Files
clean-architecture-frontend…/docs/manual
DongHyeonka 9c4cddc201 fix(a11y): 한 자원을 읽는 라우트가 기록 없이 통과로 세지면 report가 실패한다
문제: a11y.json의 notChecked는 접근성 spec이 남긴 기록만으로 정해졌다.
기록이 없으면 "검사함"이었고, 어느 라우트에 기록이 있어야 하는지는 spec
말고 아무도 몰랐다. 리뷰 11-R2에서 실패 화면 분기의 기록 호출 reason을
null로 바꾸자 라우트 test 10건, write-a11y-report.ts, 증거 schema가 모두
통과하고 a11y.json이 상세 라우트를 scope(통과)에 넣고 notChecked: []를
적었다. 1103/11-01이 고친 거짓 주장이 한 줄로 돌아온다. 같은 실행 뒤 지난
실행의 기록 파일도 디렉터리에 남아 있었다.

고른 방법: 리뷰의 (다)와 기록 초기화.
- scripts/lib/a11y-data-state.ts의 oneResourceReadRoutes가 설치된
  descriptor만으로 "실패 화면으로만 볼 수 있는 라우트"를 찾는다. 로그인이
  필요한 라우트의 paramsSchema가, 경로 파라미터가 있고 빈 목록을 거부하는
  GET의 입력 스키마일 때다. GET 쪽 규칙은
  tests/e2e/support/installed-api-answers.ts가 답하는 규칙과 같다.
  참조 기능 상세와 create:feature --with-create 상세는 GET과 같은
  <Pascal>Params를 쓰므로 이 규칙에 든다.
- write-a11y-report.ts는 그 라우트가 기록(notChecked)에 없으면
  `a11y.json not written:`과 라우트·operation을 찍고 rc=1로 끝난다.
  a11y.json은 쓰지 않는다. test:a11y(FE-GATE-009)가 실패한다.
- accessibility.spec.ts의 라우트 test는 시작할 때 자기 기록을 지운다.
  기록 호출에 닿지 못한 실행이 지난 실행의 기록을 그대로 쓰지 않는다.
  엔진 셋이 같은 파일을 쓰지만 각 엔진은 지운 뒤에만 쓰고, 실행 중에
  기록을 읽는 곳이 없어 순서가 섞여도 결과가 같다.
- 단위 테스트: 가짜 descriptor로 규칙(목록·경로 아래 목록·DELETE·공개
  라우트 제외)과 거절(null 기록은 거절, 기록이 있으면 통과, 기대 밖 기록은
  허용). 참조 기능 테스트가 실제 descriptor에서 REFERENCE_RESOURCE_DETAIL
  하나가 나오는지 본다. 이 줄이 없으면 규칙이 아무것도 찾지 못해도
  모른다. 참조 기능과 함께 지워진다.
- 11-R2 diff는 그대로 적용된다(문맥 줄 유지, 4줄 offset).
버린 대안:
- (나) 두 상태 모두 기록하고 기록 없는 라우트를 실패: 기록 삭제는 잡지만
  reason을 null로 바꾸는 11-R2는 못 잡는다. 실행 경계(TEST_RUN_ID)도
  정해야 한다.
- 증거 schema(release-artifacts.ts)에서 검사: schema 모듈이 기능
  런타임 전체(top-level await)를 불러야 하고, 그 모듈을 쓰는 스크립트가
  많다.
- spec 안에서 기록을 다시 읽어 대조: 같은 test의 두 줄을 서로 대조할
  뿐이고, 시작 시 초기화와 엔진 동시 실행이 겹치면 거짓 실패가 난다.
- 기록 호출의 모양을 바꿔 사실(읽은 operation)을 적고 report가 판정:
  11-R2 변이 자리가 사라져 리뷰 변이로 확인할 수 없다.

