Files
clean-architecture-frontend…/docs
DongHyeonka 923b29be6c fix(fanout): 실패 줄에 두 탈출 방법을, 결과 줄에 검토된 예외 수를 적는다
문제: fanout 검사의 실패 줄은 `FAIL <file>:<line> <call> inside
<context>`뿐이라, 제품 팀은 메시지만 보고 커서 runtime이나 검토 주석이라는
두 방법을 알 수 없었다. `// fanout-reviewed:` 주석으로 넘긴 호출 수도
출력하지 않았고, 허용 fixture는 bulk 읽기 하나였다(0929 결정 (가)를 하지
않았다).

고친 것: 실패 줄이 기능 `adapters/`의 `createCursorPaginationRuntime`과
같은 줄의 `// fanout-reviewed: <이유>`를 함께 적는다. 결과 줄과 fixture
줄이 검토된 예외의 수와 위치·이유를 적는다. 허용 fixture에 주석 달린 커서
루프를 더하고, fixture 실행은 그것이 예외로 세어져야 통과한다. 머리 주석과
`docs/operations/ci-quality-gates.md`에 미탐 범위를 적었다.

위험·한계: 휴리스틱 자체(receiver 이름)는 그대로다(1105의 재설계 (나)는
하지 않았다).

검증: desktop `node scripts/run-vitest.ts run
tests/architecture/request-fanout.test.ts` 통과. 검사기를 기준 커밋으로
되돌리면 새 시험 셋이 실패한다.

Refs: 0929/12-01
2026-11-13 21:49:58 +09:00
..

docs

저장소의 문서는 이 폴더 아래에 있다(루트 README.md, CHANGELOG.md 등 몇 개는 밖에 있다). 이 README는 두 가지를 정한다.

  • 어떤 문서가 어느 폴더에 있나: 1절 「문서 지도」. 지금 있는 모든 문서 폴더를 덮는다.
  • 문서의 수명에 따라 무엇을 어떤 언어로 어떻게 고치나: 2절부터.

규칙의 정본은 design-docs 저장소의 conventions/docs-system.md다. 이 README는 그 규칙을 이 repo에 적용한 내용이고, 이 템플릿을 복사한 프로젝트도 이 README를 따른다. 파일 목록과 개수는 여기에 적지 않는다. 적으면 다음 문서가 더해지는 순간 틀린 글이 된다. 파일은 폴더를 직접 읽는다.

문서와 코드가 다르면 코드가 맞다.

1. 문서 지도

  • 표의 첫 칸이 폴더다(docs/ 기준 경로).
  • 새 문서 폴더를 만들면 같은 변경에서 이 지도에 행을 더한다. 폴더를 지우거나 옮기면 그 행도 고친다.
  • 문서 검사의 map이 지도에 없는 폴더와, 지도에 있지만 없는 폴더를 막는다(5절).

처음 읽을 문서

문서 정하는 것
../AGENTS.md 규칙의 정본과 지도: 꼭 지킬 것, 맡은 일마다 읽을 playbook, 검증 진입점 scripts/verify.sh
work/, work/reference/ 작업 매뉴얼: 맡은 일마다의 playbook과 기준(완료 기준은 work/improve.md 5절)
README.md 프로젝트 구조, 시작하기, 런타임 설정과 배포 변수, 기능 켜고 끄기와 지원 범위, 검증과 CI, 새 서비스로 시작하기, 원본 업데이트 반영
architecture/frontend-application-foundation.md 이 repo의 역할(스타터 + 재사용 capability)과 기본·선택의 경계
architecture/layers.md, architecture/overview.md 계층과 import 방향. check:architecture가 검사한다
architecture/starter-experience.md 기본 라우트, 인증 모드, 기능 추가·제거 절차
manual/ 새 기능을 더하는 순서와 판단 기준, create:feature(manual/reference/)
operations/ci-quality-gates.md, testing/taxonomy.md 게이트, 테스트 계층, 새 프로젝트가 초기화할 기준선

매뉴얼

일하는 순서와 판단 지점이다. 사람과 AI 세션이 같이 쓴다.

