앞 커밋(1112/01-01) 뒤 확인 리뷰가 완료 기준의 남은 셋과 결함 둘을 찾았다. - 생성 작성 페이지에 마운트 표시(useRef)와 저장 뒤 이동이 남았다. 저장이 끝나면 페이지가 폼보다 먼저, 폼이 pending인 동안 상세로 옮겼다. 다시 마운트한 폼에서 재전송이 성공하면 사용자가 돌아와 입력한, 보낸 적 없는 값을 이탈 확인 없이 버렸다(1112/01-02 영향). - 폼이 재전송 결과로 결과 불명을 다시 판정했다(resendLeftUnknown). 코디네이터와 401에서 갈린다. 코디네이터는 결과 불명을 쥐고 폼은 다시 로그인으로 가는데, FormSaveFeedback이 결과 불명을 먼저 그려 다시 로그인 안내를 가렸다(D-2 위반). - 지난 세 결함(1105/08-02·08-04, 1106/08-02)의 시험이 생성 페이지 시험에만 있었다. 고른 방법: useAppForm에 onSaved를 더한다(추가만). 폼이 결과를 보이고 pending을 끈 뒤, 마운트된 동안만 부른다. confirmUnknownEffect(then)도 마운트된 동안만 then을 부른다. resendUnknownEffect의 then 인자와 FormSaveFeedback의 onResent는 지운다(앞 커밋에서 생겨 아직 내보낸 적이 없다). 재전송 뒤 결과 불명인지는 코디네이터의 새 holdsUnknownEffect로 묻는다. mutation 없이 쓰는 폼(이미 생성한 페이지)은 물을 곳이 없어 같은 거절 표(isRefusedOnEveryAttempt)로 본다. FormSaveFeedback은 다시 로그인 실패를 결과 불명보다 먼저 그린다. 생성 페이지는 mutation.submit을 그대로 넘기고 onSaved와 onConfirmed에서 옮기기만 한다. VD-04 머리 칸에 넣었던 문장은 보완 절로 옮긴다(머리 칸의 백틱 낱말을 문서 검사가 경로로 본다). 페이지가 FormSaveFeedback을 늘 넘기므로, 할 말이 없는 피드백 칸은 자리를 차지하지 않는다(templates.css, 빈 칸이 그리드 간격을 한 줄 더했다). 위험·한계: 저장 뒤 이동이 폼이 결과를 그린 뒤로 한 번 늦어진다. 다시 마운트한 폼에 보내지 않은 값이 있으면 이동이 이탈 확인을 띄운다(의도). 검증: form-foundation 새 시험 일곱과 create-feature 생성 페이지 시험 (RED·GREEN, 막기·다른 저장·충돌 안내 변이 셋), 생성 기능 e2e의 피드백 칸 간격 시험은 desktop에서 돌려 PR 본문에 적는다. Refs: 1112/01-01, 1112/01-02, 1105/08-02, 1105/08-04, 1106/08-02, 1112/04-02
개발 매뉴얼
이 폴더는 이 템플릿으로 만든 프로젝트에 새 기능 하나를 추가하는 절차를 적는다. 기능 하나는 화면(라우트와 페이지)과 그 화면이 쓰는 API 호출을 함께 뜻한다.
시작은 corepack pnpm create:feature <id>다. 이 명령이 모든 merge 게이트를 통과하도록 만든 가장 작은 기능을 만든다(브라우저 게이트는 드릴 밖, 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처럼 절 번호로 가리킨다.