이 대화를 모르는 서브에이전트에게 AGENTS.md부터 읽혀 두 일(새 기능 만들기, diff 리뷰)의 절차를 쓰게 했다. 막힌 곳 16, 사실과 다른 곳 5가 나왔다. 고친 것: - new-feature: 생성·기준선 다시 쓰기를 desktop에서 하고 --apply-back으로 받는다. FE-GATE-020은 제품 기능을 지우지 않으므로 그 기능의 제거 드릴을 따로 돌린다(사실과 달랐다). 생성 명령이 만드는 첫 context는 중간이다. 새 기능은 FE-GATE-026도 돌린다. 매뉴얼 예시 이름이 오면 묻는다. 초기 JS 기록의 파일을 적는다. - gates·improve·AGENTS: FE-GATE-013 결정 대기 동안의 merge 판정 문구, PR·diff 리뷰도 merge 단계 전부를 돌린다, diff 리뷰의 base·head 규칙과 ID 체계와 둘 곳, 라운드 세는 법, "빠른 게이트 8개"를 "검사 8개 (package script)"로. - review-criteria: 발견 한 개의 칸(가이드 36.3절 줄임)과 통제 M0~M4· 증거 E0~E4의 뜻을 옮긴다. 가이드 없이 판정할 수 있다는 문장을 맞춘다. - README·CLAUDE·decisions·rules/docs·skills: 최근 리뷰 README의 실제 절 이름, 사고 순서 흔적의 여섯 칸과 design-docs 위치, 보고 칸과 말투의 정본, `docs/work/README.md`를 가리키게, 리뷰 README 조치 절 예외, 스킬의 새 명령 모양. 고치지 않은 것: 세션에 주입된 옛 CLAUDE.md(시험 세션이 이 브랜치 전에 시작했다). 검증: scripts/verify.sh docs rc=0, scripts/verify.sh hooks 통과.
11 KiB
11 KiB
결정 색인
결정은 한 번 하고, 한 곳에 적고, 다시 묻지 않는다. 이 repo의 결정은 리뷰 README·SPEC.md(2026-09-25 수정 라운드의 기본값)·결정 기록에 흩어져 있다. 이 문서는 그 결정들의 색인이다. 원문은 옮기지 않고 출처만 단다(원문을 옮겨 쓰면 갈라진 복사본이 된다).
리뷰가 선택지를 낸다 → 리뷰 README 「결정이 필요한 것」
소유자가 고른다 → 같은 README 「조치」의 결정 표 (또는 SPEC.md 「결정」, 결정 기록)
이 색인에 한 줄 → 다음 작업은 여기부터 찾는다
1. 결정을 다시 묻지 않는 규칙
- 결정이 필요해 보이면 먼저 2절 색인과 가장 최근 리뷰 README의 결정 절을 찾는다.
- 이미 정했으면 따른다. 상황이 바뀌어 뒤집어야 하면 새 결정으로 적고 옛 결정을 가리킨다. 옛 기록을 고치지 않는다.
- 정한 적이 없으면 3절 형식으로 결정 대기를 만든다. 스스로 정하지 않는다. 다만 소유자가 위임한 범위 안에서는 총괄이 정하고 그 위임 문장을 출처로 적는다.
- 다시 열 수 있는 것은 결정의 전제가 틀렸다는 새 증거가 있을 때뿐이다. 그 증거와 재검토 조건을 함께 적는다.
2. 색인
「출처」의 리뷰 README는 docs/reviews/<날짜>-maturity-review/README.md다. 「repo 밖」은 소유자 지시가 세션 기록과 작업 메모에만 있던 것이다. 이 매뉴얼의 해당 절이 그 규칙의 repo 안 기록이다.
2.1 작업 방식 (소유자 지시)
| # | 날짜 | 결정 | 출처 | 이 매뉴얼 |
|---|---|---|---|---|
| O-1 | 2026-09-16 | 이 repo는 템플릿이다. 소비자 없는 코드와 빈 레지스트리는 확장 지점이지 죽은 코드가 아니다 | 옛 루트 CLAUDE.md 리뷰 전제 |
AGENTS.md 첫 문단, structure.md 2절 |
| O-2 | 2026-09-16 | adapter 배럴을 공개 경계로 만든다(배럴 폐지안 기각) | 옛 CLAUDE.md, docs/architecture/layers.md |
꼭 지킬 것 1 |
| O-3 | 2026-09-16 | 갈라진 IndexedDB 복사본은 kernel(src/adapters/platform/)로 모은다. 새 파일 단위 예외를 만들지 않는다 |
옛 CLAUDE.md, SPEC.md 공통 완료 기준 6 |
꼭 지킬 것 2 |
| O-4 | 2026-11-01 | 커밋·PR은 design-docs conventions/commit-and-pr.md를 따른다. AI 꼬리말은 어디에도 넣지 않는다 |
repo 밖 | docs/work/README.md 4절 |
| O-5 | 2026-11-03 | merge 가능 판정은 ci:gate로 merge 단계 전부를 workflow env로 돌려서 한다. 고른 스크립트 목록으로 판정하지 않는다 |
repo 밖. 실행 기록은 1103 README 14.5절 | gates.md 3절 |
| O-6 | 2026-11-03~05 | 리뷰 발견은 Low까지 고쳐 "남은 문제 0"으로 보고한다. 못 고치는 것은 결정 대기로 이유와 함께 남긴다 | repo 밖 | improve.md 4.5절 |
| O-7 | 2026-11-03~05 | 리뷰·수정에 스킬을 쓴다 | repo 밖 | improve.md 3절 |
| O-8 | 2026-11-03~05 | 총괄 세션은 하위 세션에 일을 맡긴다 | repo 밖 | delegate.md |
| O-9 | 2026-11-04 | 수정 → 리뷰를 반복한다. 새 High 0·새 P1 0·merge 단계 통과면 그 라운드의 Medium·Low를 고치고 멈춘다. 1103 수정 라운드 뒤로 세 라운드를 더 돌아도 닿지 않으면 멈추고 이유를 보고한다 | repo 밖 | improve.md 4.5절 |
| O-10 | 2026-11-05 | 테스트·게이트는 노트북에서 돌리지 않고 desktop에서 돌린다 | repo 밖 | operate.md 4.1절 |
| O-11 | 2026-11-05 | 리뷰 중 실행은 게이트를 한 번 돌리고 산출물을 함께 읽는다. 추가 실험은 목록으로 모아 같은 명령은 한 번만, 실험마다 작업 폴더를 되돌리며 일괄로. 작업 폴더 복제본을 늘려 해결하지 않는다 | 1105 README 11.4절 | delegate.md 4.2절 |
| O-12 | 2026-11-05 | 백엔드와 다른 종료 조건을 각자 유지한다(「각자 유지」). 백엔드는 발견 0까지 확인 리뷰를 반복하고, 프론트는 O-9대로 한다 | repo 밖(백엔드 총괄 전달) | improve.md 4.5절 |
| O-13 | 상시 | 짝 백엔드 repo는 읽기만 한다. stage·commit·push하지 않는다 | 1103 README 14.2절 D1 「이유」 | delegate.md 4.3절 |
| O-14 | 상시 | 리뷰에서는 코드를 고치지 않는다 | 옛 CLAUDE.md |
review-criteria.md 1절 |
| O-15 | 2026-11-05 | 수정 결과의 「고침」을 그대로 믿지 않는다. 다음 리뷰에서 ID별로 다시 판정한다 | repo 밖. 근거 사례 1105 README 3.1절 | improve.md 4.5절 |
| O-16 | 2026-11-05 | 큰 라운드는 작은 PR로 나눈다(커밋 규칙 5.1절). 소유자가 PR을 merge한다 | repo 밖 | improve.md 4.4절 |
| O-17 | 2026-11-07 | Claude Code 하네스를 자료(제작 책임자가 권하는 방식)대로 적용한다: 루트 AGENTS.md 정본(40줄 이하) + CLAUDE.md가 가져오기, 경로별 규칙 .claude/rules/, 모델이 부르는 스킬(설명에 발동 조건), repo 훅은 넛지 위주, 검증 진입점 scripts/verify.sh, 장부 docs/ledger/estimates.jsonl |
design-docs harness/01-harness-design.md 13절 |
이 매뉴얼 전체 |
| O-18 | 2026-11-07 | Agent 금지를 두지 않는다. 결과만 받는 일(검색, 구조 리뷰, 실행 검증, 단순화 제안)은 서브에이전트, 파일을 바꾸고 소유자가 열어 보고 멈출 수 있어야 하는 위임은 하위 세션이다 | 같은 문서 13절 Q5 | delegate.md 4.3절 |
| O-19 | 2026-11-07 | 루트 AGENTS.md·CLAUDE.md(와 .claude/, docs/work/)는 템플릿 계약이다. 복사한 프로젝트가 받는다. 지워도 되는 문서 목록에 넣지 않는다 |
같은 문서 13절 Q4 | structure.md 4절, operate.md 4.4절 |
| O-20 | 2026-11-08 | 프론트 편집 훅은 노트북에서 표준 라이브러리 정적 검사만 한다. 포맷·린트·타입은 desktop scripts/verify.sh에서 돈다. 설계 13절 Q6(편집 훅에서 한 파일 포맷·린트)과 다른 점은 프론트 린터가 pnpm·node_modules를 써서 "pnpm은 desktop에서만"(O-10)과 부딪치기 때문이다 |
하네스 적용 brief(백엔드 총괄, 2026-11-08) | scripts/hooks/README.md |
2.2 기술 결정 (리뷰 라운드)
| 묶음 | 날짜 | 무엇을 정했나 | 출처 |
|---|---|---|---|
| 0925 수정 라운드 기본값 D-1~D-19 | 2026-09-25 | 결과 불명 intent 보관과 같은 키 재전송(D-1), 효과 분류 선택 필드(D-2), Web Lock 직렬화(D-3·D-4), 확인 못 한 판정은 UNVERIFIED(D-14), 문서 색인(D-16), 규모 측정은 실제 모양 기능 25·100개(D-18) 등 |
SPEC.md 「결정」(문서 체계 정리 뒤에는 docs/history/로 옮겨진다) |
| 0929 결정이 필요한 것 7건 | 2026-09-29 | 확장 지점 범위, 409 분류, x-correlation-id, fanout 검사, remediation 원장, cross-context kernel 예외, 리뷰 게이트 목록에 test:system |
0929 README |
| 1101 결정 표 | 2026-11-03 | 확장 지점을 템플릿이 연다, design-system side effect 없음, raw mutation 입력을 공개 훅에서 뺌(BREAKING), 빠른 계층 quarantine 없음 유지, OPFS 여러 페이지 purge 등 24행 | 1101 README 14절 |
| V2 HTTP 경로 삭제 | 2026-11-03 | HTTP 실행은 V3 하나. 지운 V2 동작의 판정 | 1101 README, 1103 README 3절 |
| 1103 결정 D1~D6 | 2026-11-04 | 짝 업로드는 Fileserver multipart client(D1), 업무 거절은 operation 단위 refusedBeforeWrite code 목록(D2), 시각 테스트는 기능 영역을 가리고 찍음(D3), 접근성 e2e 응답 모양(D4), CHANGELOG는 순 변경 요약(D5), 짝 계약은 pin 파일 + 답 표 대조 + drift 검사(D6) |
1103 README 「조치」 |
| WebKit preload 경고(1103/11-09) | 2026-11-05 | 경고 문구 하나만 무시하고 preload 사용을 세 엔진에서 직접 검사한다 | 1103 README 14.7절 |
| 1105 결정 D7 | 2026-11-05 | 초기 JS 예산을 204,800 B에서 206,848 B로 올린다 | 1105 README 16.2절 |
| 1106 결정 D9·D10 | 2026-11-06 | 초기 JS 예산 206,848 B를 그대로 두고 근거·되돌림 규칙을 docs/operations/performance-evidence.md에 둔다(D9). 결과 불명 KEYED 재전송이 쓰기 전 거절로 끝나도 훅이 결과 불명과 키를 지킨다. 재전송의 거절이 결과 불명을 푸는 것은 짝 백엔드 표의 code뿐이다(D10과 보완 둘, 판정 src/contracts/errors.ts isRefusedOnEveryAttempt) |
1106 README 16.2절 |
| 구조·기술 결정 기록 | 2026-07-26~ | VD-01~(빈 번호 있음) |
docs/architecture/decisions/ |
3. 결정 대기 쓰는 법
못 고치는 발견은 이 형식으로 남긴다. 이 형식을 채우지 못하면 결정 대기가 아니라 미완이다.
| 칸 | 내용 |
|---|---|
| 번호·관련 발견 | 예: D8, 1105/12-01 |
| 왜 고치지 못하나 | 예: 러너 전제를 바꾸는 일이라 소유자 결정이 필요하다 |
| 선택지 | 권하는 안을 먼저. 각 안의 비용과 위험 |
| 결정할 사람 | 프론트 소유자 / 두 repo 소유자 / 프론트 소유자 + reviewer 등 |
| 결정 전까지 | 임시 처리와 보고 방법(예: gates.md 3절의 FE-GATE-013 기록 방법) |
| 재검토 조건 | 어떤 규모·버전·계약 변화가 결론을 바꾸나 |
결정 표에 들어갈 것: 고른 것과 이유(무엇을 지키는지로), 버린 대안과 버린 이유, 확인한 사실 / 기록된 의도 / 추론의 구분, 재검토 조건.
3.1 지금 열린 결정 대기
2026-11-06 리뷰(1106) 시점이다. 다음 라운드가 닫거나 새로 열면 이 표를 고친다.
| 번호 | 결정 | 관련 | 결정할 사람 | 출처 |
|---|---|---|---|---|
| D1 | 운영 advisory 2건(zod·react-router). zod 갱신은 초기 JS를 약 7 KB 늘린다 | 1103/13-03 | 프론트 소유자 + reviewer | 1106 README 7절 |
| D2 | 플랫폼 구성 화면을 진단 화면으로 인정할지, 기능으로 옮기고 다시 잴지 | 1103/09-04 | 프론트 소유자 | 같음 |
| D3 | 백엔드 생성기의 목록 GET | 1103/03-07 | 두 repo 소유자 | 같음 |
| D8 | FE-GATE-013을 멈춤 기준에서 어떻게 셀지(호스트 제약 실패로 제외 / 다른 러너에서 통과할 때까지 미충족) | 1105/12-01 | 소유자 | 같음 |
| D11 | 생성 기능 설치 상태의 브라우저 merge 게이트 | 1105/16-03 | 템플릿 담당 | 같음 |
| D6(1105) | 실행 격리: 실행별 출력·빈 포트, 또는 "한 checkout 한 실행" 명시. ci:gate 두 실행은 아직 같은 dist·artifacts/를 쓴다 |
1105/12-04 | 프론트 소유자 | 1105 README 7절, 1106 README 2.3절 |
4. 커밋·PR
정본은 repo 밖 design-docs conventions/commit-and-pr.md다. 이 repo에서 덧붙이는 것은 review-criteria.md 11절(발견 ID 꼬리말, CHANGELOG 리뷰 ID, BREAKING)과 ../README.md 4절이다. PR 본문은 그 문서 5.3절의 칸을 쓰고 「위험과 영향」과 「검증」은 비우지 않는다. 병합은 소유자가 한다.