폴더 무엇
work/ 작업 매뉴얼: 새 기능, 리뷰·수정·리팩터링, 조사·설계, 문서, 운영, 일 나누기의 playbook. work/reference/에 게이트·구조·테스트·리뷰 기준과 결정 색인, work/evidence.md에 매뉴얼 규칙의 근거 기록
manual/ 개발 매뉴얼: 새 기능 하나를 더하는 0~11단계, 결정표, 기능 폴더 밖 파일, 짝 백엔드에 붙이기. manual/reference/에 명령 인자, 전역 ID, 패턴, 오류 메시지
ledger/ 작업 예측·실측 장부(ledger/estimates.jsonl, 형식은 ledger/README.md)

현재 계약

지금 코드가 지키는 규칙이다. 코드와 같은 변경에서 고친다.

폴더 무엇
architecture/ 계층과 import 규칙(architecture/layers.md), 플랫폼의 역할, 스타터, recipe 절차, 정적 배포, 계약 소유, 규모 설계(architecture/scale-architecture.md, 코드 주석의 scale-architecture.md §N이 가리킨다), 짝 백엔드 계약(architecture/backend-api-and-server-state-contract.md 4.1·6·6.1절이 실행 규칙. 기준 커밋은 config/contracts/backend-contract-pin.json), 2026-07-18 도식 리뷰 기록의 사본(architecture/review-evidence.md, architecture/review-ledger.json)
contracts/ 계약 호환 규칙(읽는 쪽을 먼저 배포한다)
security/ 브라우저 보안 경계와 공급망
styling/ 디자인 토큰
accessibility/ 수동 접근성 검토 체크리스트와 라우트별 검토 기록(accessibility/route-reviews/)
testing/ 테스트 계층(taxonomy)과 새 프로젝트가 초기화할 기준선

운영

폴더 무엇
operations/ CI 품질 게이트, capability별 복구 절차, 릴리스·캐시 롤백, 성능 증거, 2026-08-14 adapter 재검토의 처리 원장(operations/adapter-remediation-ledger.md)
runbooks/ 오류 code별 장애 대응 runbook(FE-RB-00N). 등록은 config/runbooks/runbooks.json

결정 기록

폴더 무엇
adr/ 결정 기록(VD). 번호는 옮기기 전과 같다(VD-NN-<주제>.md). 2026-11-08에 architecture 아래 decisions 폴더에서 옮겼다

설계와 기록

설계서와 기록은 쓴 때의 글이다. 지금 동작을 설명하지 않는다. 그래서 살아 있는 문서와 다른 폴더에 둔다.

폴더 무엇
design/ 설계서. YYYY-MM-DD-<주제>-design.md. 2026-11-08에 옛 superpowers 폴더의 specs와 architecture/의 목표 설계를 옮겼다
history/plans/ 계획서. 2026-09-25 리뷰 수정 라운드의 요구사항(SPEC.md)과 작업 목록도 여기 있다
history/evidence/ 작업 단계의 증거·체크포인트
reviews/ 리뷰 결과. 라운드마다 폴더 하나(README가 결정과 남은 것을 적는다) 또는 리뷰 문서 하나. 리뷰 가이드와 실행 체크리스트는 design-docs 저장소로 옮겼고, 여기에는 정본 위치를 알려 주는 포인터 둘이 있다
  • 계획서 본문에는 그때 계획한 경로와 명령이 그대로 남아 있다. 계획서를 나중에 고치지 않는 이유는, 고치면 계획의 기록이 아니라 결과를 계획처럼 보이게 만든 글이 되기 때문이다.
  • history/와 reviews/는 복사한 프로젝트가 지워도 된다(루트 README.md 「복사한 뒤 지워도 되는 것」). 예외는 reviews/adapters/다: reviews/adapters/INVENTORY.md는 check:adapter-inventory(FE-GATE-010)가 src/adapters와 대조하는 살아 있는 목록이다.
  • design/과 adr/은 코드 주석이 근거로 가리키므로 지우지 않는다.

