루트에 CLAUDE.md와 AGENTS.md가 둘 다 있으면 Claude Code 기본 설정은 AGENTS.md를 읽지 않는다. 그래서 344줄 정본은 세션이 스스로 열 때만 닿았고, 두 문서가 같은 규칙을 아홉 군데 따로 적었다. 지켜야 할 규칙은 모두 문서에만 있어서 포맷·레이어 위반·문서 검사 실패가 desktop 게이트에서야 보였다.
소유자가 2026-11-07에 하네스 재설계(design-docs harness/01-harness-design.md 13절)를 정했다. 이 PR이 백엔드에 적용한다: 루트 지침 40줄 정본, 하위 폴더 AGENTS.md, 편집 훅, Agent 금지 해제와 서브에이전트, 모델이 부르는 스킬, repo 장부. 쌓인 매뉴얼 빈틈도 한 묶음으로 넣었다(소유자 결정).
코드·설정·빌드의 동작은 바뀌지 않는다. Java 변경은 테스트가 읽는 문서 경로와 테스트 주석뿐이다.
고른 방법과 버린 대안
루트: AGENTS.md(37줄: 무엇인가·HARD-STOP·지도·맡은 일·검증·일하는 방식) + CLAUDE.md(@AGENTS.md + Claude 전용 줄). 버림: 루트 120줄(설계 권함, 소유자가 자료 쪽 20~40줄로 정함), 심볼릭 링크(Edit 도구가 링크를 통해 쓰지 않음).
하위: src/**/CLAUDE.md 28개를 같은 폴더 AGENTS.md로 옮기고 CLAUDE.md는 @AGENTS.md 한 줄. 이 세션에서 하위 CLAUDE.md의 가져오기가 펼쳐지는 것을 확인했다. family 문서 넷 새로. 폴더를 가로지르는 파일 종류 규칙(테스트·설정·Docker·문서)은 .claude/rules/의 paths 규칙.
훅: 편집 직후 Java 한 파일을 Gradle 없이 google-java-format(카탈로그 버전, Gradle 캐시의 jar, Spotless와 같은 --skip-reflowing-long-strings)으로 맞춘다. 이 옵션으로 Spotless 대상 파일 전부를 dry-run 하면 차이가 0이었다. 레이어 넛지 N1, 문서 넛지 N2, 턴 끝 desktop 검증 넛지 N5, 적용된 migration 편집 차단 H13, .env deny. 버림: 편집 훅에서 검사 안 하기(설계 권함, 소유자가 자료 쪽으로), 편집마다 desktop 원격 실행, checkstyle 한 파일(Gradle 없이 classpath를 못 맞춤).
서브에이전트 셋(arch-reviewer, verify-api, code-simplifier)은 결과만 돌려주고 쓰기 도구가 없다. 파일을 바꾸는 위임은 하위 세션.
스킬 new-feature, desktop-gates는 정본 playbook을 가리키는 실행 순서표다. 버림: verify 스킬(내장 /verify와 이름이 겹치고, 검증 진입점 스크립트는 CI 재편 몫).
장부 docs/ledger/estimates.jsonl은 더하기만 하는 JSON Lines이고 .gitattributes가 merge=union을 준다(여러 브랜치가 끝에 줄을 더해도 병합이 안 멈춤).
검사: check-docs.py에 link(lychee 범위 밖으로 나간 지침 문서의 상대 링크를 PR에서 계속 보려고)와 style(문체), check-work-docs.py에 지도 40줄·CLAUDE.md 10줄·첫 줄 가져오기·하위 짝 검사. workflow 파일은 CI 재편 몫이라 고치지 않았다.
위험과 영향
파생 서비스: 지침 파일 자리, .claude/ 설정, Agent 허용, skills-lock.json 삭제가 넘어간다. docs/upgrade/2026-11-harness.md에 행 여덟과 할 일을 적었다. 커밋 여섯에 !가 있다(행 여덟).
훅은 세션이 시작할 때 읽힌다. 이 세션에서는 settings를 바꿔도 돌지 않아, settings가 부르는 명령에 같은 입력을 넣어 확인했다. 머지 뒤 새 세션에서 처음 돈다.
서브에이전트가 Bash로 파일을 바꾸는 것은 도구 목록으로 막지 못한다. 정의 본문이 읽기 명령만 쓰라고 하고, 노트북 Gradle·Docker는 소유자 전역 훅이 막는다.
스킬 설명 둘이 스킬 목록 예산(창의 1%)을 조금 더 쓴다. 전역 스킬 정리는 전역 설정 세션 몫이다.
정한 기본값(소유자 확인 대상): trivy 취약점 DB 받기는 설치가 아니다, 병합 커밋에는 충돌 해결만, @DisplayName은 고친 메서드만.
Gitea 서버 쪽 병합이 merge=union을 쓰는지는 확인하지 못했다.
leaf 지역 규칙이 200줄을 넘던 셋(application-core 337, persistence-jpa 357, graphql 218)은 총괄 결정(2026-11-07)대로 표·계약을 그 leaf README 끝으로 옮겼다(190·194·185줄). 템플릿 패키지 목록의 정본이 src/application-core/README.md가 되어 TemplatePackageOwnershipDocumentTest가 그 파일을 읽는다(단언은 그대로).
운영 코드 주석 넷(persistence-jpa failure·transaction)은 "CLAUDE.md의 표"를 가리킨다. 업무 코드라 고치지 않았고, CLAUDE.md → AGENTS.md → README 포인터로 닿는다.
최종 트리 c487f30f(= head a0a77575, 위 트리 + 장부 실측 한 줄): 바뀐 것이 docs/ledger/뿐이라 그 검사만 다시 돌렸다. unittest 147, check-docs.py, check-work-docs.py, check-repo-layout.py, :app-bootstrap:documentContractTest --rerun(68) 모두 rc=0.
중단한 실행(증거로 쓰지 않음): 49f27a5f(leaf 정리 전, :ci·verifyStrictLaneStages만 끝남, rc=0), e5dcc93b(main 합치기 전, 앞 12개 rc=0). 트리가 바뀌어 멈췄다. 로그 ~/h3-backend-harness-logs-run1/, -run2/.
훅·검사기 시험(노트북): 훅 29건(실제 포매터 시험은 노트북 Gradle 캐시의 1.35.0 jar로 돎), 변이 10개(조건 하나씩 끔)마다 1~2건 실패. 운영 소스 3,230개에 N1을 돌려 거짓 양성 0. --skip-reflowing-long-strings 포매터 dry-run이 Spotless 대상 파일 전부에서 차이 0. check-work-docs 시험 15건, 변이 7개마다 실패. check-docs 링크·문체 시험, 변이 셋마다 실패. 하위 CLAUDE.md의 @AGENTS.md 가져오기는 이 세션에서 domain-core 파일을 열어 본문이 읽히는 것을 봤다. 훅 설정은 세션이 시작할 때 읽혀서, settings가 부르는 명령에 같은 입력을 넣어 확인했다.
리뷰어가 볼 곳
루트 AGENTS.md(37줄)·CLAUDE.md, 아래 「옮긴 규칙」 표에서 빠진 규칙이 없는지.
scripts/hooks/hooks.py: N1의 금지 목록이 ArchUnit·purity 태스크와 같은지, N5가 턴 끝을 막는 조건.
.claude/agents/*: 쓰기 도구가 없는지, verify-api가 desktop 절차를 지키는지.
설계·결정: design-docs harness/01-harness-design.md 13절(소유자 결정 2026-11-07).
파생 서비스 안내: docs/upgrade/2026-11-harness.md.
처리 표: docs/work/evidence.md 12절. 장부: docs/ledger/estimates.jsonl.
이 브랜치 밖의 몫: 전역 ~/.claude와 하네스 플러그인(H2), 검증 진입점 스크립트와 workflow(CI 재편), design-docs 문구(docs-system.md 4.1절의 결정 기록 머리 문구, 6.1·6.2절의 CLAUDE.md 언급, 위임 장부 3회차 「매뉴얼 수정」 칸).
부록: 옮긴 규칙과 매뉴얼 보강
옮긴 규칙 (옛 자리 → 새 자리)
옛 루트 AGENTS.md(344줄)
옛 절
새 자리
프로젝트 정체성
루트 AGENTS.md 첫 문단
Prime Directive·HARD-STOP 7
루트 AGENTS.md 「HARD-STOP」(한 벌만)
Superpowers Workflow
지움(스킬 설명·플러그인과 중복). 서브에이전트 기준 한 줄은 AGENTS.md 「일하는 방식」, 자세히는 docs/work/delegate.md 4.3절
Gradle 정책 권위(registry·settings·build-logic·저장소 읽는 테스트·lane 캐시·성능 lane·verifyEnvKeys·verifyStrictLaneStages 세는 규칙)
src/build-logic/AGENTS.md(새). verifyEnvKeys 결정은 reference/decisions.md 기존 행
하위 src/**/CLAUDE.md 28개: 같은 폴더 AGENTS.md로 옮기고 CLAUDE.md는 @AGENTS.md 한 줄. family 문서 넷 새로(src/adapter/inbound, src/adapter/outbound, src/composition, src/build-logic).
200줄 넘던 지역 규칙 셋(총괄 결정 2026-11-07) — 옮긴 절은 그 leaf README.md 끝 「지역 규칙에서 옮긴 표와 계약」, 지역 규칙에는 포인터와 지킬 규칙 몇 줄:
옛 자리(지역 규칙의 절)
새 자리
application-core 「계약 타입」
src/application-core/README.md 같은 절
application-core 「패키지 소유 (Package ownership)」 표
같은 README 같은 절(템플릿 패키지 목록의 정본, TemplatePackageOwnershipDocumentTest가 읽음)
## 무엇을, 왜
- 루트에 `CLAUDE.md`와 `AGENTS.md`가 둘 다 있으면 Claude Code 기본 설정은 `AGENTS.md`를 읽지 않는다. 그래서 344줄 정본은 세션이 스스로 열 때만 닿았고, 두 문서가 같은 규칙을 아홉 군데 따로 적었다. 지켜야 할 규칙은 모두 문서에만 있어서 포맷·레이어 위반·문서 검사 실패가 desktop 게이트에서야 보였다.
- 소유자가 2026-11-07에 하네스 재설계(design-docs `harness/01-harness-design.md` 13절)를 정했다. 이 PR이 백엔드에 적용한다: 루트 지침 40줄 정본, 하위 폴더 `AGENTS.md`, 편집 훅, Agent 금지 해제와 서브에이전트, 모델이 부르는 스킬, repo 장부. 쌓인 매뉴얼 빈틈도 한 묶음으로 넣었다(소유자 결정).
- 코드·설정·빌드의 동작은 바뀌지 않는다. Java 변경은 테스트가 읽는 문서 경로와 테스트 주석뿐이다.
## 고른 방법과 버린 대안
- 루트: `AGENTS.md`(37줄: 무엇인가·HARD-STOP·지도·맡은 일·검증·일하는 방식) + `CLAUDE.md`(`@AGENTS.md` + Claude 전용 줄). 버림: 루트 120줄(설계 권함, 소유자가 자료 쪽 20~40줄로 정함), 심볼릭 링크(Edit 도구가 링크를 통해 쓰지 않음).
- 하위: `src/**/CLAUDE.md` 28개를 같은 폴더 `AGENTS.md`로 옮기고 `CLAUDE.md`는 `@AGENTS.md` 한 줄. 이 세션에서 하위 `CLAUDE.md`의 가져오기가 펼쳐지는 것을 확인했다. family 문서 넷 새로. 폴더를 가로지르는 파일 종류 규칙(테스트·설정·Docker·문서)은 `.claude/rules/`의 `paths` 규칙.
- 훅: 편집 직후 Java 한 파일을 Gradle 없이 google-java-format(카탈로그 버전, Gradle 캐시의 jar, Spotless와 같은 `--skip-reflowing-long-strings`)으로 맞춘다. 이 옵션으로 Spotless 대상 파일 전부를 dry-run 하면 차이가 0이었다. 레이어 넛지 N1, 문서 넛지 N2, 턴 끝 desktop 검증 넛지 N5, 적용된 migration 편집 차단 H13, `.env` deny. 버림: 편집 훅에서 검사 안 하기(설계 권함, 소유자가 자료 쪽으로), 편집마다 desktop 원격 실행, checkstyle 한 파일(Gradle 없이 classpath를 못 맞춤).
- 서브에이전트 셋(`arch-reviewer`, `verify-api`, `code-simplifier`)은 결과만 돌려주고 쓰기 도구가 없다. 파일을 바꾸는 위임은 하위 세션.
- 스킬 `new-feature`, `desktop-gates`는 정본 playbook을 가리키는 실행 순서표다. 버림: verify 스킬(내장 `/verify`와 이름이 겹치고, 검증 진입점 스크립트는 CI 재편 몫).
- 장부 `docs/ledger/estimates.jsonl`은 더하기만 하는 JSON Lines이고 `.gitattributes`가 `merge=union`을 준다(여러 브랜치가 끝에 줄을 더해도 병합이 안 멈춤).
- 검사: `check-docs.py`에 `link`(lychee 범위 밖으로 나간 지침 문서의 상대 링크를 PR에서 계속 보려고)와 `style`(문체), `check-work-docs.py`에 지도 40줄·`CLAUDE.md` 10줄·첫 줄 가져오기·하위 짝 검사. workflow 파일은 CI 재편 몫이라 고치지 않았다.
## 위험과 영향
- 파생 서비스: 지침 파일 자리, `.claude/` 설정, Agent 허용, `skills-lock.json` 삭제가 넘어간다. `docs/upgrade/2026-11-harness.md`에 행 여덟과 할 일을 적었다. 커밋 여섯에 `!`가 있다(행 여덟).
- 훅은 세션이 시작할 때 읽힌다. 이 세션에서는 settings를 바꿔도 돌지 않아, settings가 부르는 명령에 같은 입력을 넣어 확인했다. 머지 뒤 새 세션에서 처음 돈다.
- 서브에이전트가 Bash로 파일을 바꾸는 것은 도구 목록으로 막지 못한다. 정의 본문이 읽기 명령만 쓰라고 하고, 노트북 Gradle·Docker는 소유자 전역 훅이 막는다.
- 스킬 설명 둘이 스킬 목록 예산(창의 1%)을 조금 더 쓴다. 전역 스킬 정리는 전역 설정 세션 몫이다.
- 정한 기본값(소유자 확인 대상): trivy 취약점 DB 받기는 설치가 아니다, 병합 커밋에는 충돌 해결만, `@DisplayName`은 고친 메서드만.
- Gitea 서버 쪽 병합이 `merge=union`을 쓰는지는 확인하지 못했다.
- leaf 지역 규칙이 200줄을 넘던 셋(application-core 337, persistence-jpa 357, graphql 218)은 총괄 결정(2026-11-07)대로 표·계약을 그 leaf README 끝으로 옮겼다(190·194·185줄). 템플릿 패키지 목록의 정본이 `src/application-core/README.md`가 되어 `TemplatePackageOwnershipDocumentTest`가 그 파일을 읽는다(단언은 그대로).
- 운영 코드 주석 넷(persistence-jpa failure·transaction)은 "CLAUDE.md의 표"를 가리킨다. 업무 코드라 고치지 않았고, CLAUDE.md → AGENTS.md → README 포인터로 닿는다.
- main(`9fbf72fb`, PR #4)을 `248df518`로 합쳤다. 충돌은 없었다.
## 검증
desktop worktree, 공유 잠금(`flock /tmp/claude-gates/heavy.lock`) 아래, Gradle 명령마다 `--no-build-cache`, 새 detached worktree. 노트북 `git rev-parse HEAD^{tree}`와 desktop `git write-tree`가 같은 트리에서 돌렸다. 로그는 desktop `~/h3-backend-harness-logs/`(명령별 `<이름>.log`, 결과 XML `<이름>-xml.tgz`, 요약 `summary.tsv`).
**합친 트리 `9898949b`(= 커밋 `248df518`, main `9fbf72fb` + 이 브랜치), 22:43~23:10, 모두 rc=0, FROM-CACHE 0**
| 단계 | 명령 | 실제 실행 |
| --- | --- | --- |
| PR (가) | `:ci :verifyDependencyLocks --warning-mode=fail` | 392초, 태스크 1048 executed, 테스트 7390(skip 28, 실패 0) |
| PR (가) | `:verifyStrictLaneStages --dry-run`, `-p platforms/optional-build` 같은 검사 | rc=0 둘 |
| PR (가) | `-p platforms/optional-build ci` | 71초, 테스트 593(실패 0) |
| PR (가) | `verify-compose-profile-contracts.sh`, `check-repo-layout.py`, `unittest`(147건), `check-docs.py`, `check-work-docs.py` | rc=0 |
| brief | `:app-bootstrap:documentContractTest --rerun` | 테스트 68(실패 0) |
| brief | `:app-bootstrap:repositoryContractTest --rerun` | 테스트 65(skip 1: `src/.env`가 있어야 도는 로컬 전용 계약, 이전부터) |
| brief | `:adapter:outbound:persistence-mongo:test --tests '*MongoNamespaceContractTest' --rerun` | 테스트 3 |
| PR (나) build-logic | `-p build-logic test` | 테스트 174 |
| PR (나) fileserver-pr 5 job | 그 job의 `run` 줄 그대로 | 앞 셋은 같은 worktree에서 `:ci`가 만든 결과라 UP-TO-DATE, 필터 둘은 실행(테스트 30, 2) |
| PR (나) messaging-certification | `:messaging:messaging-kafka:verifyMessagingCertificationEvidence` | 테스트 37 |
| PR (나) notification-platform `pr` 7줄 | 그 job의 `run` 줄 그대로 | 1~4·7은 `:ci` 결과로 UP-TO-DATE, `jpaPlatformContractTest` 432, `jpaPlatformMigrationTest` 45 |
| PR (나) object-storage | `objectStorageMinioContractTest` | 테스트 19 |
| PR (나) redis-sdk-topology(PR은 standalone 7.4) | compose up → digest → 세 leaf `redisTopologyTest` → down | 테스트 122 |
| PR (나) pr-adapters web·websocket·httpclient·jpa | 걸린 lane의 `run` 줄(행렬 값마다) | web 35, websocket Jetty 8·nginx 4, httpclient apache 17·jdk 17·spring70 23, jpa PostgreSQL 16 432·18 432·migration 45 |
| PR (다) link-check | lychee 0.22.0 공식 이미지, workflow와 같은 범위 | 643 링크, 오류 0(main 트리 656, 오류 0) |
| PR (다) trivy-fs 차단 줄 | trivy 0.71.2 공식 이미지, `--severity CRITICAL,HIGH --exit-code 1` | rc=0(main 트리도 rc=0). DB는 이번에 받음(2026-11-07 14:10 UTC) |
| PR (다) buf, dependency-review | — | 해당 없음: `.proto`·lockfile·카탈로그 변경 없음 |
**최종 트리 `c487f30f`(= head `a0a77575`, 위 트리 + 장부 실측 한 줄)**: 바뀐 것이 `docs/ledger/`뿐이라 그 검사만 다시 돌렸다. `unittest` 147, `check-docs.py`, `check-work-docs.py`, `check-repo-layout.py`, `:app-bootstrap:documentContractTest --rerun`(68) 모두 rc=0.
**중단한 실행(증거로 쓰지 않음)**: `49f27a5f`(leaf 정리 전, `:ci`·`verifyStrictLaneStages`만 끝남, rc=0), `e5dcc93b`(main 합치기 전, 앞 12개 rc=0). 트리가 바뀌어 멈췄다. 로그 `~/h3-backend-harness-logs-run1/`, `-run2/`.
**훅·검사기 시험(노트북)**: 훅 29건(실제 포매터 시험은 노트북 Gradle 캐시의 1.35.0 jar로 돎), 변이 10개(조건 하나씩 끔)마다 1~2건 실패. 운영 소스 3,230개에 N1을 돌려 거짓 양성 0. `--skip-reflowing-long-strings` 포매터 dry-run이 Spotless 대상 파일 전부에서 차이 0. `check-work-docs` 시험 15건, 변이 7개마다 실패. `check-docs` 링크·문체 시험, 변이 셋마다 실패. 하위 `CLAUDE.md`의 `@AGENTS.md` 가져오기는 이 세션에서 domain-core 파일을 열어 본문이 읽히는 것을 봤다. 훅 설정은 세션이 시작할 때 읽혀서, settings가 부르는 명령에 같은 입력을 넣어 확인했다.
## 리뷰어가 볼 곳
- 루트 `AGENTS.md`(37줄)·`CLAUDE.md`, 아래 「옮긴 규칙」 표에서 빠진 규칙이 없는지.
- `scripts/hooks/hooks.py`: N1의 금지 목록이 ArchUnit·purity 태스크와 같은지, N5가 턴 끝을 막는 조건.
- `.claude/agents/*`: 쓰기 도구가 없는지, `verify-api`가 desktop 절차를 지키는지.
- `scripts/check-docs.py`의 `link`·`style`, `scripts/check-work-docs.py`의 상한·짝 검사.
- 정한 기본값 셋(위험과 영향).
## 관련
- 설계·결정: design-docs `harness/01-harness-design.md` 13절(소유자 결정 2026-11-07).
- 파생 서비스 안내: `docs/upgrade/2026-11-harness.md`.
- 처리 표: `docs/work/evidence.md` 12절. 장부: `docs/ledger/estimates.jsonl`.
- 이 브랜치 밖의 몫: 전역 `~/.claude`와 하네스 플러그인(H2), 검증 진입점 스크립트와 workflow(CI 재편), design-docs 문구(`docs-system.md` 4.1절의 결정 기록 머리 문구, 6.1·6.2절의 `CLAUDE.md` 언급, 위임 장부 3회차 「매뉴얼 수정」 칸).
## 부록: 옮긴 규칙과 매뉴얼 보강
#### 옮긴 규칙 (옛 자리 → 새 자리)
옛 루트 `AGENTS.md`(344줄)
| 옛 절 | 새 자리 |
| --- | --- |
| 프로젝트 정체성 | 루트 `AGENTS.md` 첫 문단 |
| Prime Directive·HARD-STOP 7 | 루트 `AGENTS.md` 「HARD-STOP」(한 벌만) |
| Superpowers Workflow | 지움(스킬 설명·플러그인과 중복). 서브에이전트 기준 한 줄은 `AGENTS.md` 「일하는 방식」, 자세히는 `docs/work/delegate.md` 4.3절 |
| Gradle 정책 권위(registry·settings·build-logic·저장소 읽는 테스트·lane 캐시·성능 lane·`verifyEnvKeys`·`verifyStrictLaneStages` 세는 규칙) | `src/build-logic/AGENTS.md`(새). `verifyEnvKeys` 결정은 `reference/decisions.md` 기존 행 |
| 소유 leaf·focused test 명령 | 루트 `AGENTS.md` 「검증」 |
| 커밋 정책 | 루트 `AGENTS.md` 「일하는 방식」 + `docs/work/README.md` 4절(기존) |
| 강제 수준 | 지움(설명문) |
| 모듈 책임(family별) | `src/adapter/inbound/AGENTS.md`·`src/adapter/outbound/AGENTS.md`·`src/composition/AGENTS.md`(새), core leaf `AGENTS.md`(기존 책임·금지) |
| 의존성 방향 | 루트 `AGENTS.md` 「지도」 |
| 기능 개발 프로토콜 10단계 | `docs/work/new-feature.md`(기존 절차) + 스킬 `new-feature`. 설계서·계획서 머리 블록은 `research-design.md`(기존) |
| 계층별 테스트 기준 | 각 계층 `AGENTS.md` 「테스트」(domain-core, application-core, app-bootstrap, adapter family 둘) |
| 테스트 작성 규칙 1~6, GWT 게이트 없음 | `.claude/rules/java-tests.md`(테스트 소스를 열 때 읽힘). 번호 그대로라 코드 주석의 "AGENTS.md test rule 6"은 루트 지도의 위치 줄로 닿는다 |
| 검증 원칙 | 지움(HARD-STOP 6, 전역 규칙과 중복) |
| 권장 Gradle 명령 11줄 | `reference/gates.md` 1절(기존 표) + 루트 「검증」 + 스킬 `desktop-gates` |
| capability 규칙·완료 기준 7·기본값 위치·라이브러리형 예외 | `docs/manual/10-capabilities.md`(이제 정본) + 루트 지도 한 줄 |
| 설정과 런타임, Docker 규칙 | `.claude/rules/settings-and-runtime.md`(설정·Dockerfile·compose 경로) + `.env` 권한 deny |
| 템플릿 재사용 체크리스트 9개 | 루트 `README.md` 「새 서비스로 시작하기」(빠졌던 넷: proto 조직 이름, 이미지·앱 이름, env 예시, 문서) |
| 금지된 지름길 | 1~6은 지움(HARD-STOP 1~4와 같은 말). 범위 밖 리팩터링·사용자 변경 되돌리기·파괴적 git은 루트 「일하는 방식」 |
| 작업 보고 규칙 | 지움(`docs/work/README.md` 6절, 전역 규칙) |
옛 루트 `CLAUDE.md`(75줄)
| 옛 절 | 새 자리 |
| --- | --- |
| 1 이 repo | 루트 `AGENTS.md` 첫 문단·지도 |
| 2 HARD-STOP 요약 | 루트 `AGENTS.md`(중복 제거) |
| 3 맡은 일 → playbook | 루트 `AGENTS.md` 「맡은 일」 |
| 4 실행 위치·검증 명령 | 루트 「검증」, `CLAUDE.md` 소유자 환경 줄, `operate.md` 4.1절, 스킬 `desktop-gates`, 훅 N5 |
| 4 문서 검사 명령 | 루트 「검증」 + 훅 N2 + `.claude/rules/docs.md` |
| 5 최상위 폴더·leaf 목록·capability 한 줄 | 루트 「지도」 + `check-repo-layout.py` |
| 5 messaging은 계층 아님, gRPC는 다른 빌드 | 루트 지도 한 줄 + `src/platforms/messaging/AGENTS.md`·`src/platforms/grpc/AGENTS.md`(기존) |
| 5 composition은 조립만 | 루트 지도 한 줄 + `src/composition/AGENTS.md`(새) |
| 5 새 기능 예시 | `new-feature.md`(기존) + 스킬 `new-feature` |
| 5 성능 lane 단언 스위치 없음 | `src/build-logic/AGENTS.md` + `.claude/rules/java-tests.md` + `gates.md` 5절 |
| 5 저장소 파일을 읽는 테스트 태그 | `.claude/rules/java-tests.md`·`docs.md` + `src/build-logic/AGENTS.md` |
| 5 커밋 정책, 문서 위치 | 루트 「일하는 방식」·「지도」 + `.claude/rules/docs.md` |
| 6 소유자 환경, Agent 금지 | `CLAUDE.md` 「Claude Code에서만」. Agent 금지는 풀림(`delegate.md` 4.3절) |
하위 `src/**/CLAUDE.md` 28개: 같은 폴더 `AGENTS.md`로 옮기고 `CLAUDE.md`는 `@AGENTS.md` 한 줄. family 문서 넷 새로(`src/adapter/inbound`, `src/adapter/outbound`, `src/composition`, `src/build-logic`).
200줄 넘던 지역 규칙 셋(총괄 결정 2026-11-07) — 옮긴 절은 그 leaf `README.md` 끝 「지역 규칙에서 옮긴 표와 계약」, 지역 규칙에는 포인터와 지킬 규칙 몇 줄:
| 옛 자리(지역 규칙의 절) | 새 자리 |
| --- | --- |
| application-core 「계약 타입」 | `src/application-core/README.md` 같은 절 |
| application-core 「패키지 소유 (Package ownership)」 표 | 같은 README 같은 절(템플릿 패키지 목록의 정본, `TemplatePackageOwnershipDocumentTest`가 읽음) |
| application-core 「정해진 유스케이스 모양」 | 같은 README 같은 절 |
| application-core 「멱등성 (KEYED)」 | 같은 README 같은 절 |
| persistence-jpa 「Spring 조립 소유」「플랫폼 lane」「vendor 고르기」(+「capability로 막은 store」) | `src/adapter/outbound/persistence-jpa/README.md` 같은 절 |
| persistence-jpa 「TransactionPort 구현 계약」(+「inNew 풀 크기 제약」) | 같은 README 같은 절 |
| persistence-jpa 「영속 실패 번역 계약」(SQLState 표), 「영속 감사 계약」 | 같은 README 같은 절 |
| graphql 「구현된 플랫폼 범위 — 등급으로 말한다」 | `src/adapter/inbound/graphql/README.md` 같은 절 |
#### 매뉴얼 보강 (항목 → 넣은 자리 또는 넣지 않은 이유)
| 원천 | 항목 | 자리 |
| --- | --- | --- |
| 공유 노트 목록 | 충돌 없음은 `git merge-tree`로 | `delegate.md` 9절 |
| 공유 노트 목록 | PR 만들기 전 head 브랜치 PR을 API로 | `delegate.md` 9절 |
| 공유 노트 목록 | 결정 기록 머리 둘째 줄(번역 ADR) | `check-docs.py` `DECISION_LABEL`, `docs/README.md`, ADR 33개 머리 블록. design-docs `docs-system.md` 4.1절과 프론트는 범위 밖(총괄 몫) |
| 공유 노트 목록 | 문체 검사의 주인 | `check-docs.py` `style`(새) + `docs-writing.md` 4절 4 + runbook 10개 고침 |
| 공유 노트 목록 / i2 | smoke 이미지 출처, trivy DB, 테스트 Javadoc | `gates.md` 4절 「smoke 이미지」, `operate.md` 4.1절 + `decisions.md` 기본값, `improve.md` 4.2절 6 |
| 공유 노트 목록 / d2c | 영어 절 제목 인용, 머리말 없는 runbook, `@DisplayName` 범위 | `docs-writing.md` 4절 14, `.claude/rules/java-tests.md` 규칙 2 |
| 공유 노트 목록 / d2a | 레지스트리 yaml 번역 기준 | `docs-writing.md` 4절 14 |
| 공유 노트 목록 | check-repo-layout 설명과 지도 범위, template-vs-consumer | 루트 `AGENTS.md` 지도 줄 + `check-repo-layout.py` 설명, `docs/ci-cd/template-vs-consumer.md` 세 행 |
| 장부 3회차 G1 | brief 요약과 결정 원문이 다를 때 | `reference/decisions.md` 1절 1 |
| 장부 3회차 G1 | desktop 잠금을 여럿이 기다릴 때 | `gates.md` 4절 「공유 잠금 기다리기」 |
| 장부 3회차 G2 | 커밋하는 수정의 lockfile | `gates.md` 2절 탐침 |
| 장부 3회차 G2 | 원격 실행 멈추기(`pkill -f`) | `operate.md` 4.1절 |
| 장부 3회차 G3 | 절차 문서 결함의 RED, 대기 결함의 RED | `improve.md` 4.2절 3 |
| 장부 3회차 G3 | 검증 뒤 앞 커밋에 형식 수정 | `operate.md` 4.1절(나누기 전에 확인, 편집 훅) |
| 장부 3회차 G4 | 그 코드를 지키는 lane 찾기 | `improve.md` 4.2절 8 |
| 장부 3회차 G4 | upgrade 안내 「커밋:」 줄 동시 수정 | `delegate.md` 4.2절 표 |
| 장부 r9 통합 | OOM 재시작, 자원 의존 실패, `--no-build-cache` 차이, zsh `PIPESTATUS`, 처음 켜진 lane의 이전 실패 | `gates.md` 6절 표, 4절 「원래 있던 실패 가리기」, 3절, `operate.md` 4.1절, `gates.md` 3절 (나) 5 |
| 장부 1·2회차(1~22줄) | 빈틈 88건 | 넣지 않음 — 이미 반영(1회차 `73d39212`, 2회차 `3eb3b067`, 처리 표 `evidence.md` 9·11절). 운영 캐시 교훈은 `operate.md` 9절에 있음 |
| 장부 t1 | smoke 이미지 재사용 칸, `if` 안 `set -e`, leaf 데이터 폴더, 트리 해시로 묶기, 코드 주석 언어 | `gates.md` 4절, `gates.md` 6절, `new-feature.md` 6절(`release/`), 넣지 않음 — 이미 `operate.md` 4.1절 「push 전에 검증하기」, `docs-writing.md` 4절 4 |
| 장부 t1 노트 | review-criteria 10.1 문장, 코드 예 없는 기법 | `review-criteria.md` 6절 표, 넣지 않음 — 이미 `docs/manual/04`(83줄)·`05`(45줄)이 예가 없음을 밝히고 시험을 가리킨다 |
| 장부 d1 | 이동 커밋과 커밋마다 검사, Gradle 밖 검사 자리, 줄기만 하는 예외 목록, MANIFEST, scripts 시험 위치 | `docs-writing.md` 4절 13, `gates.md` 7절 1·8, 넣지 않음 — 이미 `docs/README.md` 「문서 검사」(FROZEN), `docs-writing.md` 4절 14, `gates.md` 7절 8 |
| 장부 i1 | 병합 커밋, FROZEN 지문, smoke 이미지, 순서 의존 재현, check-docs 줄, lychee·buf·trivy | `delegate.md` 4.2절, 넣지 않음 — 이미 `docs/README.md`, `gates.md` 4절 둘, `docs-writing.md`·`review-criteria.md` 9절, `gates.md` 3절 (다) |
| 프론트 총괄 교훈(장부 41) | 위 목록 첫 둘 | 위와 같음 |
| 장부 1·33·43줄 | 결정 질문 상자 닫기, 훅 빈틈 넷, live 클러스터 적용 | 넣지 않음 — design-docs `delegation-loop.md` 몫(백엔드 아님) |
| 01-backend-layout 10.1 | 관점 2·9·18·20·27, 시나리오 | `review-criteria.md` 6절 표. 시나리오는 이미 바뀌어 있음 |
| 01-backend-layout 10.2 | 성숙도 리뷰 가이드 | 넣지 않음 — design-docs 몫 |
| 01-backend-layout 10.3 | 최상위 폴더는 큼, 테스트 환경은 leaf 안, 참조 0 파일 세기, 지도, 가드 | `README.md` 2절, `new-feature.md` 6절, `review-criteria.md` 관점 9, 루트 지도 줄, 가드는 이미 `check-repo-layout.py` |
| 01-backend-layout 12절 | 인프라 repo, 최상위 크기, 개발 환경 뜻, 비소스 파일 판정, 파생 서비스 받는 법, design-docs README | 이미 결정(`docs/ci-cd/boundary.md`), `README.md` 2절, `reference/terms.md`, 관점 9, 이미 `operate.md` 4.4절(두 방식), design-docs 몫 |
| 02-docs 9.1 | 언어·원문·용어·문체·기록 | 이미 `docs/README.md` + `reference/terms.md`(새) + `style` 검사 |
| 02-docs 9.2 | 문서-코드 일치 1~5 | 이미 `improve.md` 4.2절 6·`docs/README.md`·`number` 검사, 관점 9 표본 대조, Important 예시 |
| 02-docs 9.3 | K1~K6 | 이미 `check-docs.py`(d1) |
| 02-docs 9.4 | README 필수 절 | 루트는 이미 `readme` 검사. 모듈 README 다섯 칸은 `docs/README.md` 「모듈 README」(새) + 체크리스트 |
| 02-docs 9.5 | 설계 문서 상태 | 이미 `research-design.md` 4절 7, `docs/README.md` |
| 02-docs 9.6 | 관점 4·9·20·23·26 | `review-criteria.md` 6절 표 |
| 03-ci 8.1 | workflow·스크립트 더하는 기준 8개 | `gates.md` 7절(새) |
| 03-ci 8.2 | 빌드·CI 비례성 | `review-criteria.md` 관점 4·20·21 |
| 03-ci 8.3 | 같은 장치 결함 되풀이 | `improve.md` 7절, `delegate.md` 4.2절, `gates.md` 7절 9 |
| 03-ci 8.4 | runner 사실 | `operate.md` 4.1절(capacity 1, label, 12코어·31GB, 잠금 밖) |
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` 한 줄이다.
루트에 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행.
지금은 지켜야 할 규칙이 모두 문서에만 있다. 포맷·레이어 위반·문서 검사
실패는 desktop 게이트에서야 보이고, 이미 적용된 migration을 고쳐도
desktop의 AppliedMigrationImmutabilityTest가 돌 때까지 아무도 모른다.
소유자가 2026-11-07에 편집 훅이 그 파일 하나만 Gradle 없이 포맷·린트하고,
전체 검사는 턴 끝 넛지로, 되돌릴 수 없는 것만 막기로 정했다
(design-docs harness/01-harness-design.md 5절, 13절 Q6·Q7).
scripts/hooks/hooks.py 하나에 이벤트 넷(표준 라이브러리만):
- pre-edit H13: 편집 대상이 applied-migrations.sha256에 있는 migration이면
종료 코드 2로 막고 새 버전 파일을 더하라고 안내한다.
- post-edit 포맷: src/**/*.java 한 파일을 google-java-format으로 맞춘다.
버전은 카탈로그 googleJavaFormat, jar는 Gradle 캐시에 이미 있는 것만
쓰고(받거나 설치하지 않음), 옵션은 Spotless 단계와 같게
--skip-reflowing-long-strings --replace. 이 옵션으로 Spotless 대상
파일 전부를 dry-run 하면 차이가 0이었다(차이는 Spotless를 쓰지 않는
build-logic뿐이라 훅도 제외한다). 파일이 바뀌면 다시 읽으라고 알린다.
- post-edit N1: registry로 leaf를 찾고 import를 순수성 목록
(DomainPurityArchitectureTest, verifyApplicationCoreDependencyPurity와
같은 패키지)과 allowed_dependencies 전이 closure에 대 본다.
- post-edit N2: 문서 편집 뒤 check-work-docs·check-docs의 실패 줄.
- post-bash·stop N5: Java를 고친 뒤 ssh desktop gradlew 실행이 없으면
턴 끝을 한 번 막고 desktop 검증이나 못 돌린 이유를 쓰라고 한다.
- 권한: 실제 .env·.env.local·.env.lane 읽기·쓰기 deny(예시 파일은 둠).
버린 대안: 편집 훅에서 검사 안 하기(설계 권함, 소유자가 자료 쪽으로
정함), 편집마다 desktop 원격 실행(왕복 비용), checkstyle 한 파일
(Gradle 없이 classpath를 맞출 수 없다. 린트는 N1이 맡는다).
위험: 이 세션에서 settings.json을 바꿔도 훅은 돌지 않았다. 훅은 세션이
시작할 때 읽힌다. 그래서 settings.json이 부르는 명령에 같은 입력을 넣어
확인했다. N1은 게이트의 일부만 본다. 정본은 architectureCheck다.
검증: python3 -m unittest discover -s scripts/tests rc=0(훅 시험 29,
그중 실제 포매터 시험은 이 노트북 캐시의 1.35.0 jar로 돌았다). 변이
시험: 조건 10개를 하나씩 끈 사본마다 시험이 1~2건 실패했다. 실제
운영 소스 3,230개에 N1을 돌려 걸림 0. 편집 한 번 훅 시간 Java 0.3초,
문서 1.2초. check-docs·check-work-docs·check-repo-layout rc=0.
BREAKING CHANGE: 파생 서비스에도 같은 훅과 .env deny가 걸린다.
docs/upgrade/2026-11-harness.md 2절 4행.
Agent 도구를 프로젝트 설정으로 막아 두어서, 넓은 검색·구조 리뷰·앱을
띄워 보는 확인처럼 결과만 받으면 되는 일도 메인 세션 컨텍스트에 쌓이거나
하위 세션을 따로 띄워야 했다. 소유자가 2026-11-07에 금지를 풀고, 결과만
받는 일은 서브에이전트, 파일을 바꾸고 소유자가 열어 보고 멈출 수 있어야
하는 위임은 하위 세션으로 나누기로 정했다(design-docs
harness/01-harness-design.md 8절, 13절 Q5).
- .claude/settings.json에서 "Agent" deny를 지웠다(.env deny는 남긴다).
- .claude/agents/: arch-reviewer(HARD-STOP 1~5·registry를 읽기만 하고
판정), verify-api(desktop에서 공유 잠금 아래 bootstrap-local.sh로 앱을
띄워 health와 지정 endpoint를 호출), code-simplifier(동작을 바꾸지
않는 단순화 제안). 셋 다 Edit·Write 도구가 없다.
- 나누는 기준을 AGENTS.md 「일하는 방식」과 docs/work/delegate.md
4.3절에 썼다. 스킬이 서브에이전트에게 구현을 맡기라고 하면 그 단계는
직접 하거나 하위 세션에 맡긴다.
- scripts/tests/test_claude_setup.py: deny가 없고, 정의마다 이름·발동
조건·도구 목록이 있고, 쓰기 도구가 없고, verify-api가 desktop 절차를
따르는지 본다.
버린 대안: 금지 유지(설계 권함, 소유자가 자료 쪽으로 정함), Explore만
허용하는 훅(맨 deny를 빼면 allow로 예외를 못 판다).
위험: 서브에이전트가 Bash로 파일을 바꾸는 것은 도구 목록으로 막지
못한다(arch-reviewer, verify-api). 정의 본문이 읽기 명령만 쓰라고 하고,
노트북 Gradle·Docker는 소유자 전역 훅이 서브에이전트 안에서도 막는다.
데스크톱 앱에서 서브에이전트 기록이 소유자에게 어떻게 보이는지는 확인하지
못했다.
검증: python3 -m unittest discover -s scripts/tests rc=0. arch-reviewer에
Edit를 더한 사본, Agent deny를 되살린 사본에서 각각 시험 1건이 실패했다.
check-work-docs·check-docs rc=0.
BREAKING CHANGE: 파생 서비스에서도 Agent 도구가 열린다. 막으려면 서비스
설정에 deny를 남긴다. docs/upgrade/2026-11-harness.md 2절 5행.
새 기능을 만드는 순서와 desktop에서 게이트를 돌리는 순서는 그 일을
할 때만 필요하다. 지금은 루트 문서와 playbook을 세션이 스스로 찾아 읽어야
하고, cold-read 시험에서 desktop 절차 질문이 되풀이됐다. 소유자가
2026-11-07에 특정 시점 절차는 스킬로, 새 스킬은 모델이 부를 수 있게 하고
설명에 발동 조건을 문단으로 적기로 정했다(design-docs
harness/01-harness-design.md 5.5절, 13절 Q9·Q18).
- .claude/skills/new-feature: docs/work/new-feature.md와 docs/manual/의
실행 순서표(크기 → 받을 것 → 배치 → new-feature.sh --no-format → 안쪽부터
→ 테스트 먼저 → 훅 알림 → desktop 검증 → 체크리스트).
- .claude/skills/desktop-gates: operate.md 4.1·4.2와 gates.md의 실행
순서표(게이트 고르기 → 트리 정하기·패치 → worktree → flock·로그·rc →
테스트 수 → 잠금 대기 → 정리 → 보고 칸).
- 두 스킬 모두 정본 문서를 가리키고 다르면 정본이 맞다고 적는다. 설명은
327자·268자로 목록 상한(1,536자) 안이다.
- 설치된 스킬이 없던 skills-lock.json과 그 레이아웃 허용 항목을 지웠다.
- test_claude_setup.py에 스킬 시험(목록, 모델 호출, 발동 조건, 정본
가리키기, skills-lock.json 없음)을 더했다.
버린 대안: 사용자 호출 전용 스킬(설계 권함, 소유자가 모델 호출로 정함),
verify 스킬(내장 /verify와 이름이 겹친다. 검증 진입점 스크립트는 CI 재편
몫이라 여기서는 만들지 않는다).
위험: 스킬 목록이 컨텍스트 예산(창의 1%)에 닿아 있어, 두 설명이 다른
스킬 설명을 밀어낼 수 있다. 전역 스킬 정리는 소유자 전역 설정 세션 몫이다.
검증: unittest, check-docs(검사가 아직 없는 verify.sh 경로를 잡아
고쳤다), check-work-docs, check-repo-layout 모두 rc=0.
BREAKING CHANGE: 루트 skills-lock.json이 없어진다. docs/upgrade/
2026-11-harness.md 2절 6행.
작업 시간을 예측해도 실제와 비교해 기록하는 곳이 없어서, 틀린 예측에서
하네스를 고칠 단서를 얻지 못한다. 소유자가 2026-11-07에 자료의 방식대로
repo마다 docs/ledger/estimates.jsonl을 두기로 정했다(design-docs
harness/01-harness-design.md 10절, 13절 Q11).
- docs/ledger/README.md: 줄 셋(estimate·actual·retro)과 칸, p30·p50·p80의
뜻, 시간 기준은 작업 중 시간이라는 것, 더하기만 한다는 것.
- 첫 줄은 이 작업의 착수 예측이다(21:46, 공유 노트 착수 보고와 같은 값).
실측 줄은 끝 보고 직전에 더한다.
- 여러 브랜치가 파일 끝에 줄을 더해도 병합이 멈추지 않게 .gitattributes에
merge=union을 줬다(설계가 걱정한 병합 충돌).
- docs/work/README.md 6절(보고)과 delegate.md 4.1절에 착수 보고와 장부를
더했고, docs/README.md 지도에 ledger/ 행을 더했다.
- scripts/tests/test_ledger.py: 줄마다 공통 칸, 예측의 p30 ≤ p50 ≤ p80과
근거, 실측이 앞선 예측을 가지며 들어간 구간이 맞는지 본다.
버린 대안: design-docs 위임 장부를 schema 2로 넓히기(설계 권함, 소유자가
repo 장부로 정함). 위임 장부는 대조용으로 그대로 두고 task로 이 줄을 가리킨다.
위험: Gitea 서버 쪽 병합이 .gitattributes의 merge=union을 쓰는지는 확인하지
못했다. 충돌이 나면 두 쪽 줄을 다 남기면 된다.
검증: unittest, check-docs(지도 검사 포함), check-work-docs,
check-repo-layout rc=0. git check-attr로 merge: union을 확인했다.
문체 규칙(「~한다」, 「~합니다」와 섞지 않음)은 docs/README.md에 있지만
지키는 검사가 없어서, 번역 뒤에도 runbook 열 개에 높임 문장이 남았다.
그리고 결정 기록 머리 블록의 둘째 줄은 「본문은 결정한 때의 원문이다」인데,
2026-11-07에 본문을 한국어로 옮긴 ADR에는 맞지 않는다.
- check-docs.py `style`: 살아 있는 문서의 문장 끝이 높임(습니다·합니다·
입니다·됩니다·십시오·하세요·주세요)이면 실패. 코드 블록, 인라인 코드,
따옴표·낫표 안 인용, 「이력」 인용 블록은 보지 않는다.
- runbook 열 개의 「이 runbook은 다음 alert에서 발동됩니다.」를 「다음 alert가
울리면 쓴다.」로 고쳤다. 지금 걸리는 곳은 이것뿐이었다.
- 결정 기록 표시 줄을 「본문은 결정한 때의 내용이다(번역은 뜻을 바꾸지
않았다)」로 바꿨다: check-docs.py의 DECISION_LABEL, docs/README.md 설명,
docs/adr의 머리 블록 33개(기록은 머리 블록만 고친다는 규칙 안).
- docs/README.md 「문서 검사」에 앞 커밋이 더한 `link`와 이번 `style`을 적고,
링크 검사 설명을 바로잡았다. 「모듈 README」 절(design-docs
docs-system.md 6.2절 다섯 칸)을 더했다.
버린 대안: 문체를 리뷰로만 보기(번역 묶음 네 개를 거쳐도 남았다).
위험: design-docs docs-system.md 4.1절과 프론트의 같은 문구는 이 repo
밖이라 고치지 않았다(총괄에게 알린다).
검증: python3 -m unittest discover -s scripts/tests(문체 시험 5 포함),
check-docs.py, check-work-docs.py 모두 rc=0. 이 커밋의 트리만 얹은 임시
worktree에서 돌렸다. 검사 조건을 끈 사본 둘에서 문체 시험이 각각 2건,
1건 실패했다.
cold-read 3회차(수정 세션 넷의 빈틈 9건), 통합·배치·문서 체계·번역 세션이
「매뉴얼에서 답을 못 찾았다」고 적은 곳, 프론트 총괄 교훈 둘, design-docs
repo-structure 01·02·03의 「매뉴얼에 넣을 규칙」 중 백엔드 몫이 아직 매뉴얼에
없다. 세션마다 같은 판단을 스스로 다시 했다.
넣은 자리(항목별 표는 PR 본문):
- delegate.md: upgrade 안내 「커밋:」 줄은 총괄이 합칠 때 적는다, 두 라운드
연속 결함이면 조사로, 병합 커밋에는 충돌 해결만, 자주 하는 실수 둘(충돌
없음은 merge-tree로, PR 만들기 전 head 브랜치의 PR을 API로).
- improve.md: 절차 문서 결함과 대기 결함의 RED 모양, 테스트 Javadoc도 고친다,
그 코드를 지키는 lane 찾기, 두 라운드 연속 결함이면 조사로.
- docs-writing.md: 문체·용어·언어 범위(코드 주석 제외), check-docs도 돌린다,
이동 커밋에 참조 수정을 같이, 번역 기준(영어 절 제목, 레지스트리 yaml,
머리말 없는 runbook, MANIFEST는 납품 당시 해시).
- operate.md 4.1: zsh 파이프 rc와 자기 실행 멈추기, runner 사실(capacity 1,
12코어·31GB, 잠금 밖), 취약점 DB는 설치가 아니다, 형식은 나누기 전에.
- reference/gates.md: 커밋하는 수정의 lockfile, 처음 켜진 lane의 이전 실패,
lychee·buf·trivy 공식 이미지, smoke 이미지가 이 트리에서 만들어졌음,
원래 있던 실패 가리기(세 번), 순서 의존 재현, 공유 잠금 기다리기, 증거
실행의 --no-build-cache, 거짓 통과 두 줄(OOM 재시작, 조건 안 set -e),
새 7절 「workflow·검사 스크립트를 더할 때」.
- reference/review-criteria.md: 관점 2·4·9·18·20·21·23·26·27의 볼 곳과 결함,
Important 예시, leaf 변경 체크리스트(README 다섯 칸, 문서 검사).
- reference/decisions.md: brief와 결정 원문이 다르면 원문, 취약점 DB 기본값.
- reference/terms.md(새): 영어 그대로 쓰는 말과 「개발 환경」의 뜻.
- README.md 2절(최상위 폴더는 큼), new-feature.md(테스트 환경·release/는
leaf 안), docs/ci-cd/template-vs-consumer.md(docs-check·link-check·
check-repo-layout은 파생 서비스도 유지), settings-and-runtime 규칙.
버린 대안: 항목마다 따로 커밋(소유자 결정: 매뉴얼 보강은 한 묶음).
위험: 정한 기본값 둘은 소유자 확인 대상이다: 취약점 DB 받기 허용,
병합 커밋에 충돌 해결만. operate.md는 143/150줄, improve.md 144/150줄로
상한에 가깝다.
검증: check-work-docs(진입 경로 최대 269/350), check-docs, unittest 모두 rc=0.
폴더 지역 규칙은 이제 src/**/AGENTS.md이고 옆의 CLAUDE.md는 `@AGENTS.md`
한 줄이다. 누가 CLAUDE.md에 규칙을 다시 쓰거나, AGENTS.md만 만들고
CLAUDE.md를 빠뜨리면 Claude Code가 그 폴더 규칙을 못 읽거나 규칙이 두 벌이
된다. 그리고 check-work-docs.py에는 자기 시험이 하나도 없었다.
- check-work-docs.py: src/**/AGENTS.md마다 옆 CLAUDE.md가 있고, 모든
src/**/CLAUDE.md가 정확히 `@AGENTS.md`이며 옆에 AGENTS.md가 있는지 본다
(build 출력 제외).
- scripts/tests/test_check_work_docs.py(13건): 최소 매뉴얼 통과, 지도 41줄·
CLAUDE.md 11줄 실패, CLAUDE.md 첫 줄이 가져오기가 아니면 실패, 진입 경로가
네 파일(AGENTS.md + CLAUDE.md + README + playbook) 합인지, 짝 셋, 하위
규칙과 .claude/rules·skills·agents의 이력 ID, 로컬 .claude 상태는 안 봄,
하위 규칙의 깨진 링크.
- gates.md 「링크 검사」: lychee 범위 밖 지침 문서는 check-docs.py `link`가
보고, 손으로 돌리는 범위를 src/**/AGENTS.md로 바꿨다. docs/README.md의
검사 설명에서 링크 문법 예를 뺐다(링크 검사기가 링크로 읽었다).
위험: 진입 경로 상한 350은 파일별 상한의 합(40+10+80+150=280)보다 커서
지금 구조에서는 닿지 않는다. 옛 상한(120+80+150=350)도 같았다. 상한은 그대로
두고 시험은 상한을 낮춰 계산식을 본다.
검증: unittest(전체), check-work-docs, check-docs, 같은 범위 --links 모두
rc=0(깨진 링크 0). 조건 다섯(짝 검사, 지도 상한, 진입 경로의 CLAUDE.md,
첫 줄 가져오기, .claude 문서 이력)을 하나씩 끈 사본마다 시험이 1~3건 실패했다.
leaf 지역 규칙(src/**/AGENTS.md)은 그 폴더 파일을 열 때마다 통째로
읽힌다. Claude Code 공식 권장은 지침 파일마다 200줄 이하인데,
persistence-jpa 357줄, application-core 337줄, graphql 218줄이었다. 총괄이
2026-11-07에 상한 200을 검사에 넣고 셋을 줄이기로 정했다(소유자 결정
「자료대로 해 본다」의 방향).
- 참조 표, 계약 세부, 설계 근거를 절 단위로 그 leaf README 끝 「지역
규칙에서 옮긴 표와 계약」으로 옮겼다(내용 그대로, 제목 한 단계 내림).
지역 규칙의 같은 자리에는 README 절을 가리키는 줄과 그 폴더를 고칠 때
지킬 규칙 몇 줄을 남겼다.
- application-core: 계약 타입, 패키지 소유 표, 정해진 유스케이스 모양,
멱등성(KEYED) → 337줄에서 190줄.
- persistence-jpa: Spring 조립 소유, 플랫폼 lane, vendor 고르기,
TransactionPort 모드표, 영속 실패 번역(SQLState 표), 영속 감사 → 357줄에서
194줄.
- graphql: 구현된 플랫폼 범위 등급 표 → 218줄에서 185줄.
- 템플릿 패키지 목록의 정본이 src/application-core/README.md로 옮겨 가서
TemplatePackageOwnershipDocumentTest가 그 파일을 읽는다. 표를 머리 줄로
찾고 단언은 그대로다. 옛 경로를 읽으면 표가 없어 실패한다(옮긴 뒤
AGENTS.md에 표 머리 줄 없음, README에 둘 다 있음을 확인했다). 그 표를
가리키는 테스트 주석·실패 메시지와 매뉴얼·리뷰 기준·스킬의 참조도 바꿨다.
- persistence-jpa README가 계약 표의 정본을 AGENTS.md라고 적던 줄 넷을 새
자리로 고쳤다. 그중 「세 템플릿 모두 isolation을 READ_COMMITTED로 고정」은
코드(`SpringTransaction`: pool에 고정, template은 기본값)와 달라 코드에
맞췄고, AGENTS.md에 없던 분산 락 provider 선택표 포인터는 실제 설정 코드
`lock/DistributedLockPersistenceConfig`로 바꿨다.
- check-work-docs.py: src/**/AGENTS.md 200줄 상한(시험 둘). RolePermission
PolicyTest 주석의 옛 절 이름을 새 규칙 파일로 바꿨다.
위험: 운영 코드 주석 넷(persistence-jpa failure·transaction)은 "CLAUDE.md의
표"를 가리킨다. 업무 코드라 고치지 않았다. CLAUDE.md → AGENTS.md → README
포인터로 닿는다. persistence-jpa README는 V1이 70~72줄을 고친다. 이 커밋은
그 범위를 건드리지 않는다.
검증: check-work-docs(가장 긴 지역 규칙 194/200), check-docs, unittest rc=0.
상한 검사를 끈 사본과 상한을 400으로 올린 사본에서 시험이 실패했다. Java
변경은 최종 트리에서 desktop documentContractTest·ci로 돌린다.
BREAKING CHANGE: 세 leaf의 표가 README로 옮겨 갔다. docs/upgrade/
2026-11-harness.md 2절 8행.
매뉴얼 보강 묶음이 각 빈틈을 어디에 넣었는지, 넣지 않았으면 왜인지를 다음
cold-read 시험과 총괄 대조가 찾을 곳이 없다. 1·2회차는 evidence.md 9·11절에
처리 표를 두었다. 같은 방식으로 12절을 더한다.
- 22행: 3회차 빈틈 9건(R3-1~R3-8), 장부의 통합·배치·문서·번역 세션 빈틈,
공유 노트 목록, repo-structure 세 문서의 매뉴얼 규칙. 고침 21행(기본값 2),
고치지 않음 1행(design-docs 몫).
- 리뷰 ID와 세션 이름은 이 근거 문서에만 둔다(매뉴얼 본문 이력 ID 0 규칙).
검증: check-work-docs, check-docs rc=0.
착수 예측(21:46, p30 150분·호출 450·출력 45만) 뒤 끝 보고 직전의 실측을
세션 기록에서 뽑아 같은 task로 한 줄 더한다: 벽시계 94분, 작업 중 68분, 호출
270, 출력 34.6만 토큰, 다시 읽은 입력 1.33억 토큰, 최대 컨텍스트 80.5만. 모두
p30 안이다. 틀린 이유와 다음에 바꿀 근거는 줄의 why 칸에 있다.
작업 중 시간의 정의를 선례(design-docs harness 설계 14절)가 잰 방식과 같게
「빈틈을 5분까지만 더한 시간」으로 README에 적었다.
검증: test_ledger(예측보다 뒤의 실측, 구간 판정), check-docs, check-work-docs rc=0.
Blocking a user prevents them from interacting with repositories, such as opening or commenting on pull requests or issues. Learn more about blocking a user.
무엇을, 왜
CLAUDE.md와AGENTS.md가 둘 다 있으면 Claude Code 기본 설정은AGENTS.md를 읽지 않는다. 그래서 344줄 정본은 세션이 스스로 열 때만 닿았고, 두 문서가 같은 규칙을 아홉 군데 따로 적었다. 지켜야 할 규칙은 모두 문서에만 있어서 포맷·레이어 위반·문서 검사 실패가 desktop 게이트에서야 보였다.harness/01-harness-design.md13절)를 정했다. 이 PR이 백엔드에 적용한다: 루트 지침 40줄 정본, 하위 폴더AGENTS.md, 편집 훅, Agent 금지 해제와 서브에이전트, 모델이 부르는 스킬, repo 장부. 쌓인 매뉴얼 빈틈도 한 묶음으로 넣었다(소유자 결정).고른 방법과 버린 대안
AGENTS.md(37줄: 무엇인가·HARD-STOP·지도·맡은 일·검증·일하는 방식) +CLAUDE.md(@AGENTS.md+ Claude 전용 줄). 버림: 루트 120줄(설계 권함, 소유자가 자료 쪽 20~40줄로 정함), 심볼릭 링크(Edit 도구가 링크를 통해 쓰지 않음).src/**/CLAUDE.md28개를 같은 폴더AGENTS.md로 옮기고CLAUDE.md는@AGENTS.md한 줄. 이 세션에서 하위CLAUDE.md의 가져오기가 펼쳐지는 것을 확인했다. family 문서 넷 새로. 폴더를 가로지르는 파일 종류 규칙(테스트·설정·Docker·문서)은.claude/rules/의paths규칙.--skip-reflowing-long-strings)으로 맞춘다. 이 옵션으로 Spotless 대상 파일 전부를 dry-run 하면 차이가 0이었다. 레이어 넛지 N1, 문서 넛지 N2, 턴 끝 desktop 검증 넛지 N5, 적용된 migration 편집 차단 H13,.envdeny. 버림: 편집 훅에서 검사 안 하기(설계 권함, 소유자가 자료 쪽으로), 편집마다 desktop 원격 실행, checkstyle 한 파일(Gradle 없이 classpath를 못 맞춤).arch-reviewer,verify-api,code-simplifier)은 결과만 돌려주고 쓰기 도구가 없다. 파일을 바꾸는 위임은 하위 세션.new-feature,desktop-gates는 정본 playbook을 가리키는 실행 순서표다. 버림: verify 스킬(내장/verify와 이름이 겹치고, 검증 진입점 스크립트는 CI 재편 몫).docs/ledger/estimates.jsonl은 더하기만 하는 JSON Lines이고.gitattributes가merge=union을 준다(여러 브랜치가 끝에 줄을 더해도 병합이 안 멈춤).check-docs.py에link(lychee 범위 밖으로 나간 지침 문서의 상대 링크를 PR에서 계속 보려고)와style(문체),check-work-docs.py에 지도 40줄·CLAUDE.md10줄·첫 줄 가져오기·하위 짝 검사. workflow 파일은 CI 재편 몫이라 고치지 않았다.위험과 영향
.claude/설정, Agent 허용,skills-lock.json삭제가 넘어간다.docs/upgrade/2026-11-harness.md에 행 여덟과 할 일을 적었다. 커밋 여섯에!가 있다(행 여덟).@DisplayName은 고친 메서드만.merge=union을 쓰는지는 확인하지 못했다.src/application-core/README.md가 되어TemplatePackageOwnershipDocumentTest가 그 파일을 읽는다(단언은 그대로).9fbf72fb, PR #4)을248df518로 합쳤다. 충돌은 없었다.검증
desktop worktree, 공유 잠금(
flock /tmp/claude-gates/heavy.lock) 아래, Gradle 명령마다--no-build-cache, 새 detached worktree. 노트북git rev-parse HEAD^{tree}와 desktopgit write-tree가 같은 트리에서 돌렸다. 로그는 desktop~/h3-backend-harness-logs/(명령별<이름>.log, 결과 XML<이름>-xml.tgz, 요약summary.tsv).합친 트리
9898949b(= 커밋248df518, main9fbf72fb+ 이 브랜치), 22:43~23:10, 모두 rc=0, FROM-CACHE 0:ci :verifyDependencyLocks --warning-mode=fail:verifyStrictLaneStages --dry-run,-p platforms/optional-build같은 검사-p platforms/optional-build civerify-compose-profile-contracts.sh,check-repo-layout.py,unittest(147건),check-docs.py,check-work-docs.py:app-bootstrap:documentContractTest --rerun:app-bootstrap:repositoryContractTest --rerunsrc/.env가 있어야 도는 로컬 전용 계약, 이전부터):adapter:outbound:persistence-mongo:test --tests '*MongoNamespaceContractTest' --rerun-p build-logic testrun줄 그대로:ci가 만든 결과라 UP-TO-DATE, 필터 둘은 실행(테스트 30, 2):messaging:messaging-kafka:verifyMessagingCertificationEvidencepr7줄run줄 그대로:ci결과로 UP-TO-DATE,jpaPlatformContractTest432,jpaPlatformMigrationTest45objectStorageMinioContractTestredisTopologyTest→ downrun줄(행렬 값마다)--severity CRITICAL,HIGH --exit-code 1.proto·lockfile·카탈로그 변경 없음최종 트리
c487f30f(= heada0a77575, 위 트리 + 장부 실측 한 줄): 바뀐 것이docs/ledger/뿐이라 그 검사만 다시 돌렸다.unittest147,check-docs.py,check-work-docs.py,check-repo-layout.py,:app-bootstrap:documentContractTest --rerun(68) 모두 rc=0.중단한 실행(증거로 쓰지 않음):
49f27a5f(leaf 정리 전,:ci·verifyStrictLaneStages만 끝남, rc=0),e5dcc93b(main 합치기 전, 앞 12개 rc=0). 트리가 바뀌어 멈췄다. 로그~/h3-backend-harness-logs-run1/,-run2/.훅·검사기 시험(노트북): 훅 29건(실제 포매터 시험은 노트북 Gradle 캐시의 1.35.0 jar로 돎), 변이 10개(조건 하나씩 끔)마다 1~2건 실패. 운영 소스 3,230개에 N1을 돌려 거짓 양성 0.
--skip-reflowing-long-strings포매터 dry-run이 Spotless 대상 파일 전부에서 차이 0.check-work-docs시험 15건, 변이 7개마다 실패.check-docs링크·문체 시험, 변이 셋마다 실패. 하위CLAUDE.md의@AGENTS.md가져오기는 이 세션에서 domain-core 파일을 열어 본문이 읽히는 것을 봤다. 훅 설정은 세션이 시작할 때 읽혀서, settings가 부르는 명령에 같은 입력을 넣어 확인했다.리뷰어가 볼 곳
AGENTS.md(37줄)·CLAUDE.md, 아래 「옮긴 규칙」 표에서 빠진 규칙이 없는지.scripts/hooks/hooks.py: N1의 금지 목록이 ArchUnit·purity 태스크와 같은지, N5가 턴 끝을 막는 조건..claude/agents/*: 쓰기 도구가 없는지,verify-api가 desktop 절차를 지키는지.scripts/check-docs.py의link·style,scripts/check-work-docs.py의 상한·짝 검사.관련
harness/01-harness-design.md13절(소유자 결정 2026-11-07).docs/upgrade/2026-11-harness.md.docs/work/evidence.md12절. 장부:docs/ledger/estimates.jsonl.~/.claude와 하네스 플러그인(H2), 검증 진입점 스크립트와 workflow(CI 재편), design-docs 문구(docs-system.md4.1절의 결정 기록 머리 문구, 6.1·6.2절의CLAUDE.md언급, 위임 장부 3회차 「매뉴얼 수정」 칸).부록: 옮긴 규칙과 매뉴얼 보강
옮긴 규칙 (옛 자리 → 새 자리)
옛 루트
AGENTS.md(344줄)AGENTS.md첫 문단AGENTS.md「HARD-STOP」(한 벌만)AGENTS.md「일하는 방식」, 자세히는docs/work/delegate.md4.3절verifyEnvKeys·verifyStrictLaneStages세는 규칙)src/build-logic/AGENTS.md(새).verifyEnvKeys결정은reference/decisions.md기존 행AGENTS.md「검증」AGENTS.md「일하는 방식」 +docs/work/README.md4절(기존)src/adapter/inbound/AGENTS.md·src/adapter/outbound/AGENTS.md·src/composition/AGENTS.md(새), core leafAGENTS.md(기존 책임·금지)AGENTS.md「지도」docs/work/new-feature.md(기존 절차) + 스킬new-feature. 설계서·계획서 머리 블록은research-design.md(기존)AGENTS.md「테스트」(domain-core, application-core, app-bootstrap, adapter family 둘).claude/rules/java-tests.md(테스트 소스를 열 때 읽힘). 번호 그대로라 코드 주석의 "AGENTS.md test rule 6"은 루트 지도의 위치 줄로 닿는다reference/gates.md1절(기존 표) + 루트 「검증」 + 스킬desktop-gatesdocs/manual/10-capabilities.md(이제 정본) + 루트 지도 한 줄.claude/rules/settings-and-runtime.md(설정·Dockerfile·compose 경로) +.env권한 denyREADME.md「새 서비스로 시작하기」(빠졌던 넷: proto 조직 이름, 이미지·앱 이름, env 예시, 문서)6은 지움(HARD-STOP 14와 같은 말). 범위 밖 리팩터링·사용자 변경 되돌리기·파괴적 git은 루트 「일하는 방식」docs/work/README.md6절, 전역 규칙)옛 루트
CLAUDE.md(75줄)AGENTS.md첫 문단·지도AGENTS.md(중복 제거)AGENTS.md「맡은 일」CLAUDE.md소유자 환경 줄,operate.md4.1절, 스킬desktop-gates, 훅 N5.claude/rules/docs.mdcheck-repo-layout.pysrc/platforms/messaging/AGENTS.md·src/platforms/grpc/AGENTS.md(기존)src/composition/AGENTS.md(새)new-feature.md(기존) + 스킬new-featuresrc/build-logic/AGENTS.md+.claude/rules/java-tests.md+gates.md5절.claude/rules/java-tests.md·docs.md+src/build-logic/AGENTS.md.claude/rules/docs.mdCLAUDE.md「Claude Code에서만」. Agent 금지는 풀림(delegate.md4.3절)하위
src/**/CLAUDE.md28개: 같은 폴더AGENTS.md로 옮기고CLAUDE.md는@AGENTS.md한 줄. family 문서 넷 새로(src/adapter/inbound,src/adapter/outbound,src/composition,src/build-logic).200줄 넘던 지역 규칙 셋(총괄 결정 2026-11-07) — 옮긴 절은 그 leaf
README.md끝 「지역 규칙에서 옮긴 표와 계약」, 지역 규칙에는 포인터와 지킬 규칙 몇 줄:src/application-core/README.md같은 절TemplatePackageOwnershipDocumentTest가 읽음)src/adapter/outbound/persistence-jpa/README.md같은 절src/adapter/inbound/graphql/README.md같은 절매뉴얼 보강 (항목 → 넣은 자리 또는 넣지 않은 이유)
git merge-tree로delegate.md9절delegate.md9절check-docs.pyDECISION_LABEL,docs/README.md, ADR 33개 머리 블록. design-docsdocs-system.md4.1절과 프론트는 범위 밖(총괄 몫)check-docs.pystyle(새) +docs-writing.md4절 4 + runbook 10개 고침gates.md4절 「smoke 이미지」,operate.md4.1절 +decisions.md기본값,improve.md4.2절 6@DisplayName범위docs-writing.md4절 14,.claude/rules/java-tests.md규칙 2docs-writing.md4절 14AGENTS.md지도 줄 +check-repo-layout.py설명,docs/ci-cd/template-vs-consumer.md세 행reference/decisions.md1절 1gates.md4절 「공유 잠금 기다리기」gates.md2절 탐침pkill -f)operate.md4.1절improve.md4.2절 3operate.md4.1절(나누기 전에 확인, 편집 훅)improve.md4.2절 8delegate.md4.2절 표--no-build-cache차이, zshPIPESTATUS, 처음 켜진 lane의 이전 실패gates.md6절 표, 4절 「원래 있던 실패 가리기」, 3절,operate.md4.1절,gates.md3절 (나) 573d39212, 2회차3eb3b067, 처리 표evidence.md9·11절). 운영 캐시 교훈은operate.md9절에 있음if안set -e, leaf 데이터 폴더, 트리 해시로 묶기, 코드 주석 언어gates.md4절,gates.md6절,new-feature.md6절(release/), 넣지 않음 — 이미operate.md4.1절 「push 전에 검증하기」,docs-writing.md4절 4review-criteria.md6절 표, 넣지 않음 — 이미docs/manual/04(83줄)·05(45줄)이 예가 없음을 밝히고 시험을 가리킨다docs-writing.md4절 13,gates.md7절 1·8, 넣지 않음 — 이미docs/README.md「문서 검사」(FROZEN),docs-writing.md4절 14,gates.md7절 8delegate.md4.2절, 넣지 않음 — 이미docs/README.md,gates.md4절 둘,docs-writing.md·review-criteria.md9절,gates.md3절 (다)delegation-loop.md몫(백엔드 아님)review-criteria.md6절 표. 시나리오는 이미 바뀌어 있음README.md2절,new-feature.md6절,review-criteria.md관점 9, 루트 지도 줄, 가드는 이미check-repo-layout.pydocs/ci-cd/boundary.md),README.md2절,reference/terms.md, 관점 9, 이미operate.md4.4절(두 방식), design-docs 몫docs/README.md+reference/terms.md(새) +style검사improve.md4.2절 6·docs/README.md·number검사, 관점 9 표본 대조, Important 예시check-docs.py(d1)readme검사. 모듈 README 다섯 칸은docs/README.md「모듈 README」(새) + 체크리스트research-design.md4절 7,docs/README.mdreview-criteria.md6절 표gates.md7절(새)review-criteria.md관점 4·20·21improve.md7절,delegate.md4.2절,gates.md7절 9operate.md4.1절(capacity 1, label, 12코어·31GB, 잠금 밖)leaf 지역 규칙(src/**/AGENTS.md)은 그 폴더 파일을 열 때마다 통째로 읽힌다. Claude Code 공식 권장은 지침 파일마다 200줄 이하인데, persistence-jpa 357줄, application-core 337줄, graphql 218줄이었다. 총괄이 2026-11-07에 상한 200을 검사에 넣고 셋을 줄이기로 정했다(소유자 결정 「자료대로 해 본다」의 방향). - 참조 표, 계약 세부, 설계 근거를 절 단위로 그 leaf README 끝 「지역 규칙에서 옮긴 표와 계약」으로 옮겼다(내용 그대로, 제목 한 단계 내림). 지역 규칙의 같은 자리에는 README 절을 가리키는 줄과 그 폴더를 고칠 때 지킬 규칙 몇 줄을 남겼다. - application-core: 계약 타입, 패키지 소유 표, 정해진 유스케이스 모양, 멱등성(KEYED) → 337줄에서 190줄. - persistence-jpa: Spring 조립 소유, 플랫폼 lane, vendor 고르기, TransactionPort 모드표, 영속 실패 번역(SQLState 표), 영속 감사 → 357줄에서 194줄. - graphql: 구현된 플랫폼 범위 등급 표 → 218줄에서 185줄. - 템플릿 패키지 목록의 정본이 src/application-core/README.md로 옮겨 가서 TemplatePackageOwnershipDocumentTest가 그 파일을 읽는다. 표를 머리 줄로 찾고 단언은 그대로다. 옛 경로를 읽으면 표가 없어 실패한다(옮긴 뒤 AGENTS.md에 표 머리 줄 없음, README에 둘 다 있음을 확인했다). 그 표를 가리키는 테스트 주석·실패 메시지와 매뉴얼·리뷰 기준·스킬의 참조도 바꿨다. - persistence-jpa README가 계약 표의 정본을 AGENTS.md라고 적던 줄 넷을 새 자리로 고쳤다. 그중 「세 템플릿 모두 isolation을 READ_COMMITTED로 고정」은 코드(`SpringTransaction`: pool에 고정, template은 기본값)와 달라 코드에 맞췄고, AGENTS.md에 없던 분산 락 provider 선택표 포인터는 실제 설정 코드 `lock/DistributedLockPersistenceConfig`로 바꿨다. - check-work-docs.py: src/**/AGENTS.md 200줄 상한(시험 둘). RolePermission PolicyTest 주석의 옛 절 이름을 새 규칙 파일로 바꿨다. 위험: 운영 코드 주석 넷(persistence-jpa failure·transaction)은 "CLAUDE.md의 표"를 가리킨다. 업무 코드라 고치지 않았다. CLAUDE.md → AGENTS.md → README 포인터로 닿는다. persistence-jpa README는 V1이 70~72줄을 고친다. 이 커밋은 그 범위를 건드리지 않는다. 검증: check-work-docs(가장 긴 지역 규칙 194/200), check-docs, unittest rc=0. 상한 검사를 끈 사본과 상한을 400으로 올린 사본에서 시험이 실패했다. Java 변경은 최종 트리에서 desktop documentContractTest·ci로 돌린다. BREAKING CHANGE: 세 leaf의 표가 README로 옮겨 갔다. docs/upgrade/ 2026-11-harness.md 2절 8행.