CI job 컨테이너의 /dev/shm은 Docker 기본값 64 MB다. 그래서 앞 커밋의
Firefox RAM 프로필이 CI에서는 켜지지 않는다. 프로필은 runner 디스크에
남고, 이유가 한 줄 찍힌다. main run 266(ee95573f)도 같은 꼴로
빨갛다. FE-GATE-009 [firefox] generated-feature.spec.ts:380에서 첫
화면(로그인 heading) 5초 대기를 넘겼다.
생성기가 Playwright 이미지를 쓰는 job 컨테이너에
`options: "--shm-size=2g"`를 붙인다(BROWSER_JOB_SHARED_MEMORY). 2 GB는
Firefox worker 6개 프로필 합 최대 211 MB와 fixture가 요구하는 worker당
64 MB에 여유를 둔 값이다. job 메모리 상한 10 GB 안에서 쓴다.
ci-quality-gates.md에 한 줄을 적었다.
버린 대안: runner 설정 `container.options`에 같은 값을 두는 안(계획
D-4 (가))은 운영 설정이라 소유자 실행 묶음에 있다. 그것이 적용되면 이
줄은 지워도 된다.
위험·한계: runner는 `privileged: false`다. act_runner가 workflow의 이
옵션을 무시하면 프로필은 그대로 디스크에 남고, FE-GATE-008·009 로그에
「Firefox profiles stay on disk」 줄이 남는다. runner run에서 그 줄이
없는지로 확인한다.
검증(desktop): generate:ci-workflow로 workflow와 snapshot 갱신,
ci-browser-image·ci-workflow-generation 시험 449 passed, check:ci-workflow,
check:types:node, eslint, scripts/verify.sh docs, verify:documentation 통과.
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.md6.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이 무시하는 생성 산출물도 없어도 된다. - 설명·수치가 코드와 맞는지는 검사하지 않는다. 리뷰가 표본으로 대조한다.