폴더 밖 문서

문서 무엇
../README.md 루트 README. 6절의 필수 절을 가진다
../CHANGELOG.md 템플릿 버전 사이의 변경. 지난 상태를 적는 문서라 문서 검사의 참조·숫자 검사는 보지 않는다
../AGENTS.md 규칙의 정본과 지도. src/ 계층 폴더마다 지역 규칙 AGENTS.md가 있다
루트 CLAUDE.md AGENTS.md를 가져오고 Claude Code 전용 줄만 둔다. 경로별 규칙·스킬·서브에이전트는 .claude/
vision.md, problem-statement.md 비전과 문제 정의. 소유자가 채우는 양식이다
루트 PRODUCT.md 디자인 도구가 읽는 제품 맥락
../src/adapters/browser-transfer/image-cdn/README.md Image CDN adapter의 모듈 README

게이트가 읽는 파일

지우거나 옮기면 게이트가 실패한다.

파일 읽는 명령
이 파일, architecture/review-ledger.json, architecture/review-evidence.md verify:documentation (FE-GATE-017)
라우트별 수동 접근성 기록(accessibility/route-reviews/<ROUTE_ID>.md) verify:documentation (FE-GATE-017), review:a11y-manual (FE-GATE-009, FE-GATE-028)
reviews/adapters/INVENTORY.md check:adapter-inventory (FE-GATE-010)
operations/adapter-remediation-ledger.md, operations/adapter-remediation-dispositions.json check:remediation-ledger (게이트 밖. 이유는 config/ci/ungated-scripts.json)
architecture/backend-api-and-server-state-contract.md 6.1절 표 tests/unit/backend-contract-pin-document.test.ts (FE-GATE-005)
architecture/starter-experience.md의 기능 폴더 밖 파일 표, manual/03-outside-feature-folder.md A절 tests/unit/feature-tracked-files.test.ts (FE-GATE-005)
manual/의 표시한 코드 블록과 manual/04-paired-backend-session.md 3.2절 tests/unit/manual-code-blocks.test.ts, tests/unit/manual-paired-backend-settings.test.ts (FE-GATE-005)

2. 문서 수명과 언어

수명 문서 위치 언어 고치는 법
살아 있음 README, AGENTS.md(루트와 src/ 계층 폴더), CLAUDE.md, .claude/의 규칙·스킬, 매뉴얼(work/, manual/), 장부(ledger/), vision.md·problem-statement.md, 현재 계약(architecture/, contracts/, security/, styling/, accessibility/, testing/), 운영(operations/, runbooks/), reviews/adapters/INVENTORY.md, 모듈 README, CHANGELOG.md 제자리 한국어 코드와 같은 변경에서 고친다(4절)
결정 결정 기록(VD) adr/ 한국어 본문은 고치지 않는다. 일부가 바뀌면 상태를 「채택(보완)」으로 하고 맨 아래에 날짜가 있는 「보완」 절을 덧붙인다. 크게 바뀌면 새 VD를 쓰고 옛 VD를 「대체됨」으로 한다
기록 설계서, 계획서, 증거, 리뷰 design/, history/, reviews/ 머리 블록은 한국어, 본문은 쓴 때의 원문 머리 블록의 칸만 고친다
  • 살아 있는 문서와 결정 기록의 본문은 한국어로 쓴다. 설정 파일의 사람이 읽는 설명 칸(recipe 카탈로그, runbook 등록)도 한국어다.
  • 원문으로 두는 것: 코드 식별자, 명령, 경로, 설정 키, 오류 코드, 로그·출력 인용, 외부 문서 인용, 제품 이름.
  • 용어는 자연스러운 한국어 → 한국어(영어) → 영어 그대로 순으로 고른다. 처음 나올 때 한 번 병기한다. 이 repo가 영어로 쓰는 말(adapter, port, capability, recipe, feature, context, slice, registry, gate 등)은 영어로 둔다.
  • 문체는 「~한다」다. 한 문서 안에서 「~합니다」와 섞지 않는다.
  • 2026-11-08에 살아 있는 문서를 모두 한국어로 옮겼다. 문서 검사의 예외 목록은 비어 있다(5절).
  • accessibility/route-reviews/의 라우트별 기록은 문서가 아니라 정해진 영어 키 형식의 게이트 입력이다(scripts/lib/manual-a11y-evidence.ts). 문서 검사가 보지 않는다.

