Files
clean-architecture-frontend…/docs/manual/README.md
T
DongHyeonka fbd8f7d148 chore(review): 1103 게이트·드릴 조치 브랜치를 합친다
Refs: docs/reviews/2026-11-03-maturity-review/README.md 02-06 11-06 12-09 10-01 11-03~11-05 12-02 12-04 12-05 12-08 14-04 16-02

# Conflicts:
#	docs/manual/01-add-a-feature.md
#	docs/manual/02-decision-tables.md
#	docs/manual/reference/patterns.md
2026-11-04 23:08:05 +09:00

90 lines
6.2 KiB
Markdown

# 개발 매뉴얼
이 폴더는 이 템플릿으로 만든 프로젝트에 **새 기능 하나를 추가하는 절차**를 적는다.
기능 하나는 화면(라우트와 페이지)과 그 화면이 쓰는 API 호출을 함께 뜻한다.
시작은 `corepack pnpm create:feature <id>`다. 이 명령이 모든 merge 게이트를 통과하도록 만든 가장 작은 기능을 만든다(브라우저 게이트는 드릴 밖, `docs/manual/reference/create-feature.md`).
그 뒤 이 매뉴얼의 단계대로 뼈대를 실제 기능으로 바꾼다.
## 누가 읽는가
- 이 템플릿을 복사한 제품 팀의 프론트엔드 개발자.
- 기능을 만드는 AI 에이전트. 단계마다 "쓸 스킬"을 적었다.
- 스킬: Claude Code가 부르는 작업 지침의 이름이다. 사람이 읽을 때는 건너뛰어도 된다.
전제: 루트 `README.md`의 "Start locally"대로 로컬에서 앱이 뜬다.
## 읽는 순서
```text
README (이 문서)
→ 01 작업 순서 (처음부터 끝까지 한 번)
→ 02 결정표 (단계 중 "무엇을 고를지" 막힐 때)
→ 03 기능 폴더 밖 파일 (폴더 밖을 고쳐야 할 때)
→ 04 짝 백엔드에 처음 붙이기 (로그인이 필요한 API를 처음 부를 때)
→ reference/ (명령 인자, 전역 ID, 패턴, 오류 메시지를 찾아볼 때)
```
| 문서 | 내용 |
|---|---|
| [`01-add-a-feature.md`](01-add-a-feature.md) | 0~11단계. 단계마다 정할 것, 판단 기준, 잡는 검사와 못 잡는 것, 쓸 스킬 |
| [`02-decision-tables.md`](02-decision-tables.md) | context 경계, 계약 출처, 재시도 의미, 결과 불명, 인증, 페이지 템플릿, 파일 업로드 |
| [`03-outside-feature-folder.md`](03-outside-feature-folder.md) | 기능 폴더 밖 파일. 생성 명령이 하는 것과 사람이 하는 것 |
| [`04-paired-backend-session.md`](04-paired-backend-session.md) | 짝 백엔드의 두 인증 모드(JWT·Keycloak, Redis session)에 맞는 세션 owner를 붙이는 법 |
| [`reference/create-feature.md`](reference/create-feature.md) | `create:feature`의 인자, 만드는 파일, 거부 조건, 출력 |
| [`reference/global-ids.md`](reference/global-ids.md) | 전역 ID 종류, 생성 명령이 만드는 값, 유일성 검사 |
| [`reference/patterns.md`](reference/patterns.md) | 기능 개발 패턴과 예제 위치. 예제가 없는 패턴은 "없음" |
| [`reference/errors.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처럼 절 번호로 가리킨다.