루트에 CLAUDE.md와 AGENTS.md가 둘 다 있으면 Claude Code 기본 설정은
AGENTS.md를 읽지 않는다. 그래서 344줄 정본은 세션이 스스로 열 때만
닿았고, HARD-STOP은 CLAUDE.md 요약으로만 실렸다. 두 문서가 같은
규칙을 아홉 군데 따로 적었다. 소유자가 2026-11-07에 루트 정본은
AGENTS.md 20~40줄, CLAUDE.md는 `@AGENTS.md`로 정했다(design-docs
harness/01-harness-design.md 13절 Q1·Q2·Q3).
- AGENTS.md(37줄): 무엇인가, HARD-STOP 7, 지도, 맡은 일, 검증,
일하는 방식. CLAUDE.md(6줄): `@AGENTS.md`와 Claude 전용 줄.
- 옛 절의 새 자리: Gradle 정책 권위 → src/build-logic/AGENTS.md(새),
테스트 작성 규칙 → .claude/rules/java-tests.md(paths: 테스트 소스),
계층별 테스트 기준·family 책임 → 각 core AGENTS.md와 새
src/adapter/inbound·outbound/AGENTS.md, composition 조립 규칙 →
src/composition/AGENTS.md(새), capability 규칙·완료 기준 →
docs/manual/10-capabilities.md(이제 정본), 설정·Docker 규칙 →
.claude/rules/settings-and-runtime.md, 문서 편집 규칙 →
.claude/rules/docs.md, 템플릿 재사용 체크리스트 → README
「새 서비스로 시작하기」. Superpowers 목록·강제 수준·금지된 지름길·
작업 보고 규칙은 HARD-STOP과 전역 규칙의 중복이라 지웠다.
- 살아 있는 문서의 옛 절 참조를 새 자리로 바꿨다. 결정 색인은 옛
행에 취소선을 긋고 「지침 배치」 행을 더했다.
- check-work-docs.py: 지도를 AGENTS.md로, 상한 40(CLAUDE.md 10),
진입 경로에 CLAUDE.md를 더하고, CLAUDE.md 첫 줄이 가져오기인지,
.claude/rules·skills·agents 문서의 이력 ID와 링크를 본다.
- DeveloperExperienceContractTest는 루트 안내 명령을 AGENTS.md에서
읽는다. 단언은 그대로다.
버린 대안: 루트 120줄(설계 권함, 소유자가 자료 쪽으로 정함),
CLAUDE.md만 두기(다른 에이전트가 못 읽음), 심볼릭 링크.
위험: 폴더를 가로지르는 규칙(.claude/rules/)은 Claude Code만 자동으로
읽는다. 다른 에이전트용으로 AGENTS.md 지도에 위치 한 줄을 뒀다.
검증: check-work-docs.py(AGENTS.md 37/40, CLAUDE.md 6/10),
check-docs.py, unittest, check-repo-layout.py 모두 rc=0. Java 테스트
변경은 마지막 트리에서 desktop documentContractTest로 확인한다.
BREAKING CHANGE: 루트 AGENTS.md의 절 이름이 바뀌고 내용이 위 자리로
옮겨 갔다. docs/upgrade/2026-11-harness.md 2절 2·3행.
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` 한 줄이다.
문제: 이력 ID 0 규칙은 docs/work와 docs/manual 본문에만 걸려 있었다.
새 세션이 처음 읽는 규칙 문서인 AGENTS.md와 leaf CLAUDE.md에는 "리뷰
05-18", "D12", "MSG-023", "owner decision 33"처럼 지난 리뷰를 모르면 읽을
수 없는 번호가 87줄 남아 있었다. 2026-11-07 소유자가 이 둘로 넓히기로
했다(리뷰 README 19.4절 ③의 (b)). 모듈 README·설계 문서·docs/reviews는
넓히지 않는다.
고른 방법: 87줄의 번호를 내용과 날짜로 바꾸거나 지웠다. 근거(번호가 가리키는
발견·결정과 원래 문서)는 docs/work/evidence.md 10절 표로 옮겼다. 원래 설계
기록이 이 repo에 없는 번호(feature-*-contract의 D1~D12)는 가리키는 규칙과
코드 위치를 근거로 적었다. check-work-docs.py 기본 모드가 두 문서 묶음까지
보게 했고, 그동안 못 잡던 꼴을 더했다: 모듈 리뷰 발견(MSG-023, BOOT-006),
리뷰 후속 발견(S6-#10a, X2-P1-5, S5-lead-4), 고른 대안이 붙은 발견 번호
(03-11 (b)), 영어 "decision 9"·"review README §15", 줄바꿈으로 갈린 ID.
날짜로 쓴 결정("owner decision 2026-11-06")을 번호로 잡던 오탐은 뺐다.
문서를 고친 것과 검사를 넓힌 것을 한 커밋에 둔 것은, 따로 두면 검사만 있는
커밋에서 기본 모드가 실패하기 때문이다. 버린 안: 검사만 넓히고 문서는 다음
커밋 — 중간 커밋이 rc=1이 된다.
위험·한계: 검사는 아는 꼴만 잡는다. 걷어낸 뒤 "리뷰·라운드·결정·review·
decision·round·§"로 남은 괄호를 grep으로 다시 읽었다. 새 패턴을 docs/reviews
밖 전체에 돌리면 검사 대상 밖에서 125줄이 새로 걸린다(모듈 README, ADR 등의
실제 ID). 대상 안 오탐은 0이다. 일부러 만든 "line 10-12 (b)" 한 꼴은 오탐이지만
repo에 없다. 이 검사는 CI가 돌리지 않는다. 파생 서비스 tech-log-backend의 같은
문서에 33줄이 있다(대부분 템플릿에서 받은 사본, 고치지 않음).
검증(트리 41e44de0, desktop ~/workspace/manual-gap-fix-2, 로그
~/manual-gap-fix-2-logs/A-*):
- python3 scripts/check-work-docs.py rc=0, --history docs/manual rc=0,
lychee 범위 --links rc=0(578파일, 깨짐 0)
- ./gradlew :app-bootstrap:documentContractTest --rerun rc=0(67건, 실패 0)
- ./gradlew :adapter:outbound:persistence-mongo:test --tests
'dev.caskeleton.adapter.outbound.mongo.MongoNamespaceContractTest' --rerun
rc=0(3건)
문제: 앞 커밋에서 더한 한국어 라운드 번호 패턴이 "1라운드"(지난 라운드
하나의 이름)와 "2~3라운드 동안"(라운드 수)을 가르지 못한다. 확인 리뷰를
독립 리뷰어 둘로 하는 소유자 결정을 delegate.md에 옮기다가 "2~3라운드
기록이 쌓이면"이 이력 ID로 잡혀 기본 검사가 rc=1이 됐다.
고른 방법: 범위 기호(~, -) 바로 뒤의 숫자와, 뒤에 동안·마다·씩·간이
붙는 경우를 뺀다. 버린 대안: 문서에서 "라운드 두세 번"으로 돌려 쓰기.
다음에 쓰는 사람이 같은 오탐을 다시 만난다.
위험·한계: "3라운드 뒤"처럼 다른 낱말이 붙는 횟수는 아직 이력으로
잡는다. 그때는 문장을 고치거나 패턴에 낱말을 더한다.
검증:
- 패턴 시험 19건(보통 문장 11, 이력 8)이 모두 기대대로 나왔다
- python3 scripts/check-work-docs.py rc=0, 본문 이력 0줄
- --history docs/manual 결과는 16줄 그대로(rc=1)
문제: check-work-docs.py --history는 리뷰·라운드 낱말 바로 뒤의 NN-NN만
발견 번호로 본다. 그래서 앞말 없이 나열한 "(05-01, 04-01, 06-01)",
"리뷰 01 영역 5.2절", "sample P30 결정"을 놓친다. 2026-11-07 docs/manual
이력 걷어내기에서 검사가 찾은 16줄을 고친 뒤 docs-writing.md 9절대로
grep으로 다시 읽으니 이 꼴 3줄이 더 있었다.
고른 방법: 패턴 셋을 더한다.
- 쉼표+공백이나 가운뎃점으로 이은 NN-NN 둘 이상. 콜론 뒤 줄 범위
("Foo.java:10-12,20-24")와 공백 없는 쉼표 범위는 잡지 않는다
- "리뷰 NN 영역", "NN 영역 N.N절"
- 2026-09-25 리뷰 후속 묶음 번호 P10~P49와 "W3-P30" 꼴
버린 대안:
- 홀로 선 NN-NN 하나까지 잡기. 장 번호·범위 같은 보통 숫자가 걸린다
- P 뒤 두 자리를 모두 잡기. P95·P99 같은 백분위수가 걸린다
위험·한계: 검사는 여전히 아는 꼴만 잡는다. P1~P9 묶음 번호는 우선순위
P0~P3과 겹쳐 잡지 않는다. 문서가 자기 목록에 P10~P49 번호를 붙이면
이력이 아니어도 잡는다(docs/study/graphql-walkthrough.ko.md의 할 일
번호 P10·P11). 지금 검사 대상인 docs/work 본문과 docs/manual에는 그런
줄이 없다. 이 커밋만 있으면 --history docs/manual이 19줄, rc=1이다.
다음 커밋이 그 19줄을 걷어낸다. 기본 모드(docs/work 본문, 루트
CLAUDE.md)는 0줄 그대로다.
검증(desktop worktree, 다음 커밋까지 얹은 트리 8ff82a67과 같은 스크립트):
- 기준 커밋 73d39212의 docs/manual: 옛 스크립트 16줄, 새 스크립트 19줄.
더 잡은 3줄은 03-placement.md:40·:54, 05-idempotency.md:93이다
- 오탐 시험 14줄: 보통 문장 8줄(p95·P99, 콜론 뒤 줄 범위, 날짜 쌍,
홀로 선 번호, 장 번호)은 안 잡고 이력 6줄은 잡았다
- 노트북에서 docs/reviews 밖 *.md에 새 패턴을 돌려 걸린 65줄을 읽었다.
위 할 일 번호 4줄 말고는 모두 실제 이력 번호였다
- 기본 모드 rc=0, 본문 이력 0줄
문제: check-work-docs.py --history는 날짜 접두어(MMDD/), RR 접두어,
묶음 이름, round 폴더, 번호만 쓴 결정, 커밋 sha만 이력 ID로 본다.
그래서 "리뷰 02-01 결정", "1라운드 06-01·06-03", "리뷰 README 13절"처럼
날짜 접두어 없이 쓴 리뷰 번호를 놓친다. 2026-11-06 docs/manual 이력
걷어내기 시험에서 --history가 0을 냈는데, 손으로 찾으니 16줄이 남아
있었다.
고른 방법: 패턴 셋을 더한다.
- 리뷰·라운드·review 낱말 뒤 20자 안에 홀로 선 NN-NN. 2026-11-01 같은
날짜의 일부는 홀로 선 번호가 아니라 잡지 않는다
- 한국어 라운드 번호(1라운드, 라운드6)
- 리뷰 README 절 번호(리뷰 README 13절)
버린 대안: 앞말 없이 모든 NN-NN을 잡기. 장 번호·시각 범위 같은 보통
숫자까지 잡아 오탐이 많다.
위험·한계: 검사는 아는 꼴만 잡는다. 다른 꼴은 걷어낸 뒤 grep으로 한 번
더 읽는다(docs-writing.md 자주 하는 실수). 이 커밋 뒤 --history
docs/manual은 16줄을 내고 rc=1이 된다. 그 16줄은 이번에 고치지 않는다.
다음 cold-read 시험 과제다. 기본 모드(docs/work 본문, 루트 CLAUDE.md)는
0줄 그대로다.
검증:
- 고치기 전 python3 scripts/check-work-docs.py --history docs/manual
결과 0줄, rc=0
- 고친 뒤 같은 명령 결과 16줄, rc=1. 2026-11-06 시험 세션이 손으로 찾은
16줄과 같다
- 오탐 시험 12건(보통 문장 7, 이력 5)이 모두 기대대로 나왔다
- 기본 모드 rc=0, 본문 이력 0줄. desktop worktree에서도 같다
문제: 옛 개선 매뉴얼은 진입 경로가 717줄이었고 본문에 지난 리뷰 ID가 든
줄이 많아, 이력을 모르는 세션은 근거를 따라가지 못했다. 이것을 사람 눈으로만
지키면 다시 늘어난다. 리뷰 색인도 손으로 옮기다 발견 5건이 빠져 어떤 수정
묶음에도 배정되지 않은 적이 있다(원래 리뷰 124건이 색인에는 119건).
고른 방법: Gradle 밖 Python 스크립트 두 개를 둔다(2026-11-06 소유자 결정 D6:
이 repo는 문서를 파싱하는 Gradle 검사를 두지 않는다).
- check-work-docs.py: 지도(CLAUDE.md)와 docs/work/의 분량 상한(지도 120,
README 80, playbook 150, 진입 경로 350), playbook 9칸 뼈대, 「자주 하는
실수」 10줄, 본문 이력 ID 0(evidence.md와 reference/의 두 색인 문서는 제외),
상대 링크를 본다. --links, --history 모드로 다른 문서에도 쓴다.
- check-review-index.py: 리뷰 폴더의 영역 문서 제목에 있는 발견 ID가 README
색인에 모두 있는지 본다. 범위(A~B)와 이어 쓰기(A·07)를 읽고, NN- 자리표시자를
잡는다.
정규식은 re.ASCII로 쓴다. Python의 \w·\b가 한글을 단어 문자로 봐서
"RR6-01-07과" 같은 표기를 놓쳤다.
버린 대안: document-contract Gradle lane(이 repo 원칙과 충돌), 검사 없이
cold-read 시험에서만 확인(매번 사람이 세야 한다).
위험·한계: check-work-docs.py가 보는 docs/work/는 다음 커밋에 들어온다. 이
커밋만으로는 "missing"으로 실패한다. 이력 ID 패턴은 이 repo가 쓴 형식만 안다
(MMDD/, RR<n>-, 묶음 이름, round<n>, 번호만 쓴 결정, 커밋 sha). 색인 검사는
"이름이 있나"만 보고 고쳤는지는 보지 않는다.
검증
- check-review-index.py docs/reviews/2026-11-01-maturity-review
--index-heading "12. 발견 색인": 124/124, rc=0
- 같은 폴더를 사고 시점 34565130에서 꺼내 돌림: NN-10~NN-14 5건, rc=1
- check-review-index.py docs/reviews/2026-11-03-rereview: 157 중 135, rc=1
(README가 ID 대신 내용·건수로 적은 22건)
- check-work-docs.py를 일부러 망가뜨린 사본 18가지에 돌림: 이력 ID 7형식,
분량 3종, 뼈대, 실수 줄 수, 깨진 링크, 빠진 파일은 rc=1, ID가 허용된 파일과
"결정 3개" 같은 개수 표현은 rc=0