leaf·family 지역 규칙은 지금 src/**/CLAUDE.md에만 있어서 Claude Code
밖의 에이전트는 이 규칙을 정본 이름으로 찾지 못한다. 소유자가
2026-11-07에 루트와 하위 폴더 모두 AGENTS.md를 정본으로 정했다
(design-docs harness/01-harness-design.md 13절 Q1·Q2).
- 28개 파일을 git mv로 같은 폴더 AGENTS.md로 옮기고, 그 자리
CLAUDE.md에는 `@AGENTS.md` 한 줄만 둔다. 이 세션에서
src/domain-core 파일을 열자 CLAUDE.md의 가져오기가 펼쳐져
AGENTS.md 본문이 함께 읽히는 것을 확인했다. 그래서 Claude Code는
지금처럼 그 폴더를 만질 때 규칙을 읽는다.
- 버린 대안: 심볼릭 링크(Edit 도구가 링크를 통해 쓰지 않는다),
CLAUDE.md 그대로 두기(다른 에이전트가 못 찾는다).
- 살아 있는 문서와 테스트 코드의 leaf 규칙 경로를 새 이름으로 바꿨다.
기록 문서(evidence, upgrade, design, history, reviews, adr)는 쓴
때의 경로를 그대로 둔다.
- link-check workflow(lychee)는 src/**/CLAUDE.md만 본다. 내용이
AGENTS.md로 가면 상대 링크가 검사 밖으로 나가므로, PR마다 도는
check-docs.py에 살아 있는 문서 전체의 상대 링크 검사를 더했다.
workflow는 CI 재편 몫이라 고치지 않았다.
- check-work-docs.py의 이력 ID 검사도 src/**/AGENTS.md를 본다.
위험: git은 이 커밋을 "CLAUDE.md 수정 + AGENTS.md 추가"로 본다(같은
이름의 새 파일이 생겨 이름 바꾸기로 잡히지 않는다). 옛 이력은
`git log -- <폴더>/CLAUDE.md`로 본다. 코드 주석의 "CLAUDE.md"는
가져오기를 거쳐 같은 문서에 닿으므로 운영 코드는 고치지 않았다.
검증: python3 scripts/check-docs.py, python3 scripts/check-work-docs.py,
python3 -m unittest discover -s scripts/tests 모두 rc=0. 링크 검사
시험은 검사 조건을 끈 사본에서 7건 중 3건이 실패했다.
BREAKING CHANGE: 파생 서비스의 leaf 규칙 문서 이름이 AGENTS.md로
바뀐다. 동기화 뒤 각 leaf의 CLAUDE.md는 `@AGENTS.md` 한 줄이다.
문제: docs/ 바로 아래에 매뉴얼·운영 문서와 쓴 때의 기록(계획서·설계서·
납품 패키지·증거·학습)이 같은 층에 섞여 있다. 기록이라는 표시도 없어
읽는 사람이 지금 동작을 설명하는 문서와 구분하지 못한다.
고른 방법: 2026-11-07 소유자가 승인한 수명 기준 분리를 따른다.
- docs/superpowers/specs → docs/design/
- docs/superpowers/plans → docs/history/plans/
- docs/superpowers/packages/* → docs/history/packages/*
- docs/{graphql,web,websocket}-superpowers-package
→ docs/history/packages/<같은 이름>/ (packages/graphql과 겹치지 않게
원래 폴더 이름을 둔다)
- docs/evidence → docs/history/evidence/, docs/study → docs/history/study/
- git에 들어가 있던 __pycache__ .pyc를 지우고 .gitignore에 더한다.
옮긴 경로를 가리키는 줄을 같은 커밋에서 고쳤다: 살아 있는 문서의 인라인
경로, AGENTS.md·CLAUDE.md, 빌드 스크립트·테스트 주석, docs/README.md 위치
표, 파생 서비스용 docs/upgrade/2026-11-docs-records.md. 기록 본문은
고치지 않고, 이동으로 깨진 마크다운 상대 링크 32개의 대상만 고쳤다(lychee와
check-work-docs.py --links가 docs/** 전체를 본다). 이동만 따로 두면 그
커밋에서 링크 검사가 실패하므로 한 커밋으로 묶었다. 대부분 R100이라 이름
바뀜은 그대로 보인다.
위험·한계: 기록 본문과 docs/reviews/** 안의 인라인 코드 경로는 옛 경로로
남는다(기록은 고치지 않는다). 실험용 Flyway 파일
db/experimental-rls/V1__tenant_rls.sql의 주석은 체크섬이 바뀌므로 두었다.
납품 패키지 셋의 MANIFEST.sha256과 validate_*.py는 패키지 안 상대 경로라
이동 뒤에도 그대로다.
검증: python3 scripts/check-work-docs.py rc=0, --links(gates.md 범위 +
CLAUDE.md·AGENTS.md) 581개 파일 깨진 링크 0, --history docs/manual rc=0.
문제: 2026-11-06 이력 없는 세션 6개에 이 매뉴얼만 주고 실제 일을
시켰다. 6개 모두 일은 끝냈지만 매뉴얼에서 답을 못 찾은 곳이 세션마다
1~9건 나왔고, 세 곳은 문서끼리 다르게 말했다.
- 리뷰 README를 누가 쓰나: delegate.md는 총괄, improve.md는 리뷰어
- push: README 4절·decisions.md는 "커밋을 허용하면 push도", 정본
delegation-loop.md 11절은 brief가 push를 따로 허용해야 한다
- evidence.md 머리말은 "RR-는 1차 재리뷰"라는데 round2도 RR-를 썼다
고른 방법:
- 리뷰어는 README에 자기 라운드 색인 절 하나만 쓰고, 처리 표·결정의
답·게이트 기록은 총괄이 쓴다(improve.md 4.1, delegate.md 4.2,
decisions.md 2.1)
- 커밋과 push는 brief 7절이 따로 허용한다. 커밋만 허용되면 push하지
않는다. push 없이도 패치와 트리 해시로 desktop에서 검증한다
(operate.md 4.1 「push 전에 검증하기」). 이 방법은 커밋 본문에
desktop 결과를 넣으려는 세션의 빈틈도 닫는다
- evidence.md 머리말을 접두어별 문서로 고친다
- 나머지 빈틈은 그 일을 하는 playbook의 절차 단계나 자주 하는 실수,
reference에 한 줄씩 넣는다. 36행 처리 표는 evidence.md 9절이다
(고침 35, 고치지 않음 1: 새 매뉴얼에 이미 답이 있던 것)
버린 대안: push를 "커밋 허용이면 push도"로 읽기. 정본 11절과 실제
brief(백엔드는 push, design-docs는 push 안 함)가 push를 따로 다룬다.
버린 대안: 빈틈을 모두 자주 하는 실수에 넣기. 10줄 상한을 넘고, 절차의
한 단계인 것은 그 단계에 있어야 읽힌다.
위험·한계:
- 리뷰 README 분담, push를 따로 읽는 것, 하위 세션 Slack은 기본값이다.
소유자가 뒤집을 수 있게 decisions.md에 기본값으로 적었다
- AGENTS.md의 커밋 예외 문장은 이번 범위 밖이라 그대로다. 세부는 이
README 4절을 가리키므로 README가 정한다
- 고친 매뉴얼은 2회차 cold-read 시험 전이다
검증:
- python3 scripts/check-work-docs.py rc=0. 지도 73/120, README 76/80,
improve.md 134/150, 진입 경로 최대 283/350, 본문 이력 0줄
- python3 scripts/check-work-docs.py --links docs CLAUDE.md 결과 링크
432개, 깨진 것 0
- desktop: 바꾼 것을 패치로 기준 커밋 2c8a359d 위에 얹어 노트북과 같은
트리 3d0e5900을 만들고 flock 아래
:app-bootstrap:documentContractTest --rerun rc=0, 66건 실패 0
건너뜀 0, 13초, 직전 1분 부하 3.13
(desktop ~/manual-gap-fix-1-logs/documentContractTest.log)
문제: 이 repo의 진입 문서는 아키텍처 규칙을 길게 다시 쓴 CLAUDE.md(183줄)와
리뷰·수정만 다루는 옛 개선 매뉴얼(진입 717줄, 미병합)이었다. 이력 없는 세션이
"이 일이면 무엇을 읽나"를 알 수 없었고, 새 기능·조사·문서·운영·총괄의 절차는
없었다. 규칙도 서로 달랐다: 하위 에이전트(AGENTS.md는 권함, 소유자는 금지),
커밋(human-only와 브랜치 커밋 허용), 리뷰 멈춤 기준(거둔 기준이 남음).
고른 방법(2026-11-06 소유자 결정 D1, D2, D4, D12; 설계 design-docs
delegation-loop/02-design.md 4~6·10절):
- CLAUDE.md를 72줄 지도로 바꿨다: 이 repo, HARD-STOP 7개 한 줄씩(정본
AGENTS.md), 일 → playbook 표, 검증 명령과 실행 위치, 코드만 보고는 헷갈리는
곳, 소유자 환경 포인터. AGENTS.md를 요약하던 절은 지웠다. AGENTS.md에 없던
내용은 옮겼다: messaging 예외는 지도 5절, 판단 보고 규칙은
reference/review-criteria.md 11절, 위험 비례 원칙은 docs/work/README.md 2절.
- docs/work/: README(라우터·크기·공통 단계·커밋·막혔을 때·보고), playbook 6개
(new-feature, improve, research-design, docs-writing, operate, delegate, 모두
같은 9칸 뼈대), reference/ 4개(gates, review-criteria, defect-patterns,
decisions), evidence.md. 옛 매뉴얼 03~06장은 reference/를 늘리지 않고
review-criteria(점검 기준), defect-patterns(막는 기준), gates(성능 lane)에
나눠 넣었다. 다섯 번째 reference 파일은 설계의 파일 구성과 달라 버렸고,
improve.md 본문에 넣는 안은 150줄 상한을 넘어 버렸다.
- improve.md에 수정 보고의 「새로 가정하는 것」 칸(확인 리뷰가 여기서 시작)과
수정 묶음 상한(영역 하나·발견 8건, 확인 리뷰당 추가 1,500줄)을 넣었다. 지난
수정 커밋의 추가 줄과 다음 확인 리뷰 발견 수(+906→9, +1,877→7, +5,420→25,
+13,479→29)가 근거다(evidence.md 3절). 멈춤 기준은 "발견 0"으로 하나만 둔다.
- 커밋: AGENTS.md human-only는 두고 "brief가 허용할 때만 자기 브랜치에" 예외를
README 4절과 AGENTS.md에 같은 말로 적었다.
- 본문 이력 ID 0. 지난 리뷰 ID와 사건은 evidence.md와 두 색인
(reference/decisions.md, reference/defect-patterns.md)에만 둔다.
- 연결: README.md(HARD-STOP을 "8개"로 잘못 적은 것도 7개로), docs/README.md,
docs/manual/README.md(입구 연결), docs/manual/02-new-feature.md(지운
CLAUDE.md 「Layer workflow」를 가리키던 줄).
위험·한계: 이 매뉴얼은 이력 없는 새 세션으로 시험(cold-read)하기 전이라
초안이다. 정식 시험은 총괄이 따로 한다. 작성 중 자가 점검(지도부터 읽어
docs-writing.md로 brief 하나를 써 봄)에서 막힌 네 곳은 고쳤다. docs/manual/
본문에는 아직 이력 ID 9줄이 남아 있다(범위 밖, 후속 작업). gates.md 5절의
성능 단언 속성 문장은 성능 게이트를 고치는 다른 작업과 겹친다.
검증
- python3 scripts/check-work-docs.py: rc=0. 지도 72/120, README 75/80,
playbook 79~132/150, 진입 경로 최대 279/350, 본문 이력 ID 0줄
- python3 scripts/check-work-docs.py --links docs README.md CLAUDE.md
AGENTS.md: 504파일, 상대 링크 447개, 깨진 것 0
- CLAUDE.md를 읽는 테스트 DeveloperExperienceContractTest
.guidanceNamesTheArchitectureSourceSetTask가 기대하는
"./gradlew :app-bootstrap:architectureTest"를 지도에 남겼다. Gradle 게이트는
이 커밋을 push한 뒤 desktop에서 돌린다