Commit Graph
8 Commits
Author SHA1 Message Date
DongHyeonka 6a792b8144 refactor(layout)!: 옮긴 경로를 부르는 곳을 모두 새 배치에 맞춘다
문제: 앞 커밋이 Gradle 루트를 저장소 루트로 옮기고 계층 폴더를 묶었다.
빌드 스크립트·build-logic·시험·workflow·스크립트·문서가 아직 옛 배치
(Gradle 루트 = src/)를 가정해 빌드가 되지 않는다.

고른 방법:
- Gradle 경로와 registry id는 그대로 둔다(:app-bootstrap, :application-core,
  :composition:*). registry의 source_path만 새 폴더를 가리킨다. 폴더에 맞춘
  이름(:domain:core, :application:core)은 프로젝트 이름 core가 둘이 되어
  boot jar의 BOOT-INF/lib와 기본 capability가 겹치고, 파생 서비스의 모든
  project(':…') 줄을 바꾸게 한다.
- registry는 gradle/modules.json, 시험 이미지 목록은
  gradle/container-images.properties: 버전 카탈로그 옆, 빌드가 고정하는 것.
  config/는 코드 검사 도구 설정만 둔다.
- build-logic: settings·architecture 플러그인의 저장소 루트를 Gradle 루트로
  (getParentFile 제거). config contract의 파일 트리는 src/만 훑는다(루트를
  훑으면 docs·.claude/worktrees까지 줍는다).
- 빌드 스크립트: rootProject.projectDir.parentFile → rootProject.projectDir,
  rootProject.file('../…') → rootProject.file('…'), 옛 src 기준 include에
  src/를 붙인다. notification API surface의 application-notification 소스
  루트를 새 폴더로(놓치면 272개 타입이 surface에서 말없이 빠진다).
- 시험: 옛 src 기준 모듈 목록과 ../ 개수를 고친다. 없는 폴더를 말없이
  건너뛰던 목록(MessagingAuthority, NotificationPayloadAtRest 등)을 새
  폴더로, FileserverDocumentationCoverageTest는 Gradle 경로 → 폴더를
  registry로 찾는다. Docker 계약은 WORKDIR /build, 새 jar 경로.
- Docker: 빌드 context를 저장소 루트로, .dockerignore는 허용 목록으로 다시
  써서 전에 context였던 것만 들어가게 한다. compose의 build.context는 .,
  env_file은 ./.env.