위험·한계: 방향은 하나다. 규칙이 찾은 라우트가 기록에 없으면 실패하고,
규칙이 못 찾는 라우트를 spec이 notChecked로 적는 것은 덜 주장하는 쪽이라
받는다. paramsSchema가 GET 입력과 다른 상세 페이지(손으로 쓴 기능)는
규칙이 찾지 못해 기록만으로 정해진다(이전과 같다). 공개 라우트는 spec이
API에 답하지 않으므로 이 규칙 밖이다. write-a11y-report.ts가 기능 런타임
전체를 불러온다(check:registries와 같은 경로). check:types:node가 그
그래프를 node 설정으로 검사한다. 노트북에서 아무것도 실행하지 않았다.

검증: desktop batch에서 확인.
node scripts/run-vitest.ts run tests/unit/a11y-report.test.ts
tests/features/reference-feature/reference-contract.test.ts
11-R2 변이와 기록 줄 삭제 변이에서 playwright(chromium, @a11y /) 뒤
node scripts/write-a11y-report.ts rc=1, 변이 없이 rc=0. corepack pnpm
test:a11y

Refs: 1106/11-01
2026-11-06 05:29:21 +09:00
..

개발 매뉴얼

이 폴더는 이 템플릿으로 만든 프로젝트에 새 기능 하나를 추가하는 절차를 적는다. 기능 하나는 화면(라우트와 페이지)과 그 화면이 쓰는 API 호출을 함께 뜻한다.

시작은 corepack pnpm create:feature <id>다. 이 명령이 모든 merge 게이트를 통과하도록 만든 가장 작은 기능을 만든다(브라우저 게이트는 드릴 밖, docs/manual/reference/create-feature.md). 그 뒤 이 매뉴얼의 단계대로 뼈대를 실제 기능으로 바꾼다.

누가 읽는가

  • 이 템플릿을 복사한 제품 팀의 프론트엔드 개발자.
  • 기능을 만드는 AI 에이전트. 단계마다 "쓸 스킬"을 적었다.
    • 스킬: Claude Code가 부르는 작업 지침의 이름이다. 사람이 읽을 때는 건너뛰어도 된다.

전제: 루트 README.md의 "Start locally"대로 로컬에서 앱이 뜬다.

읽는 순서

README (이 문서)
  → 01 작업 순서 (처음부터 끝까지 한 번)
  → 02 결정표 (단계 중 "무엇을 고를지" 막힐 때)
  → 03 기능 폴더 밖 파일 (폴더 밖을 고쳐야 할 때)
  → 04 짝 백엔드에 처음 붙이기 (로그인이 필요한 API를 처음 부를 때)
  → reference/ (명령 인자, 전역 ID, 패턴, 오류 메시지를 찾아볼 때)
문서 내용
01-add-a-feature.md 0~11단계. 단계마다 정할 것, 판단 기준, 잡는 검사와 못 잡는 것, 쓸 스킬
02-decision-tables.md context 경계, 계약 출처, 재시도 의미, 결과 불명, 인증, 페이지 템플릿, 파일 업로드
03-outside-feature-folder.md 기능 폴더 밖 파일. 생성 명령이 하는 것과 사람이 하는 것
04-paired-backend-session.md 짝 백엔드의 두 인증 모드(JWT·Keycloak, Redis session)에 맞는 세션 owner를 붙이는 법
reference/create-feature.md create:feature의 인자, 만드는 파일, 거부 조건, 출력
reference/global-ids.md 전역 ID 종류, 생성 명령이 만드는 값, 유일성 검사
reference/patterns.md 기능 개발 패턴과 예제 위치. 예제가 없는 패턴은 "없음"
reference/errors.md 생성·조립·레지스트리 검사의 실패 메시지와 고칠 파일

