Files
clean-architecture-frontend…/docs
DongHyeonka 63ba523519 fix(form): 저장 뒤 이동과 마운트 판정을 폼이 맡고 다시 로그인 안내를 먼저 그린다
앞 커밋(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
2026-11-13 00:03:42 +09:00
..

docs

저장소의 문서는 이 폴더 아래에 있다(루트 README.md, CHANGELOG.md 등 몇 개는 밖에 있다). 이 README는 두 가지를 정한다.

  • 어떤 문서가 어느 폴더에 있나: 1절 「문서 지도」. 지금 있는 모든 문서 폴더를 덮는다.
  • 문서의 수명에 따라 무엇을 어떤 언어로 어떻게 고치나: 2절부터.

규칙의 정본은 design-docs 저장소의 conventions/docs-system.md다. 이 README는 그 규칙을 이 repo에 적용한 내용이고, 이 템플릿을 복사한 프로젝트도 이 README를 따른다. 파일 목록과 개수는 여기에 적지 않는다. 적으면 다음 문서가 더해지는 순간 틀린 글이 된다. 파일은 폴더를 직접 읽는다.

문서와 코드가 다르면 코드가 맞다.

1. 문서 지도

  • 표의 첫 칸이 폴더다(docs/ 기준 경로).
  • 새 문서 폴더를 만들면 같은 변경에서 이 지도에 행을 더한다. 폴더를 지우거나 옮기면 그 행도 고친다.
  • 문서 검사의 map이 지도에 없는 폴더와, 지도에 있지만 없는 폴더를 막는다(5절).

처음 읽을 문서

문서 정하는 것
../AGENTS.md 규칙의 정본과 지도: 꼭 지킬 것, 맡은 일마다 읽을 playbook, 검증 진입점 scripts/verify.sh
work/, work/reference/ 작업 매뉴얼: 맡은 일마다의 playbook과 기준(완료 기준은 work/improve.md 5절)
README.md 프로젝트 구조, 시작하기, 런타임 설정과 배포 변수, 기능 켜고 끄기와 지원 범위, 검증과 CI, 새 서비스로 시작하기, 원본 업데이트 반영
architecture/frontend-application-foundation.md 이 repo의 역할(스타터 + 재사용 capability)과 기본·선택의 경계
architecture/layers.md, architecture/overview.md 계층과 import 방향. check:architecture가 검사한다
architecture/starter-experience.md 기본 라우트, 인증 모드, 기능 추가·제거 절차
manual/ 새 기능을 더하는 순서와 판단 기준, create:feature(manual/reference/)
operations/ci-quality-gates.md, testing/taxonomy.md 게이트, 테스트 계층, 새 프로젝트가 초기화할 기준선

매뉴얼

일하는 순서와 판단 지점이다. 사람과 AI 세션이 같이 쓴다.

폴더 무엇
work/ 작업 매뉴얼: 새 기능, 리뷰·수정·리팩터링, 조사·설계, 문서, 운영, 일 나누기의 playbook. work/reference/에 게이트·구조·테스트·리뷰 기준과 결정 색인, work/evidence.md에 매뉴얼 규칙의 근거 기록
manual/ 개발 매뉴얼: 새 기능 하나를 더하는 0~11단계, 결정표, 기능 폴더 밖 파일, 짝 백엔드에 붙이기. manual/reference/에 명령 인자, 전역 ID, 패턴, 오류 메시지
ledger/ 작업 예측·실측 장부(ledger/estimates.jsonl, 형식은 ledger/README.md)

현재 계약

지금 코드가 지키는 규칙이다. 코드와 같은 변경에서 고친다.

폴더 무엇
architecture/ 계층과 import 규칙(architecture/layers.md), 플랫폼의 역할, 스타터, recipe 절차, 정적 배포, 계약 소유, 규모 설계(architecture/scale-architecture.md, 코드 주석의 scale-architecture.md §N이 가리킨다), 짝 백엔드 계약(architecture/backend-api-and-server-state-contract.md 4.1·6·6.1절이 실행 규칙. 기준 커밋은 config/contracts/backend-contract-pin.json), 2026-07-18 도식 리뷰 기록의 사본(architecture/review-evidence.md, architecture/review-ledger.json)
contracts/ 계약 호환 규칙(읽는 쪽을 먼저 배포한다)
security/ 브라우저 보안 경계와 공급망
styling/ 디자인 토큰
accessibility/ 수동 접근성 검토 체크리스트와 라우트별 검토 기록(accessibility/route-reviews/)
testing/ 테스트 계층(taxonomy)과 새 프로젝트가 초기화할 기준선

운영

폴더 무엇
operations/ CI 품질 게이트, capability별 복구 절차, 릴리스·캐시 롤백, 성능 증거, 2026-08-14 adapter 재검토의 처리 원장(operations/adapter-remediation-ledger.md)
runbooks/ 오류 code별 장애 대응 runbook(FE-RB-00N). 등록은 config/runbooks/runbooks.json

결정 기록

폴더 무엇
adr/ 결정 기록(VD). 번호는 옮기기 전과 같다(VD-NN-<주제>.md). 2026-11-08에 architecture 아래 decisions 폴더에서 옮겼다

설계와 기록

설계서와 기록은 쓴 때의 글이다. 지금 동작을 설명하지 않는다. 그래서 살아 있는 문서와 다른 폴더에 둔다.

폴더 무엇
design/ 설계서. YYYY-MM-DD-<주제>-design.md. 2026-11-08에 옛 superpowers 폴더의 specs와 architecture/의 목표 설계를 옮겼다
history/plans/ 계획서. 2026-09-25 리뷰 수정 라운드의 요구사항(SPEC.md)과 작업 목록도 여기 있다
history/evidence/ 작업 단계의 증거·체크포인트
reviews/ 리뷰 결과. 라운드마다 폴더 하나(README가 결정과 남은 것을 적는다) 또는 리뷰 문서 하나. 리뷰 가이드와 실행 체크리스트는 design-docs 저장소로 옮겼고, 여기에는 정본 위치를 알려 주는 포인터 둘이 있다
  • 계획서 본문에는 그때 계획한 경로와 명령이 그대로 남아 있다. 계획서를 나중에 고치지 않는 이유는, 고치면 계획의 기록이 아니라 결과를 계획처럼 보이게 만든 글이 되기 때문이다.
  • history/와 reviews/는 복사한 프로젝트가 지워도 된다(루트 README.md 「복사한 뒤 지워도 되는 것」). 예외는 reviews/adapters/다: reviews/adapters/INVENTORY.md는 check:adapter-inventory(FE-GATE-010)가 src/adapters와 대조하는 살아 있는 목록이다.
  • design/과 adr/은 코드 주석이 근거로 가리키므로 지우지 않는다.

폴더 밖 문서

문서 무엇
../README.md 루트 README. 6절의 필수 절을 가진다
../CHANGELOG.md 템플릿 버전 사이의 변경. 지난 상태를 적는 문서라 문서 검사의 참조·숫자 검사는 보지 않는다
../AGENTS.md 규칙의 정본과 지도. src/ 계층 폴더마다 지역 규칙 AGENTS.md가 있다
루트 CLAUDE.md AGENTS.md를 가져오고 Claude Code 전용 줄만 둔다. 경로별 규칙·스킬·서브에이전트는 .claude/
vision.md, problem-statement.md 비전과 문제 정의. 소유자가 채우는 양식이다
루트 PRODUCT.md 디자인 도구가 읽는 제품 맥락
../src/adapters/browser-transfer/image-cdn/README.md Image CDN adapter의 모듈 README

게이트가 읽는 파일

지우거나 옮기면 게이트가 실패한다.

파일 읽는 명령
이 파일, architecture/review-ledger.json, architecture/review-evidence.md verify:documentation (FE-GATE-017)
라우트별 수동 접근성 기록(accessibility/route-reviews/<ROUTE_ID>.md) verify:documentation (FE-GATE-017), review:a11y-manual (FE-GATE-009, FE-GATE-028)
reviews/adapters/INVENTORY.md check:adapter-inventory (FE-GATE-010)
operations/adapter-remediation-ledger.md, operations/adapter-remediation-dispositions.json check:remediation-ledger (게이트 밖. 이유는 config/ci/ungated-scripts.json)
architecture/backend-api-and-server-state-contract.md 6.1절 표 tests/unit/backend-contract-pin-document.test.ts (FE-GATE-005)
architecture/starter-experience.md의 기능 폴더 밖 파일 표, manual/03-outside-feature-folder.md A절 tests/unit/feature-tracked-files.test.ts (FE-GATE-005)
manual/의 표시한 코드 블록과 manual/04-paired-backend-session.md 3.2절 tests/unit/manual-code-blocks.test.ts, tests/unit/manual-paired-backend-settings.test.ts (FE-GATE-005)

2. 문서 수명과 언어

수명 문서 위치 언어 고치는 법
살아 있음 README, AGENTS.md(루트와 src/ 계층 폴더), CLAUDE.md, .claude/의 규칙·스킬, 매뉴얼(work/, manual/), 장부(ledger/), vision.md·problem-statement.md, 현재 계약(architecture/, contracts/, security/, styling/, accessibility/, testing/), 운영(operations/, runbooks/), reviews/adapters/INVENTORY.md, 모듈 README, CHANGELOG.md 제자리 한국어 코드와 같은 변경에서 고친다(4절)
결정 결정 기록(VD) adr/ 한국어 본문은 고치지 않는다. 일부가 바뀌면 상태를 「채택(보완)」으로 하고 맨 아래에 날짜가 있는 「보완」 절을 덧붙인다. 크게 바뀌면 새 VD를 쓰고 옛 VD를 「대체됨」으로 한다
기록 설계서, 계획서, 증거, 리뷰 design/, history/, reviews/ 머리 블록은 한국어, 본문은 쓴 때의 원문 머리 블록의 칸만 고친다
  • 살아 있는 문서와 결정 기록의 본문은 한국어로 쓴다. 설정 파일의 사람이 읽는 설명 칸(recipe 카탈로그, runbook 등록)도 한국어다.
  • 원문으로 두는 것: 코드 식별자, 명령, 경로, 설정 키, 오류 코드, 로그·출력 인용, 외부 문서 인용, 제품 이름.
  • 용어는 자연스러운 한국어 → 한국어(영어) → 영어 그대로 순으로 고른다. 처음 나올 때 한 번 병기한다. 이 repo가 영어로 쓰는 말(adapter, port, capability, recipe, feature, context, slice, registry, gate 등)은 영어로 둔다.
  • 문체는 「~한다」다. 한 문서 안에서 「~합니다」와 섞지 않는다.
  • 2026-11-08에 살아 있는 문서를 모두 한국어로 옮겼다. 문서 검사의 예외 목록은 비어 있다(5절).
  • accessibility/route-reviews/의 라우트별 기록은 문서가 아니라 정해진 영어 키 형식의 게이트 입력이다(scripts/lib/manual-a11y-evidence.ts). 문서 검사가 보지 않는다.

3. 기록 문서의 머리 블록

design/, history/, adr/의 .md 파일은 맨 위에 이 블록을 둔다. 블록을 빼면 원문 그대로다(옮길 때 깨진 상대 링크의 대상만 고쳤다).

<!-- 머리 블록: 이 블록을 빼면 원문이다. 형식은 docs/README.md 「기록 문서의 머리 블록」 -->
> **기록 · 설계서** 본문은 쓴 때의 원문이다. 지금 동작은 「현재 정본」을 읽는다.

- 상태: 구현됨
- 작성일: 2026-08-01
- 요약: 한국어 한 문장
- 현재 정본: `docs/architecture/layers.md`
- 대체됨: `docs/design/<대체한 문서>.md`
<!-- 머리 블록 끝 -->
  • 종류는 폴더가 정하고 둘째 줄에 굵게 적는다: design/ 설계서, history/plans/ 계획서, history/evidence/ 증거. 결정 기록(adr/)의 둘째 줄은 > **결정 기록** 본문은 결정한 때의 원문이다. 지금도 유효한지는 「상태」를, 지금 동작은 「현재 정본」을 읽는다.다. VD는 처음부터 한국어로 썼고 번역하지 않았다. 나중에 본문을 번역하면 「원문이다」 대신 「내용이다(번역은 뜻을 바꾸지 않았다)」로 쓴다.

  • 상태는 종류마다 고정 어휘다.

    종류 상태
    설계서 제안 · 채택 · 구현됨 · 보류 · 폐기 · 대체됨 · 확인 안 함
    결정 기록 제안 · 채택 · 채택(보완) · 폐기 · 대체됨
    계획서 실행 중 · 끝남 · 중단 · 대체됨 · 확인 안 함
    증거 보관
  • 「현재 정본」은 지금 동작을 설명하는 살아 있는 문서나 코드의 경로다. 여럿이면 쉼표로 잇고, 없으면 「없음 — 이유」로 쓴다.

  • 「대체됨」은 상태가 대체됨일 때 대체한 문서의 경로다. 이 문서가 다른 문서를 대체했으면 「대체」 칸에 그 경로를 쓴다.

  • 상태는 그 결정을 바꾼 변경이 같이 바꾼다. 기능을 지우는 커밋이 그 기능의 설계서를 「폐기」나 「대체됨」으로 바꾼다. 새 설계서·결정 기록은 처음부터 블록을 달고 쓴다(보통 「제안」).

  • 2026-11-08에 처음 단 상태는 원래 상태 줄을 기계로 바꾼 값이다: Accepted·Approved·확정·승인·정본 → 채택, Superseded → 대체됨, Proposed → 제안, implemented → 구현됨, 날짜가 붙은 보완 메모가 본문에 있는 VD → 채택(보완). 상태 줄이 없던 설계서와 체크 상자가 모두 표시되지 않은 계획서는 「확인 안 함」이다.

  • .md가 아닌 파일(레인 준비 셸 스크립트)에는 달지 않는다. 같은 폴더 문서의 블록이 그 파일을 설명한다.

  • 리뷰(reviews/)는 아직 머리 블록을 요구하지 않는다.

4. 문서와 코드를 같은 변경에서 고친다

  • 코드나 규칙을 바꾸는 변경이 그것을 설명하는 살아 있는 문서도 고친다. 찾는 법: git grep -n '<바꾼 이름>' -- '*.md'.
  • 살아 있는 문서는 지금 있는 것만 쓴다. 지운 타입·경로·명령은 CHANGELOG.md에 쓴다. 살아 있는 문서 안에서 꼭 써야 하면 > 이력 으로 시작하는 인용 블록 안에 쓴다. 문서 검사는 그 블록의 문체를 보지 않는다.
  • 숫자·버전을 복사하지 않는다. 프레임워크 버전은 package.json과 .nvmrc, 게이트 목록은 config/ci/gates.json, recipe 목록은 config/recipes/frontend-capability-recipes.json, adapter 파일 목록은 reviews/adapters/INVENTORY.md를 가리킨다.
  • 루트 README는 「프로젝트 구조」와 「문서 지도」 절을 반드시 둔다. 전체 절 목록과 순서의 정본은 design-docs conventions/docs-system.md 6.1절이고, 문서 검사의 readme가 그 목록(scripts/lib/docs-system.ts의 README_SECTIONS)을 본다.

5. 문서 검사

verify:documentation(FE-GATE-017)이 위 규칙 중 기계로 볼 수 있는 것을 본다. 하나라도 걸리면 실패한다. 경로 필터가 없다: 코드에서 파일이나 script를 지우는 변경이 그 변경과 상관없는 문서를 낡게 만든다.

  • pull request에서 실패하게 하는 곳은 merge 단계 FE-GATE-005다. 그 안의 tests/unit/documentation-readiness.test.ts가 이 repo를 그대로 두고 verify:documentation을 한 번 돌린다. FE-GATE-017 job 자체는 documentation 단계를 고른 workflow_dispatch에서만 돈다(config/ci/gates.json의 documentation_gate).
검사 보는 것
language 살아 있는 문서와 결정 기록 본문이 한국어인가. 코드·명령·경로·링크·인용은 세지 않고, 영어 낱말 3개 이상이면서 한글 덩어리 비율 0.3 미만이면 영어다(보고 언어 훅 H11과 같은 판정)
head 기록과 결정 기록 맨 위의 머리 블록: 칸, 상태 어휘, 날짜, 한국어 요약, 현재 정본·대체됨 경로가 지금 있는지
document references 살아 있는 문서의 인라인 코드·셸 코드 블록 안 repo 경로, 마크다운 링크 대상, package script 이름, FE-GATE ID가 지금 있는가. 짝 백엔드 경로는 config/contracts/backend-contract-pin.json이 고정한 커밋의 트리에서 찾는다
number 살아 있는 문서가 프레임워크 버전이나 게이트·recipe·adapter 개수를 복사했는가. 결정 기록, 기록, CHANGELOG.md는 보지 않는다
map 이 README의 1절 지도가 docs/ 아래 모든 폴더를 덮는가(표 첫 칸의 폴더/). 파일 없이 폴더만 가진 묶음 폴더(history/)는 그 바로 아래 폴더가 대신한다. 지도에 있지만 없는 폴더도 실패다
readme 루트 README가 첫 줄 제목, 그 아래 한 문단, 정해진 ## 절을 정해진 순서로 가지는가
style 살아 있는 문서와 결정 기록의 문장 끝이 높임(「~합니다」「~하세요」)이 아닌가. 코드, 따옴표·낫표 안 인용, > 이력 블록은 보지 않는다
  • 그 밖에 같은 명령이 루트 README의 런타임 변수 표, 입구 문서의 src/ 폴더 설명(architecture/layers.md 표와 글자가 같아야 한다), 수동 접근성 기록의 범위, 2026-07-18 도식 리뷰 사본 둘의 일치를 본다.
  • 규칙과 판정의 정본은 scripts/lib/docs-system.ts(검사 여섯)와 scripts/verify-documentation-readiness.ts(참조와 그 밖의 검사)다. 백엔드 템플릿의 문서 검사기(그 repo의 check-docs.py)를 같은 이름·문턱으로 옮긴 것이다.
  • 검사 자신의 시험: tests/unit/docs-system.test.ts, tests/unit/documentation-readiness.test.ts.
  • 예외 목록 scripts/docs-system-exceptions.txt는 비어 있고 줄기만 한다. 목록에 새 줄을 더하면 실패한다(줄마다 scripts/lib/docs-system.ts의 FROZEN에 지문이 있어야 하는데, FROZEN이 비어 있다). 기준선을 늘리는 것은 규칙을 바꾸는 일이라 소유자 결정이 필요하다.
  • 복사한 프로젝트가 지운 기록(history/, reviews/)과 지운 샘플 기능의 경로는 없어도 된다. git이 무시하는 생성 산출물도 없어도 된다.
  • 설명·수치가 코드와 맞는지는 검사하지 않는다. 리뷰가 표본으로 대조한다.