- workflow: working-directory: src 기본값과 그것을 되돌리던 줄을 지운다.
- scripts: verify.sh, ci/*, bootstrap-local, new-feature,
  verify-feature-scaffold, mongo 검증, hooks, check-repo-layout 허용 목록.
  check-docs의 경로 검사는 build-logic/·gradle/로 시작하는 경로도 본다.
- 문서: AGENTS.md 지도, README 구조 표, leaf AGENTS.md의 cd src, gates·
  operate·결정 색인, src/bootstrap/AGENTS.md를 조립 계층 family 규칙으로
  다시 쓴다. 기록 문서(docs/design·history·reviews, 지난 upgrade 안내,
  capability-status 제거 표)는 머리 블록만 고친다. 파생 서비스용 안내
  docs/upgrade/2026-11-relayout.md를 더한다.

위험: bootRun working dir가 저장소 루트가 되어 .env와 상대 경로 설정이
루트 기준이다. 루트 .env는 compose 보간에도 읽힌다(upgrade 안내 5절).
파생 서비스는 태그 pre-relayout-2026-11까지 받은 뒤 이 묶음을 받는다.

검증: desktop에서 캐시 없이 scripts/verify.sh docs·pr·main·release,
compose smoke 18 lane, 빠른 시작(scripts/verify.sh app). 결과는 PR 본문.
구조 리뷰(arch-reviewer) 지적 5건을 반영했다.

BREAKING CHANGE: Gradle은 저장소 루트에서 돈다(cd src 없음). registry는
gradle/modules.json, 이미지 빌드 context는 저장소 루트다. 옛 경로 → 새 경로
표는 docs/upgrade/2026-11-relayout.md.
Refs: design-docs repo-structure/01-backend-layout.md 6.1절 가-2·가-3
2026-11-11 22:15:42 +09:00
DongHyeonka 7140f27948 docs(agents)!: 200줄 넘는 leaf 지역 규칙 셋의 표와 근거를 README로 옮긴다
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행.
2026-11-07 22:33:08 +09:00
DongHyeonka c8db79a78f docs(work): 쌓인 매뉴얼 빈틈과 조사 문서의 매뉴얼 규칙을 한 묶음으로 넣는다
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.
2026-11-07 22:21:04 +09:00
DongHyeonka 67ecae2cc2 feat(skills)!: 새 기능과 desktop 게이트 절차를 모델이 부르는 스킬로 둔다
새 기능을 만드는 순서와 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 22:10:08 +09:00
DongHyeonka 3c73fc333c 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행.
2026-11-07 21:59:42 +09:00
DongHyeonka 08f932123a docs(agents)!: leaf 지역 규칙 문서를 같은 폴더 AGENTS.md로 옮긴다
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` 한 줄이다.
2026-11-07 21:58:12 +09:00
DongHyeonka ab5982e955 refactor(repo)!: 샘플 모듈과 그 참조를 지운다
문제: src/sample-portfolio(311파일)와 src/Dockerfile.sample이 빌드 8곳,
registry, PR job, spotbugs 제외, 매뉴얼·leaf 문서 수십 곳에 얽혀 있다.
매뉴얼과 생성 명령이 예시를 맡게 된 뒤로 샘플은 유지 비용만 남았고,
문서 일부는 이미 없는 태스크(sampleOffTest)와 ArchUnit 규칙을 가리킨다.

고른 방법: 소유자 결정(2026-11-07)대로 샘플을 폴더째 지우고 역할은
옮기지 않는다. 샘플을 가리키던 것도 같은 변경에서 지운다.
- 빌드: registry 행, 루트 build.gradle의 샘플 태스크·의존·단계
  (sampleWebContractCheck, :sample-portfolio:*, strict lane 단계),
  app-bootstrap architectureTestRuntimeOnly, spotbugs 제외 3곳
- CI: ci-quality-gates.yml의 sample-portfolio job과 release-gate 칸
- 테스트: SampleRuntimeDefaultsContractTest, Dockerfile.sample 비교 테스트,
  ArchUnit 규칙의 죽은 sample 패키지 제외. build-logic 테스트와
  application-core 테스트의 가짜 이름은 example-app으로 바꾼다
- 문서: 매뉴얼 예시를 실제 코드(durable operation, identifier,
  ErrorCodeRegistryMappingTest)로 바꾸고, 템플릿에 예가 없는 기법
  (유일 제약 → 같은 409)은 규칙과 확인 방법만 적는다. 결정 색인의
  샘플 전용 행은 "샘플과 함께 사라짐"으로 표시한다
버린 대안: 설계서 권장안(OpenAPI 스냅숏·웹 계약을 옮긴 뒤 삭제)은
소유자가 고르지 않았다.

위험·한계:
- 샘플 안에만 있던 검사(OpenAPI 스냅숏, Date 헤더, 가상 스레드 MDC
  전파, 요청당 SQL 수 단언)가 함께 사라진다. 소유자가 남기라 하면
  총괄이 따로 맡긴다.
- APP_CACHE_REDIS_ENABLED는 샘플이 읽지 않는 키라(설계서 가정과 다름)
  지우지 않고 src/README.md 문장만 고쳤다. 제거 기한 2026-11-30은 그대로.
- docs/capability-status.md 「제거된 코드」 표와 docs/work/evidence.md의
  샘플 경로는 이력이라 두었다.

검증(desktop, 트리 0525e14e, ~/t1-layout-logs/):
- ./gradlew :ci --warning-mode=fail rc=0 (502 executed, 83 from cache)
- :verifyStrictLaneStages --dry-run rc=0
- :app-bootstrap:documentContractTest rc=0
- -p build-logic check rc=0
- :verifyDependencyLocks rc=0
- python3 scripts/check-work-docs.py, 상대 링크 검사 rc=0

Refs: design-docs repo-structure/README.md 3.1, repo-structure/01-backend-layout.md 6.2
BREAKING CHANGE: src/sample-portfolio, src/Dockerfile.sample, 샘플 태스크와 job이 없어진다. 샘플을 고쳐 쓰던 파생 서비스는 병합 때 수정 대 삭제 충돌이 난다. docs/upgrade/2026-11-maturity-review.md B-49.
2026-11-07 12:21:03 +09:00
DongHyeonka 63c63413d1 docs(work): 지도와 작업 종류별 playbook으로 작업 매뉴얼을 만든다
문제: 이 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에서 돌린다
2026-11-06 19:58:44 +09:00