문제 V2 클라이언트는 보낸 KEYED 요청이 503·408·425·502·504·network·timeout으로 끝나면 같은 키로 자동 재시도했다. 048f490으로 그 동작이 없어졌다. 설계 정본 (2026-07-30 closed deep design 8.3)은 KEYED 자동 재시도를 "known response status가 retry 가능하다고 package가 명시한 경우만" 허용하고, 응답 없는 network·timeout 뒤에는 금지한다. V2는 응답 없는 실패 뒤에도 보내 정본과 어긋났고, V3는 응답이 재시도를 허락해도 보내지 않아 정본보다 좁았다. 짝 백엔드는 503 IDEMPOTENCY_UNAVAILABLE을 "작업 실행 전에 거부됐다. 같은 키로 나중에 다시 보낸다"로 정한다(http-contract.md §2). 고른 방법 - backend-envelope.ts의 invitesKeyedResend: 503 + IDEMPOTENCY_UNAVAILABLE. - Envelope operation의 실패 해석에서 KEYED 명령이 그 답을 받으면 AdmissionOutcome에 keyedResend를 싣는다. 재시도 루프는 그때 retryBudget· MAX_RETRY_ATTEMPTS·상한 2 안에서 같은 frozen 요청(같은 Idempotency-Key)을 다시 보낸다. certainty는 MAYBE_APPLIED로 두어, 다 쓰면 결과 불명으로 끝나고 키를 지킨다. 버린 대안 - V2처럼 KEYED의 모든 재시도 가능 status·network 실패에서 재시도: 정본 8.3이 응답 없는 실패 뒤 재시도를 금지한다. - 409 IDEMPOTENT_IN_FLIGHT도 자동 재시도: 처리 중 요청은 47fec5c의 사용자 재전송(Retry-After 대기)이 이미 같은 키로 다룬다. V2도 409는 자동으로 다시 보내지 않았다. 위험·한계 - retryBudget이 0인 명령(참조 기능 CREATE)은 그대로 다시 보내지 않는다. - Envelope가 아닌 operation은 백엔드 code를 몰라 이 재전송이 없다. 검증 - RED: tests/integration/http-execution-v3-envelope.test.ts "KEYED resend on the backend's pre-execution refusal" 3건 중 2건 실패(한 번만 보내고 PROBLEM). 다른 503(REQUEST_TIMEOUT)을 다시 보내지 않는 행은 처음부터 통과. - GREEN: 같은 파일 35건 통과. 두 번 보낸 키가 같다. - check:types, lint, check:architecture, test:unit 2,568, test:integration 117, test:component 245, tests/features 99 통과. Refs: docs/reviews/2026-11-01-maturity-review/README.md 14.7
개발 매뉴얼
이 폴더는 이 템플릿으로 만든 프로젝트에 새 기능 하나를 추가하는 절차를 적는다. 기능 하나는 화면(라우트와 페이지)과 그 화면이 쓰는 API 호출을 함께 뜻한다.
시작은 corepack pnpm create:feature <id>다. 이 명령이 모든 merge 게이트를 통과하는 가장 작은 기능을 만든다.
그 뒤 이 매뉴얼의 단계대로 뼈대를 실제 기능으로 바꾼다.
누가 읽는가
- 이 템플릿을 복사한 제품 팀의 프론트엔드 개발자.
- 기능을 만드는 AI 에이전트. 단계마다 "쓸 스킬"을 적었다.
- 스킬: Claude Code가 부르는 작업 지침의 이름이다. 사람이 읽을 때는 건너뛰어도 된다.
전제: 루트 README.md의 "Start locally"대로 로컬에서 앱이 뜬다.
읽는 순서
README (이 문서)
→ 01 작업 순서 (처음부터 끝까지 한 번)
→ 02 결정표 (단계 중 "무엇을 고를지" 막힐 때)
→ 03 기능 폴더 밖 파일 (폴더 밖을 고쳐야 할 때)
→ reference/ (명령 인자, 전역 ID, 패턴, 오류 메시지를 찾아볼 때)
| 문서 | 내용 |
|---|---|
01-add-a-feature.md |
0~11단계. 단계마다 정할 것, 판단 기준, 잡는 검사와 못 잡는 것, 쓸 스킬 |
02-decision-tables.md |
context 경계, 계약 출처, 재시도 의미, 결과 불명, 인증, 페이지 템플릿 |
03-outside-feature-folder.md |
기능 폴더 밖 파일. 생성 명령이 하는 것과 사람이 하는 것 |
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/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로만 쓴다.
- 지금은 고쳐졌다. 그래도 이 매뉴얼의 예시는 route ID와
문서와 코드가 다를 때
코드가 맞다. 이 매뉴얼은 주장이고, 근거는 코드·설정·실행 결과다.
docs/README.md §1에서 이 폴더를 링크하면 verify:documentation(FE-GATE-017)이 이 폴더 문서에 적힌 경로·명령·게이트 ID가 있는지 검사한다.
폴더 링크는 그 폴더 바로 아래 .md만 검사한다. reference/도 검사하려면 따로 링크한다.
설명이 코드와 맞는지는 검사하지 않는다.
플랫폼 규칙(예산·실행·검증·텔레메트리)의 근거는 docs/architecture/의 scale-architecture.md에 있다. 이 매뉴얼은 scale-architecture.md §24처럼 절 번호로 가리킨다.