3. 기록 문서의 머리 블록

design/, history/, adr/의 .md 파일은 맨 위에 이 블록을 둔다. 블록을 빼면 원문 그대로다(옮길 때 깨진 상대 링크의 대상만 고쳤다).

<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
> **기록 · 설계서** 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.

- 상태: 구현됨
- 작성일: 2026-08-01
- 요약: 한국어 한 문장
- 현재 정본: `docs/architecture/layers.md`
- 대체됨: `docs/design/<대체한 문서>.md`
<!-- 머리 블록 끝 -->
  • 종류는 폴더가 정하고 둘째 줄에 굵게 적는다: design/ 설계서, history/plans/ 계획서, history/evidence/ 증거. 결정 기록(adr/)의 둘째 줄은 > **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.다. VD는 처음부터 한국어로 썼고 번역하지 않았다. 나중에 본문을 번역하면 「원문이다」 대신 「내용이다(번역은 뜻을 바꾸지 않았다)」로 쓴다.

  • 상태는 종류마다 고정 어휘다.

    종류 상태
    설계서 제안 · 채택 · 구현됨 · 보류 · 폐기 · 대체됨 · 확인 안 함
    결정 기록 제안 · 채택 · 채택(보완) · 폐기 · 대체됨
    계획서 실행 중 · 끝남 · 중단 · 대체됨 · 확인 안 함
    증거 보관
  • 「현재 정본」은 지금 동작을 설명하는 살아 있는 문서나 코드의 경로다. 여럿이면 쉼표로 잇고, 없으면 「없음 — 이유」로 쓴다.

  • 「대체됨」은 상태가 대체됨일 때 대체한 문서의 경로다. 이 문서가 다른 문서를 대체했으면 「대체」 칸에 그 경로를 쓴다.

  • 상태는 그 결정을 바꾼 변경이 같이 바꾼다. 기능을 지우는 커밋이 그 기능의 설계서를 「폐기」나 「대체됨」으로 바꾼다. 새 설계서·결정 기록은 처음부터 블록을 달고 쓴다(보통 「제안」).

  • 2026-11-08에 처음 단 상태는 원래 상태 줄을 기계로 바꾼 값이다: Accepted·Approved·확정·승인·정본 → 채택, Superseded → 대체됨, Proposed → 제안, implemented → 구현됨, 날짜가 붙은 보완 메모가 본문에 있는 VD → 채택(보완). 상태 줄이 없던 설계서와 체크 상자가 모두 표시되지 않은 계획서는 「확인 안 함」이다.

  • .md가 아닌 파일(레인 준비 셸 스크립트)에는 달지 않는다. 같은 폴더 문서의 블록이 그 파일을 설명한다.

  • 리뷰(reviews/)는 아직 머리 블록을 요구하지 않는다.

4. 문서와 코드를 같은 변경에서 고친다

  • 코드나 규칙을 바꾸는 변경이 그것을 설명하는 살아 있는 문서도 고친다. 찾는 법: git grep -n '<바꾼 이름>' -- '*.md'.
  • 살아 있는 문서는 지금 있는 것만 쓴다. 지운 타입·경로·명령은 CHANGELOG.md에 쓴다. 살아 있는 문서 안에서 꼭 써야 하면 > 이력 으로 시작하는 인용 블록 안에 쓴다. 문서 검사는 그 블록의 문체를 보지 않는다.
  • 숫자·버전을 복사하지 않는다. 프레임워크 버전은 package.json과 .nvmrc, 게이트 목록은 config/ci/gates.json, recipe 목록은 config/recipes/frontend-capability-recipes.json, adapter 파일 목록은 reviews/adapters/INVENTORY.md를 가리킨다.
  • 루트 README는 「프로젝트 구조」와 「문서 지도」 절을 반드시 둔다. 전체 절 목록과 순서의 정본은 design-docs conventions/docs-system.md 6.1절이고, 문서 검사의 readme가 그 목록(scripts/lib/docs-system.ts의 README_SECTIONS)을 본다.

