문제: 짝 백엔드(45d2a478)는 POST /v1/files를 요청 안에서 동기로 검증하고 READY가 아닌 state를 모두 202로 답한다(FileUploadController#created). 악성 코드가 아닌 이유로 검증기가 거절하면 예외 없이 202 REJECTED다 (FinalizeUploadApplicationUseCase#applyNonAcceptVerdict). 기본 검증기 사슬의 첫 검증기(LengthVerifier)가 빈 파일을 그렇게 거절하므로, 0바이트 파일 하나로 닿는다. client schema에는 REJECTED가 없어 이 답이 SCHEMA_MISMATCH, APPLIED_CONFIRMED, "응답 형식 오류" 문구로 끝난다. 사용자는 파일을 바꾸라는 안내 대신 지원 문의를 보게 된다. 테스트의 MSW는 202 VERIFYING만 적은 백엔드 문서에서 왔고, 매뉴얼도 202를 "아직 검사 중"으로 적어 QUARANTINED(동기 검증 202의 대부분)를 끝나지 않는 대기로 보이게 한다. 고른 방법(리뷰 01-01 최소 개선 방향 (가)): - schema가 REJECTED를 받는다. 202 REJECTED는 성공이 아니라 실패 VALIDATION_REJECTED, code FILE_REJECTED, NOT_APPLIED, httpStatus 202다. 413·415·422 파일 거절과 같은 규칙이다. 백엔드는 그 레코드를 공개하지 않고 바이트 정리를 예약하므로 쓸 수 있는 파일이 남지 않는다. 공개 타입 FileserverFileState와 FileserverUploadedFile은 바꾸지 않았다(REJECTED는 성공 값으로 나오지 않는다). - 빈 파일은 읽기 전(선언 크기 0) 또는 읽은 뒤(선언 없음, 0바이트) 보내지 않고 FILE_EMPTY, NOT_STARTED로 끝낸다. 서버의 202 REJECTED에는 이유가 없어 기능이 "빈 파일"이라고 말할 수 없기 때문이다. - 201⇔READY 검사, size 일치 검사, 모르는 필드 무시는 그대로다. 201 REJECTED는 여전히 SCHEMA_MISMATCH다. - MSW 설명을 백엔드 코드(45d2a478) 기준으로 고치고 202 QUARANTINED· REJECTED 행을 더했다(1103/01-01의 "MSW가 문서에서 왔다" 부분). - 매뉴얼 7절이 202 state 셋의 뜻(VERIFYING 재검사 대기, QUARANTINED 관리자 결정 전 내려받기 불가, REJECTED는 실패)과 FILE_EMPTY를 적는다. 버린 대안: - REJECTED를 성공 state로 넘긴다: 타입 변경은 작지만 기능마다 성공 값에서 거절을 다시 찾아야 하고, 공개 타입 FileserverFileState가 넓어진다. - 빈 파일 거절만 한다: 기본 사슬은 막지만 제품이 더한 검증기의 REJECT는 그대로 SCHEMA_MISMATCH다. 위험·한계: - upload() 결과가 바뀐다. 202 REJECTED가 SCHEMA_MISMATCH에서 VALIDATION_REJECTED/FILE_REJECTED로, 빈 파일이 서버 요청에서 FILE_EMPTY로 바뀐다. CHANGELOG [계약] 한 줄이 필요하다. - 빈 파일 거절은 짝 백엔드 기본 검증기 사슬을 가정한다. 제품이 사슬에서 LengthVerifier를 빼 빈 파일을 받게 하면 client 규칙도 바꿔야 한다. - 실제 짝 백엔드를 띄워 빈 파일을 올려 보지 않았다(미검증). 응답 모양은 백엔드 코드(UploadedFileResponse, FileRecord#toDescriptor)를 읽은 것이다. - 1103/01-01의 남은 부분은 이 커밋 밖이다: 백엔드 매뉴얼의 짝 경로 안내와 docs/fileserver/http-contract.md의 202 state 목록(백엔드로 넘김), 실제 업로드 검증(미검증). 검증: desktop batch에서 확인. node scripts/run-vitest.ts run tests/integration/fileserver-upload.test.ts RED(이 커밋의 테스트 + 부모 src): "reads 202 REJECTED as a refused file, not as a broken answer"(SCHEMA_MISMATCH로 끝남), "an empty file", "an undeclared size that turns out empty"(fetch를 부름)가 실패한다. Refs: 1105/01-01, 1103/01-01
개발 매뉴얼
이 폴더는 이 템플릿으로 만든 프로젝트에 새 기능 하나를 추가하는 절차를 적는다. 기능 하나는 화면(라우트와 페이지)과 그 화면이 쓰는 API 호출을 함께 뜻한다.
시작은 corepack pnpm create:feature <id>다. 이 명령이 모든 merge 게이트를 통과하도록 만든 가장 작은 기능을 만든다(브라우저 게이트는 드릴 밖, docs/manual/reference/create-feature.md).
그 뒤 이 매뉴얼의 단계대로 뼈대를 실제 기능으로 바꾼다.
누가 읽는가
- 이 템플릿을 복사한 제품 팀의 프론트엔드 개발자.
- 기능을 만드는 AI 에이전트. 단계마다 "쓸 스킬"을 적었다.
- 스킬: Claude Code가 부르는 작업 지침의 이름이다. 사람이 읽을 때는 건너뛰어도 된다.
전제: 루트 README.md의 "Start locally"대로 로컬에서 앱이 뜬다.
읽는 순서
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/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처럼 절 번호로 가리킨다.