브랜드 웹사이트 개발기 (2) — 기획 문서와 콘텐츠를 정확히 맞추기

ㄴ콘텐츠 정합성 작업의 첫 단계는 비교가 아니라 기준 정하기였다. 검증 지시문·기획 원본·구현 3자가 어긋난 상황을 페이지×표기 매트릭스로 전수 점검하고, 깨진 이미지는 참조 대조로 0건임을 사실로 증명한다. 1편의 멱등 마이그레이션으로 문서 카피를 정합화하고, 이미지는 교체 대신 crop과 object-fit으로 의도한 프레이밍을 맞춘다.

2편: 코드가 아니라 "정합성"이 일이었다

1편에서 PHP + SQLite 구조와 콘텐츠 관리 시스템(c() 헬퍼, 멱등 마이그레이션, DB-override)을 다뤘다. 그런데 이 브랜드 사이트를 만들며 시간이 가장 많이 든 작업은 기능 구현이 아니었다. "기획 문서가 지정한 콘텐츠가 화면에 정확히 그대로 나오는가"를 맞추는 일 — 즉 정합성(integrity) 문제였다.

브랜드 사이트는 어느 섹션에 어떤 사진과 문구가 들어갈지를 기획 문서가 정한다. 이 사이트의 경우 출처가 한 개도 아니었다. 의뢰처가 처음 준 검증 지시문, 실제 기획 원본인 여러 개의 문서 파일, 그리고 이미 만들어진 구현 코드 — 세 가지가 있었고, 셋이 서로 어긋났다. "화면을 문서에 맞춘다"는 단순해 보이는 일이, 사실은 "어느 문서가 정답인지부터 정하는" 일이었다.

이번 글은 그 정합성 작업을 순서대로 기록한다. 3자 불일치를 발견한 과정, 검증을 체계화한 방법, 그리고 1편에서 만든 멱등 마이그레이션이 어떻게 "고치는 도구"가 됐는지, 마지막으로 픽셀 단위의 이미지·레이아웃 디테일까지.

가장 큰 발견 — 세 기준이 서로 달랐다

작업 초기에 받은 검증 지시문은 어떤 콘셉트를 전제하고 있었다. "이런 슬로건, 이런 4개 사업영역, 이런 통계 숫자, 이런 핵심가치, 이런 연락처가 화면에 있어야 한다"는 기대 목록이었다. 그대로 대조했다면 "거의 다 틀렸다"고 보고했을 것이다.

그런데 실제 기획 원본 문서들을 열어 보니, 지시문이 말한 슬로건도 통계도 핵심가치도 원본 문서 어디에도 없었다. 원본은 전혀 다른 콘셉트였고, 놀랍게도 구현 코드는 그 원본 문서를 충실히 따르고 있었다. 즉 "구현이 문서를 안 지킨" 게 아니라, "의뢰처가 기억하는 콘셉트(지시문)와 실제 기획 문서가 달랐던" 것이다.

이 발견이 보고서의 0번 항목이 됐다. "진짜 리스크는 코드 결함이 아니라, 어느 기준이 정답인지 확정되지 않은 것" 이라고 못 박았다. 만약 지시문만 보고 "슬로건이 틀렸다, 통계가 없다"며 코드를 뜯어고쳤다면, 실제 기획 의도를 거꾸로 망가뜨릴 뻔했다. 정합성 작업에서 가장 먼저 할 일은 비교가 아니라 "무엇과 무엇을 비교할지(기준 정하기)" 임을 이때 배웠다.

그래서 보고서는 표로 3자를 나란히 놓았다. 항목마다 "지시문 기대 / 원본 문서 / 실제 구현 / 판정"을 적었다. 예를 들어 메인 슬로건은 지시문이 기대한 문구가 원본·구현 어디에도 없고, 대신 원본과 구현이 동일한 다른 문구를 쓰고 있었다 — 판정은 "구현은 문서와 일치, 지시문과 불일치". 이렇게 적고 나니 어디를 의뢰처와 확정해야 하는지가 한눈에 보였다.

검증을 체계화하다 — 페이지 × 표기 매트릭스

3자 대조를 머릿속으로 하면 반드시 놓친다. 그래서 페이지별로, 항목마다 표기를 붙이는 매트릭스로 검증을 구조화했다. 표기는 셋으로 단순화했다.

• 반영됨: 문서 지정과 화면이 일치
• 누락·불일치: 문서엔 있는데 화면에 없거나, 서로 다름
• 깨진 이미지: 화면이 참조하는 이미지 파일이 실제로 존재하지 않음

이 매트릭스가 만든 효과가 컸다. 첫째, 전수 점검이 강제된다. "메인의 파트너 문단", "활동 상세 4페이지의 인트로와 3카드"처럼 모든 섹션을 빠짐없이 한 칸씩 채우니, 사람 눈으로 훑을 때 건너뛰던 곳이 사라졌다. 둘째, 불일치의 "심각도"가 분리됐다. 같은 "불일치"여도 콘셉트 충돌(치명적)과 카피 한 단어 누락(경미)은 무게가 다르다. 보고서는 마지막에 우선순위 TOP 5를 따로 뽑아, "콘셉트 확정"을 1순위, "제품 명칭 혼용 표준화"를 중위, "미세 카피 누락"을 하위로 분류했다. 의뢰처가 무엇부터 결정해야 하는지가 명확해졌다.