5. 문서 검사

verify:documentation(FE-GATE-017)이 위 규칙 중 기계로 볼 수 있는 것을 본다. 하나라도 걸리면 실패한다. 경로 필터가 없다: 코드에서 파일이나 script를 지우는 변경이 그 변경과 상관없는 문서를 낡게 만든다.

  • pull request에서 실패하게 하는 곳은 merge 단계 FE-GATE-005다. 그 안의 tests/unit/documentation-readiness.test.ts가 이 repo를 그대로 두고 verify:documentation을 한 번 돌린다. FE-GATE-017 job 자체는 documentation 단계를 고른 workflow_dispatch에서만 돈다(config/ci/gates.json의 documentation_gate).
검사 보는 것
language 살아 있는 문서와 결정 기록 본문이 한국어인가. 코드·명령·경로·링크·인용은 세지 않고, 영어 낱말 3개 이상이면서 한글 덩어리 비율 0.3 미만이면 영어다(보고 언어 훅 H11과 같은 판정)
head 기록과 결정 기록 맨 위의 머리 블록: 칸, 상태 어휘, 날짜, 한국어 요약, 현재 정본·대체됨 경로가 지금 있는지
document references 살아 있는 문서의 인라인 코드·셸 코드 블록 안 repo 경로, 마크다운 링크 대상, package script 이름, FE-GATE ID가 지금 있는가. 짝 백엔드 경로는 config/contracts/backend-contract-pin.json이 고정한 커밋의 트리에서 찾는다
number 살아 있는 문서가 프레임워크 버전이나 게이트·recipe·adapter 개수를 복사했는가. 결정 기록, 기록, CHANGELOG.md는 보지 않는다
map 이 README의 1절 지도가 docs/ 아래 모든 폴더를 덮는가(표 첫 칸의 폴더/). 파일 없이 폴더만 가진 묶음 폴더(history/)는 그 바로 아래 폴더가 대신한다. 지도에 있지만 없는 폴더도 실패다
readme 루트 README가 첫 줄 제목, 그 아래 한 문단, 정해진 ## 절을 정해진 순서로 가지는가
style 살아 있는 문서와 결정 기록의 문장 끝이 높임(「~합니다」「~하세요」)이 아닌가. 코드, 따옴표·낫표 안 인용, > 이력 블록은 보지 않는다
  • 그 밖에 같은 명령이 루트 README의 런타임 변수 표, 입구 문서의 src/ 폴더 설명(architecture/layers.md 표와 글자가 같아야 한다), 수동 접근성 기록의 범위, 2026-07-18 도식 리뷰 사본 둘의 일치를 본다.
  • 규칙과 판정의 정본은 scripts/lib/docs-system.ts(검사 여섯)와 scripts/verify-documentation-readiness.ts(참조와 그 밖의 검사)다. 백엔드 템플릿의 문서 검사기(그 repo의 check-docs.py)를 같은 이름·문턱으로 옮긴 것이다.
  • 검사 자신의 시험: tests/unit/docs-system.test.ts, tests/unit/documentation-readiness.test.ts.
  • 예외 목록 scripts/docs-system-exceptions.txt는 비어 있고 줄기만 한다. 목록에 새 줄을 더하면 실패한다(줄마다 scripts/lib/docs-system.ts의 FROZEN에 지문이 있어야 하는데, FROZEN이 비어 있다). 기준선을 늘리는 것은 규칙을 바꾸는 일이라 소유자 결정이 필요하다.
  • 복사한 프로젝트가 지운 기록(history/, reviews/)과 지운 샘플 기능의 경로는 없어도 된다. git이 무시하는 생성 산출물도 없어도 된다.
  • 설명·수치가 코드와 맞는지는 검사하지 않는다. 리뷰가 표본으로 대조한다.