문제: pin(45d2a478)이 백엔드 main보다 한참 뒤라 drift 검사가 exit 1이다. 그사이 백엔드가 폴더를 다시 배치하고(scaffold 원본 셋의 경로) 샘플을 지웠다. 계약 문서 6.1절 근거 파일 넷과 위치 목록이 main에 없고, 매뉴얼 04는 pin과 다른 bbe944bd를 기준이라 적는다. Fileserver 업로드 client의 게시 전 5xx 표는 pin 대조 밖이다(1105/01-02). 백엔드 697e62e8c부터 fileserver의 permit·pool 포화가 429에서 503 SERVER_BUSY로 바뀌어, client는 작업 전에 거절된 업로드를 결과 불명으로 읽는다. 고른 방법(R9-D4): - pin, 답 표 source, 표 사본(--write-excerpt)을 d32b4b53으로 옮긴다. §4의 새 행 404 OPERATION_NOT_FOUND는 durable operation 조회의 답이라 notCopied에 이유와 함께 둔다. - scaffold 원본 세 경로를 새 위치로 고친다(내용 0줄 변경 확인). - pin에 backend.codeSources를 더한다. Fileserver code 파일과 게시 전 5xx 표(codes)를 적고, readers에 fileserver-upload.ts를 넣는다. drift 검사가 그 파일들의 변경과, pin 커밋에 없는 경로(옮겨진 파일)를 알린다. pin 시험이 client 표와 pin 사본을 양쪽으로 대조한다. - NOT_APPLIED_5XX_CODES에 SERVER_BUSY를 더한다. raise 자리 둘 (TransferAdmissionController, BlockingTransferExecutor)이 모두 작업 전이다. - 6.1절 표의 백엔드 파일:줄을 d32b4b53에서 다시 찾았다. 판정은 같다. 샘플과 함께 사라진 근거(참조 도메인 행, WorkLogWebMapper 등)는 뺐고, 새 출처(PatchBodies, 알림 컨트롤러 필드 거절)를 적었다. - 매뉴얼 04의 기준을 pin으로 바꾸고 백엔드 경로 셋을 고친다. 버린 대안: 문서만 옛 pin 기준으로 맞추기 — drift 검사는 계속 막힌다. 위험·한계: V3 경로의 503 SERVER_BUSY는 상태만 정해진 모든 503에도 붙어 code로 단계를 가를 수 없다. 그래서 V3 표에 넣지 않고 결과 불명 쪽에 둔다(6.1절). 백엔드 main은 계속 움직이므로 다음 백엔드 병합 뒤 drift가 다시 1일 수 있다(설계된 신호). 검증: 노트북, 공유 clone(d32b4b53)으로 node scripts/check-backend-contract-drift.ts --backend <clone>: 옮기기 전 exit 1(문서·scaffold 4건), 옮긴 뒤 exit 0. desktop RED — pin·drift· 업로드 표 시험이 고치기 전 코드에서 실패 (/tmp/claude-gates/r9b-pr1-red/exec_node.log). merge 단계는 PR 본문. Refs: 1112/02-05, 1112/08-18, 1105/01-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처럼 절 번호로 가리킨다.