실제로 이 매트릭스로 여러 구체적 불일치를 잡았다. 같은 제품을 어떤 페이지에선 한 이름으로, 다른 페이지에선 다른 이름으로 부르는 명칭 혼용, 메인·활동 소개·활동 상세에서 4개 제품의 노출 순서가 서로 다른 문제, 그리고 연락처·통계 자리에 플레이스홀더(02-0000-0000 같은 가짜 값) 가 남아 있는 문제. 하나하나는 작아도, 모이면 "기획대로 보이지 않는" 사이트가 된다.

깨진 이미지는 "참조 대조"로 0건임을 증명

정합성 검증에서 가장 흔한 사고는 존재하지 않는 이미지를 참조하는 것이다. 화면 코드에 assets/img/foo.jpg라고 적혀 있는데 그 파일이 없으면, 운영에서 깨진 이미지로 노출된다. 이걸 사람이 페이지를 일일이 열어 눈으로 확인하면 반드시 놓친다.

그래서 "코드가 참조하는 모든 이미지 경로" 와 "실제 자산 폴더에 있는 파일 목록" 을 대조했다. 개념은 단순하다 — 코드에서 이미지 경로를 모두 뽑아, 각 경로가 파일 시스템에 실재하는지 확인한다.

이 대조로 깨진 이미지 0건을 "주장"이 아니라 "확인된 사실"로 만들 수 있었다. 화면 코드가 참조하는 수십 개 이미지가 전부 자산 폴더에 실재했고, 사용자 업로드용 빈 디렉터리에는 정적 이미지가 없는 게 정상임도 함께 기록했다. 정합성 보고에서 "괜찮아 보인다"와 "대조해 보니 0건이다"는 신뢰도가 전혀 다르다. 기계적으로 대조 가능한 것은 기계가 대조하게 한 것이 이 작업의 핵심 원칙이었다.

고치는 도구 — 멱등 마이그레이션으로 문서 카피를 정합화

불일치를 찾았으면 고쳐야 한다. 그런데 이 사이트는 콘텐츠가 DB(site_content)에 들어 있고, 이미 운영 DB가 존재한다. 코드의 기본값만 바꾸면 신규 DB엔 반영돼도 운영 DB는 옛 값을 유지한다. 여기서 1편의 멱등 버전 마이그레이션이 정확히 해결책이 됐다.

원본 문서의 카피를 문서 그대로(verbatim) 옮겨, 한 번만 적용되는 마이그레이션 블록으로 운영 DB까지 따라잡게 했다.

카드형 콘텐츠(임팩트 카드 등)는 키-값이 아니라 행 단위라, 카테고리와 정렬 순번을 기준으로 매칭해 라벨·제목·본문을 한꺼번에 정규화했다.

이 방식의 장점은 "고침"이 곧 "버전 기록" 이 된다는 것이다. 어떤 카피를 어느 시점에 문서 기준으로 맞췄는지가 마이그레이션 블록으로 코드에 남는다. 나중에 "이 문구 왜 이렇게 됐지?"라는 질문에, 마이그레이션 블록 자체가 답이 된다. 동시에 멱등이라 운영·신규 환경이 같은 상태로 수렴한다. 1편에서 만든 인프라가 2편의 정합성 작업을 떠받친 셈이다.

단일 소스로 묶기 — 같은 정보가 두 곳에 살지 않게

정합성을 깨뜨리는 또 다른 원인은 같은 정보가 두 군데에 따로 저장되는 것이다. 이 사이트에는 '걸어온 길' 타임라인과 소식(news)이 있었는데, 둘의 내용이 사실상 겹쳤다. 타임라인용 별도 데이터와 소식 데이터를 따로 관리하면, 둘은 시간이 지나며 반드시 어긋난다.

그래서 타임라인을 소식 데이터에 연동했다. 별도 연혁 테이블 대신, 소식을 날짜 오름차순으로 읽어 타임라인으로 그린다. 운영자가 소식 한 곳만 관리하면 타임라인에도 자동 반영된다.

연동 후에는 더 이상 노출되지 않게 된 연혁 관리 화면의 라벨까지 정정했다('현재 미노출'로 표시). 데이터를 합치는 것으로 끝내지 않고, "이건 이제 화면에 안 나간다"는 사실을 관리자 화면에도 정직하게 반영한 것이다. 정합성은 화면뿐 아니라 운영자가 보는 관리 도구의 설명까지 사실과 맞아야 비로소 완성된다.

픽셀 단위의 정합성 — 이미지 crop과 레이아웃

