2026-11-07~08의 정리(문서 이동, 참조 기능 삭제, CI 재편) 뒤 살아 있는 문서가 지금 코드와 다른 말을 한다. - 현재 계약 문서 둘과 스타터 문서가 기록(docs/design/)을 정본으로 가리킨다. 정본을 frontend-application-foundation.md·src/bootstrap/, 패턴 표·계층 규칙으로 바꾸고 설계서는 배경으로 둔다(1112/02-06). - 실시간 대응표 둘(짝 백엔드 출구, poll attempt 결과)이 기록에만 있었다. optional-adapter-recipes.md로 옮기고 코드 주석·매뉴얼 03·설계서 머리 블록이 옮긴 곳을 가리킨다(1112/09-02). - 실행 격리 변수 목록을 설계 기록이 아니라 scripts/lib/run-isolation.ts로 가리킨다(1112/08-17). - 계약 소유 절 이름(「판단 규칙」), pin 대조 시험의 게이트(005·007), drift 검사 범위(1112/02-07). INVENTORY 머리의 손 숫자와 지킬 수 없는 꼬리 문장(1112/02-08). - 검증 안내: 검사기를 바꾸면 FE-GATE-029, 문서면 desktop verify:documentation(1112/08-05, 08-04). FE-GATE-012는 merge 단계다 (08-16). N6이 알리는 파일을 좁혀 적는다(08-10). 한 파일 시험은 verify.sh exec(08-11). 문서 검사 범위의 손 사본을 정본 한 곳으로(08-07). - create:feature 참조의 Next: 3과 되돌리기(08-08), 손으로 옮긴 숫자 (08-19), 라운드 없는 리뷰 ID 17곳에 0925를 붙인다(08-15). - secret scan 범위 설명(1112/07-03), lab이 기능 라우트를 읽는 문장 (1103/16-06), README 동기화 기준점·제품 소유 파일·선택 기능 결함 몫 (0929/14-02, 14-03, 13-10), 커밋을 다시 지은 모든 통합의 해시 대조 (1106/14-02). 고른 방법: 문장을 코드에 맞춘다. 표는 옮기고 숫자는 정본을 가리킨다. 버린 대안: 기록 문서 본문 고치기(기록은 머리 블록만 고친다). 위험·한계: 문서 검사 범위 목록을 지운 ci-quality-gates.md는 이제 docs/README.md 5절과 gates.md 7절을 읽어야 한다. 매뉴얼 02 7절 업로드 예의 declare module 문제(1112/09-01)는 고치는 방향이 check:architecture 규칙과 부딪쳐 결정 대기로 남긴다. 검증: scripts/verify.sh docs(노트북) 통과. desktop verify:documentation과 FE-GATE-005(문서를 읽는 시험)는 PR 본문에 적는다. Refs: 1112/02-06, 1112/02-07, 1112/02-08, 1112/07-03, 1112/08-04, 1112/08-05, 1112/08-07, 1112/08-08, 1112/08-10, 1112/08-11, 1112/08-15, 1112/08-16, 1112/08-17, 1112/08-19, 1112/09-02, 1103/16-06, 0929/14-02, 0929/14-03, 0929/13-10, 1106/14-02
개발 매뉴얼
이 폴더는 이 템플릿으로 만든 프로젝트에 새 기능 하나를 추가하는 절차를 적는다. 기능 하나는 화면(라우트와 페이지)과 그 화면이 쓰는 API 호출을 함께 뜻한다.
시작은 corepack pnpm create:feature <id>다. 이 명령이 모든 merge 게이트를 통과하도록 만든 가장 작은 기능을 만든다. 명령이 출력하는 Next:의 초기 JS 기록 다시 쓰기까지 해야 통과한다(브라우저 게이트는 드릴 밖, docs/manual/reference/create-feature.md).
그 뒤 이 매뉴얼의 단계대로 뼈대를 실제 기능으로 바꾼다.
누가 읽는가
- 이 템플릿을 복사한 제품 팀의 프론트엔드 개발자.
- 기능을 만드는 AI 에이전트. 단계마다 "쓸 스킬"을 적었다.
- 스킬: Claude Code가 부르는 작업 지침의 이름이다. 사람이 읽을 때는 건너뛰어도 된다.
전제: 루트 README.md의 「시작하기」대로 로컬에서 앱이 뜬다.
읽는 순서
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
- route ID:
- 다른 repo의 계약 표. 백엔드 멱등성 응답 표는 위 파일 §2가 정본이다. 위치만 적는다.
- 작업 이력.
docs/reviews/와docs/history/는 복사한 프로젝트가 지울 수 있다. 이 매뉴얼은 그 문서에 기대지 않는다.
지금 구조가 아닌 설명은 링크하지 않는다.
docs/design/2026-07-26-frontend-ports-adapters-and-boundaries-design.md의 "7. 권장 목표 디렉터리 구조".- 목표안이다. 지금 기능 폴더 구조와 다르다.
- 지금 구조는
docs/architecture/layers.md가 정본이다.
docs/architecture/starter-experience.md의 예전 "폴더 밖 수정" 4행 표와 "governance는 바뀌지 않는다" 문장(2026-11-01 리뷰 시점 판).- 그 판은 실제로 고쳐야 하는 파일을 다 적지 않았다.
- 지금 판의 "feature 추가" 절 표가 정본이다. 03 문서가 이 표를 링크한다.
- 템플릿이 예전에 두던 참조 샘플 기능과 예제 화면을 가리키는 문서와 리뷰 기록.
- 그 샘플은 지웠다. 이 매뉴얼의 예시는 생성 명령 출력과 매뉴얼 안 코드 조각이다(
tests/unit/manual-code-blocks.test.ts가 시험한다).
- 그 샘플은 지웠다. 이 매뉴얼의 예시는 생성 명령 출력과 매뉴얼 안 코드 조각이다(
문서와 코드가 다를 때
코드가 맞다. 이 매뉴얼은 주장이고, 근거는 코드·설정·실행 결과다.
verify:documentation(FE-GATE-017)이 이 폴더(reference/ 포함)의 모든 문서에 적힌 경로·명령·게이트 ID가 있는지 검사한다(docs/README.md 「5. 문서 검사」).
설명이 코드와 맞는지는 검사하지 않는다.
플랫폼 규칙(예산·실행·검증·텔레메트리)의 근거는 docs/architecture/의 scale-architecture.md에 있다. 이 매뉴얼은 scale-architecture.md §24처럼 절 번호로 가리킨다.