자주 나오는 말

  • 기능(feature): src/features/<id>/ 폴더 하나. 그 기능의 테스트는 tests/features/<id>/에 둔다.
  • context: 같은 URL 앞부분 아래에 있는 기능 묶음이다. 선언은 src/contexts/<context>/context-module.ts다.
  • 라우트 루트: context가 가진 URL 앞부분이다. 선언 파일의 CONTEXT_ROUTE_PATH가 그 값이다.
  • 생성기: scripts/generate-product-feature-index.ts. 기능·context 선언을 읽어 src/.generated/를 만든다. 모든 빌드·검사 명령이 먼저 돌린다.
  • 조립: 부팅이나 테스트 시작 때 설치된 기능의 계약·라우트·문구를 하나로 합치는 일. 중복이 있으면 여기서 실패한다.
  • 게이트: CI가 돌리는 검사 묶음이다. ID는 FE-GATE-0NN 꼴이고 정의는 config/ci/gates.json에 있다.
  • 계약 패키지: 백엔드 API의 모양과 신원(버전·digest·소스 리비전)을 담은 @org-contracts/* 패키지.
  • digest: 패키지 내용의 해시다. 같은 버전 번호로 내용이 바뀌는 것을 막는다.

공통 원칙

판단 원칙은 design-docs repo의 conventions/feature-design-principles.md(기능 설계 공통 원칙)에 있다. 프론트·백엔드 템플릿이 함께 쓰는 원칙이다. 이 매뉴얼은 원칙을 복사하지 않고 "(원칙 5)"처럼 번호로 가리킨다.

이 폴더에 두는 것

  • 이 템플릿의 파일 이름, 명령, 게이트 ID로 쓴 절차와 판단 기준.
  • 실패 메시지와 고칠 파일. 메시지는 코드의 문자열을 그대로 옮긴다.

이 폴더에 두지 않는 것

  • 두 템플릿 공통 원칙. design-docs의 원칙 문서에 둔다.
  • 목록. route ID, 오류 code, 게이트 목록을 여기에 적지 않는다. 정본 위치만 적는다(원칙 8).
    • route ID: src/features/installed-feature-contracts.ts의 ROUTE_REGISTRY
    • 게이트: config/ci/gates.json
    • 백엔드 오류 code와 멱등성 응답: 백엔드 템플릿의 clean-architecture-backend-template/docs/web/http-contract.md
  • 다른 repo의 계약 표. 백엔드 멱등성 응답 표는 위 파일 §2가 정본이다. 위치만 적는다.
  • 작업 이력. docs/reviews/와 docs/superpowers/는 복사한 프로젝트가 지울 수 있다. 이 매뉴얼은 그 문서에 기대지 않는다.

지금 구조가 아닌 설명은 링크하지 않는다.

  • docs/architecture/frontend-ports-adapters-and-boundaries.md의 "7. 권장 목표 디렉터리 구조".
    • 목표안이다. 지금 기능 폴더 구조와 다르다.
    • 지금 구조는 docs/architecture/layers.md가 정본이다.
  • docs/architecture/starter-experience.md의 예전 "폴더 밖 수정" 4행 표와 "governance는 바뀌지 않는다" 문장(2026-11-01 리뷰 시점 판).
    • 그 판은 실제로 고쳐야 하는 파일을 다 적지 않았다.
    • 지금 판의 "Adding a feature" 절 표가 정본이다. 03 문서가 이 표를 링크한다.
  • 참조 기능 페이지의 경로 문자열과 route 입력 cast.
    • 지금은 고쳐졌다. 그래도 이 매뉴얼의 예시는 route ID와 buildRouteUrl로만 쓴다.

문서와 코드가 다를 때

코드가 맞다. 이 매뉴얼은 주장이고, 근거는 코드·설정·실행 결과다.

docs/README.md §1에서 이 폴더를 링크하면 verify:documentation(FE-GATE-017)이 이 폴더 문서에 적힌 경로·명령·게이트 ID가 있는지 검사한다. 폴더 링크는 그 폴더 바로 아래 .md만 검사한다. reference/도 검사하려면 따로 링크한다. 설명이 코드와 맞는지는 검사하지 않는다.

플랫폼 규칙(예산·실행·검증·텔레메트리)의 근거는 docs/architecture/의 scale-architecture.md에 있다. 이 매뉴얼은 scale-architecture.md §24처럼 절 번호로 가리킨다.