콘텐츠 카피를 맞추고 나면, 마지막 관문은 "문서가 지정한 이미지가 의도한 프레이밍으로 보이는가" 다. 같은 이미지라도 컨테이너 비율과 crop 위치에 따라 전혀 다르게 보인다. 여기서 가장 애를 먹은 게 한 활동 상세 페이지의 배너였다.

문서가 지정한 배너 이미지는 정사각에 가까운 비율인데, 와이드 히어로 영역에 넣으니 object-position: center 기본값 탓에 위아래가 과하게 잘려 핵심 피사체가 헤드라인과 겹쳤다. 처음엔 가로 비율 사진으로 교체해 봤지만, 같은 페이지 다른 섹션의 사진과 중복되는 문제가 생겼다. 결국 "문서가 지정한 그 이미지"를 쓰되, crop 위치만 조정하는 방향으로 돌아왔다.

이 한 줄에 담긴 교훈은 "문서 지정 이미지를 바꾸지 말고, 프레이밍으로 해결하라" 이다. 이미지를 교체하면 문서 정합성이 깨지지만, crop 위치만 보정하면 "지정 이미지 유지 + 의도한 모습"을 둘 다 얻는다. 그리고 전역 CSS를 건드리지 않고 해당 배너에만 한정한 것도 중요하다. 한 화면을 고치려다 다른 화면을 망가뜨리는 건 정합성 작업에서 가장 흔한 2차 사고다.

비슷한 레이아웃 디테일이 더 있었다.

사진을 일러스트로 교체한 섹션에서, 사진용 cover(꽉 채워 잘림)를 그대로 쓰면 라인아트 가장자리가 잘려 그림이 깨진다. 16:9 비율 박스에 object-fit: contain으로 바꿔 전체가 잘림 없이 들어가게 했다. 또 임팩트 섹션의 인용문은 "세 줄로 보여야" 하는데, 제목용 큰 폰트가 박스보다 커서 줄이 제멋대로 재줄바꿈됐다. 해당 인용문에만 인라인으로 폰트 크기와 최대 폭, 줄 간격을 잡아 의도한 3줄로 떨어지게 했다. 이 역시 전역 스타일을 건드리지 않고 그 요소에만 적용했다.

이런 작업은 "기능"이 아니다. 브랜드가 의도한 대로 보이는가의 문제다. 콘텐츠가 많고 픽셀 단위의 의도가 중요한 브랜드 사이트에서는, 바로 이 맞춤이 품질을 좌우한다.

정리하며

• 브랜드 사이트의 가장 큰 작업은 코드가 아니라 "기획 문서 ↔ 화면 콘텐츠 정합성" 이었다.
• 첫 단계는 비교가 아니라 기준 정하기 였다. 의뢰처 지시문·기획 원본·구현이 3자 불일치였고, "어느 것이 정답인지 확정"하는 것을 최우선으로 보고했다. (구현은 의외로 원본 문서에 충실했다.)
• 검증을 페이지 × 표기 매트릭스(반영됨/불일치/깨진 이미지)로 구조화해 전수 점검과 심각도 분리를 강제하고, 우선순위 TOP 5로 의사결정 순서를 명확히 했다.
• 깨진 이미지는 참조 대조(코드가 가리키는 경로 ↔ 실재 파일)로 0건임을 "확인된 사실"로 증명했다. 기계로 대조 가능한 건 기계가 대조하게.
• 고침은 1편의 멱등 마이그레이션으로 처리해, 운영 DB까지 문서 카피로 정합화하고 그 변경 자체를 코드에 버전으로 남겼다.
• 중복 데이터(타임라인/소식)는 단일 소스로 연동해 어긋남을 원천 차단하고, 관리 화면 라벨까지 사실과 맞췄다.
• 이미지는 교체 대신 crop·object-fit·줄바꿈 보정으로 "문서 지정 유지 + 의도한 모습"을 동시에 얻었고, 모든 보정을 전역이 아닌 해당 요소에만 한정해 2차 사고를 막았다.

시리즈를 마치며

두 편에 걸쳐 한 브랜드 웹사이트를 정리했다.

• 1편: 서버 설정 없는 PHP + SQLite, 0-setup 부트스트랩, 멱등 마이그레이션, c() 콘텐츠 시스템과 DB-override 패턴.
• 2편: 기획 문서와 화면의 정합성 — 3자 기준 확정, 검증 매트릭스, 참조 대조, 멱등 마이그레이션을 이용한 정합화, 픽셀 단위 이미지·레이아웃 보정.

이 사이트의 결론은 분명하다. 작은 브랜드 사이트는 화려한 기술이 아니라 적정 기술로 빠르게 띄우고(1편), 콘텐츠가 기획 의도대로 정확히 보이게 만드는 것(2편) 이 핵심이었다. 그리고 두 편을 관통하는 한 문장은 이것이다 — "사람이 대조하면 놓치는 것을, 기계가 대조하게 하라." 멱등 마이그레이션이 데이터 정합을, 참조 대조가 이미지 무결성을, 단일 소스 연동이 중복 제거를 기계의 몫으로 옮겼다. 콘텐츠가 많은 사이트일수록 이 접근이 품질의 차이를 만든다.