docs(agents)!: 루트 AGENTS.md를 40줄 정본으로 줄이고 CLAUDE.md가 가져온다

루트에 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행.
This commit is contained in:
DongHyeonka
2026-11-07 21:59:42 +09:00
parent 08f932123a
commit 3c73fc333c
48 changed files with 336 additions and 490 deletions
+2 -2
View File
@@ -36,7 +36,7 @@
7. 링크: repo 안 문서는 상대 링크로 쓴다. repo 밖 문서(design-docs 등)와 `file:line`은 링크가 아니라 코드 표기로 쓴다. 링크 검사(lychee)가 따라가지 못하기 때문이다.
8. 숫자를 복제하지 않는다. leaf 개수, 테스트 수처럼 코드가 정하는 값은 쓰는 순간 낡는다. 정본을 가리킨다.
9. 그 문서를 읽는 테스트가 있는지 찾는다: `grep -rn -e '<파일 이름>' -e '<폴더 경로>' src --include=*.java`. 있으면 그 테스트가 기대하는 문장을 지키고, 그 lane을 desktop에서 돌린다([reference/gates.md](reference/gates.md) 2절). 없으면(주석만 걸리는 것도 없음이다) lane은 돌리지 않고, grep 명령과 결과를 보고에 적는다. brief가 돌릴 lane을 정했으면 그 lane을 돌린다(지도 3절: brief가 먼저다).
10. `docs/work/`, 루트 `CLAUDE.md`, `AGENTS.md`, `src/**/CLAUDE.md`를 바꿨으면 `python3 scripts/check-work-docs.py`를 돌린다. 분량 상한, 본문 이력 ID 0(앞의 넷 모두), playbook 뼈대, 상대 링크를 본다.
10. `docs/work/`, 루트 `AGENTS.md`·`CLAUDE.md`, `src/**/AGENTS.md`, `.claude/` 아래 문서를 바꿨으면 `python3 scripts/check-work-docs.py`를 돌린다. 분량 상한, 본문 이력 ID 0(앞의 넷 모두), playbook 뼈대, 상대 링크를 본다.
11. 리뷰 폴더 README를 만들거나 고쳤으면 `python3 scripts/check-review-index.py docs/reviews/<폴더>`를 돌린다.
12. 다른 문서는 같은 스크립트의 모드로 본다: 상대 링크는 `--links <파일 또는 폴더>`(PR에서는 lychee가 다시 본다), 이력 ID는 `--history <파일 또는 폴더>`.
- 이력 검사 패턴을 더하면 오탐을 시험한다. 잡아야 할 이력 문장과 잡지 말아야 할 보통 문장을 시험 파일로 만들어 `--history`로 돌린다. `docs/reviews/**` 밖 전체(`git ls-files '*.md' ':!docs/reviews'`)에도 돌려 새로 걸린 줄을 모두 읽는다. 검사 대상 파일의 오탐은 패턴을 좁혀 없애고, 대상 밖의 오탐은 보고에 적는다.
@@ -52,7 +52,7 @@
- 독자 한 문장이 있고, 문서가 그 독자의 일을 처음부터 끝까지 다룬다.
- 문서의 명령·태스크 이름·경로가 기준 커밋에 실제로 있다.
- 정본을 복사한 문장이 없다. 가리키는 줄만 있다.
- `docs/work/`·루트 `CLAUDE.md`·`AGENTS.md`·`src/**/CLAUDE.md`를 바꿨으면 `scripts/check-work-docs.py`가 rc=0이다.
- `docs/work/`·루트 `AGENTS.md`·`CLAUDE.md`·`src/**/AGENTS.md`·`.claude/` 아래 문서를 바꿨으면 `scripts/check-work-docs.py`가 rc=0이다.
- 그 문서를 읽는 document-contract lane이 있으면 rc=0이다(desktop 로그).
- 매뉴얼을 새로 만들었거나 진입 경로를 바꿨으면 cold-read 시험이나 자가 점검 결과가 보고에 있다.