작업 가이드와 문서의 경계를 다시 긋는 설계

작성일: 2026-08-19 상태: 사용자 승인(경계 재설정 + 검사 실행 절 신설, 노출은 브라우저 검사에 한정)

배경

사용자가 두 공개 화면을 읽고 "중복된 느낌"이라고 말했다. 읽어보니 느낌이 아니라 사실이다.

두 화면은 원래 성격이 다르게 설계됐다. /guide는 규정이다 — 앞으로 이렇게 일하라. /docs는 자취다 — 실제로 그렇게 일해본 기록이고, 그래서 걸린 지점까지 감추지 않고 적는다. 이 구분은 지금도 유효하다.

문제는 두 화면이 같은 것을 각각 그린다는 데 있다.

• 통과 조건을 양쪽이 다 찍는다. /docs의 모든 단계 카드가 gateForStep으로 /guide의 게이트 문자열을 그대로 다시 렌더한다.
• SM 아홉 단계는 거의 완전히 겹친다. /guide가 improvementJourney를 직접 들여와 단계명·통과 조건·읽는 것·남기는 것을 그린다. /docs가 그리는 것과 같은 데이터, 같은 문자열이다. 차이는 /docs가 실물 문서와 걸린 지점을 덧붙이는 것뿐이다.
• 08-18 변경이 경계를 더 흐렸다. 그때 /guide에 단계별 문서 슬롯을 넣으면서, 원래 /docs의 몫이던 "이 단계가 남기는 문서"가 /guide로 넘어왔다.

즉 /guide가 /docs 쪽으로 자라났고 /docs는 /guide의 규정을 복창한다. 각자 고유한 것이 분명히 있는데도 겹친 면적이 커서 중복으로 읽힌다.

읽는 과정에서 결함도 하나 나왔다. /docs 전체 색인의 머리글이 전체 38편으로 박혀 있는데 실제 공개 문서는 43편이다. 바로 아래 단계별 머리글은 배열 길이로 세고 있어서 대비가 뚜렷하다. 같은 날 고친 단계 이름 하드코딩과 정확히 같은 종류다 — 계산할 수 있는 값을 손으로 적어두면 언젠가 반드시 틀어진다.

관점

한 사실은 한 화면만 말한다.

/docs의 단계 카드에는 이미 "가이드에서 이 단계 설명 보기" 링크가 있다. 규정을 복창하는 대신 그 링크가 규정을 가리키게 하면 된다. 링크는 이미 있으므로 새로 만들 것이 없다.

이 경계는 /docs를 약하게 만들지 않는다. 오히려 그 화면이 자기 몫만 남긴다 — 어느 단계에 무엇이 실제로 남았고 어디서 걸렸는가. 통과 조건이 빠지면 그 화면이 무엇을 파는지가 오히려 선명해진다.

검사 실행 절을 새로 만든다

같은 사용자가 이어서 물었다. 브라우저 검사는 테스트 단계의 일인데 작업 가이드에서 그것이 어떻게 도는지가 보이지 않는다는 것이다.

기존 방침은 가이드에 구체적 명령을 적지 않는 것이었다. 가이드는 도구 중립이고, 명령은 채워 넣을 칸으로만 두며, 실제 명령은 저장소 규칙 문서가 진다. 이번에 사용자가 이 방침을 브라우저 검사에 한해 뒤집었다. 뒤집은 이유는 타당하다 — 게이트가 "접근성·반응형 브라우저 검사"를 요구하는데, 그 검사가 무엇을 보는지가 어디에도 없으면 읽는 사람이 게이트를 통과했는지 스스로 판정할 수 없다. 통과 조건만 있고 판정 기준이 없는 셈이다.

그래서 새 절 하나를 만든다.

• 위치는 목차 여섯 번째, templates 앞이다. 게이트(02절)를 읽은 사람이 "그래서 그 검사가 뭘 보는데?"라고 물을 자리에 답이 온다.
• 내용은 도구, 명령, 뷰포트, 접근성 규칙, 무엇을 보는지, 그리고 개발 서버를 먼저 띄우지 않는다는 주의다.
• 노출은 브라우저 검사 하나에 한정한다. RED/GREEN 명령이나 검증 계열 명령은 지금처럼 채워 넣을 칸으로 둔다. 도구 이름이 화면에 박히는 자리를 한 곳으로 묶어, 도구를 바꿀 때 고칠 데가 한 군데이게 한다.
• 게이트 문구에는 넣지 않는다. 게이트는 /docs에도 흐르던 문자열이고, 도구 중립이라야 다른 팀이 자기 도구로 같은 순서를 밟을 수 있다. 도구 이름은 새 절 안에만 둔다.

범위

포함:

• content/guide.ts — browserCheck 신설, guideSections에 항목 추가
• app/guide/page.tsx — 새 절 렌더
• app/docs/page.tsx — 단계 카드에서 통과 조건·읽는 것·남기는 것 렌더 제거, 색인 머리글 편수를 계산값으로
• content/journey.ts — /docs가 더는 쓰지 않는 필드 정리
• 위 변경을 요구하는 단위·통합·브라우저 테스트

제외:

• 게이트 문구 자체의 수정. 규정 내용은 이번에 바꾸지 않는다.
• 문서 배치와 편수. 43편 그대로다.
• /guide의 단계별 문서 슬롯. 08-18에 사용자가 승인한 구조이고, 그 슬롯은 "이 단계가 남겨야 할 문서"라는 규정 쪽 정보라 경계에 어긋나지 않는다.
• 나머지 두 단계 이름의 줄임말(격리 구현→구현, 통합 배포→배포·운영). 성격을 오해시키지 않아 별건으로 둔다.

되돌릴 수 없는 것

/docs에서 통과 조건을 걷어내면 그 화면만 보고 게이트를 알 수 없다. 이것은 의도한 손실이다. 대신 모든 단계 카드가 규정으로 가는 링크를 갖는다. 링크가 끊기면 자취만 남고 규정을 찾을 길이 없어지므로, 그 링크의 존재는 테스트로 지킨다.