a638698fc84e316bb17e64a9cbae66176ed1ccfa
14
Commits
| Author | SHA1 | Message | Date | |
|---|---|---|---|---|
|
|
c611b06f03 |
feat(claude): 분야 전문가를 지식 스킬 열 개와 렌즈 리뷰어로 두고 협업 명단을 붙인다
문제: 하네스에 분야 지식이 없다. 영속성·메시징·보안·관측·성능·API 계약· 빌드·시험·문서·도메인의 이 repo 규칙(적용된 마이그레이션 금지, 잠금 상한, 동시 인덱스 빌드, env 키 레지스트리 등)은 문서에 흩어져 있어, 세션이 그 문서를 찾아 읽어야만 지킨다. 여러 분야에 걸친 일을 누가 보고 어떻게 합치는지도 정한 곳이 없다. 고른 방법(소유자 결정 2026-11-11 「W3 설계대로」): - 지식 스킬 be-* 10개(.claude/skills/). 각자 paths를 걸어 그 분야 파일을 만질 때만 목록에 뜬다. 본문은 언제 쓰나 → 함정 → 실패는 이렇게 보인다 → 검증 → 이 repo에서 정한 것 순서이고, 정본 문서를 가리킨다. 초안은 이 repo 문서만 본 서브에이전트가 썼고, 경로는 relayout 배치에 맞췄다. - 서브에이전트 reviewer(렌즈 = brief의 스킬 경로). arch-reviewer는 be-domain을 미리 싣고 lead 공통 양식으로 돌려준다. - .claude/rules/expert-skills.md: 분야 파일을 고치기 전에 그 스킬의 「함정」·「검증」을 보게 하는 두 줄(평가에서 스킬 호출이 5번 중 2번이었다). - docs/work/experts.md: 명단·경로 → 렌즈·넘김 지도·충돌·비용. 루트 AGENTS.md 한 줄, CLAUDE.md 두 줄 고침(10줄 상한 유지), README 3절 4단계와 delegate.md 4.3절에 가리키는 말. - 시험: 에이전트 넷, Agent 도구 금지, 설명 합 1,200자, 지식 스킬의 paths· 설명 300자·금지어·절 순서·150줄, 모든 paths glob이 추적 파일에 걸림, 명단이 모든 전문가를 담음. 버린 대안: 분야마다 서브에이전트. Anthropic 2026-10-22·2026-01-23·2026-04-07 글이 반대하고, 설명이 모든 세션에 든다. 위험: 플러그인 lead·new-expert·harness-eval은 claude-harness PR #3(0.3.0)이 병합돼야 받는다. 그전에는 lead를 가리키는 문장이 설명만 남는다. 검증: python3 -m unittest discover -s scripts/tests → 154건 통과. 새 시험 6개는 조건을 깰 때마다 실패했다. scripts/verify.sh docs → rc=0. |
||
|
|
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
|
||
|
|
5e204e6a43 |
refactor(platforms)!: gRPC 플랫폼을 별도 repo grpc-library로 옮기고 지운다
템플릿 repo 안에 프로젝트 계층이 아닌 라이브러리가 있었다. gRPC 플랫폼 (src/platforms/grpc, grpc-advanced)과 그것만을 위한 두 번째 Gradle 빌드 (src/platforms/optional-build)는 템플릿 어느 leaf도 쓰지 않는데, registry 9행, workflow job 넷과 단계 하나, build-logic 플러그인 둘, 카탈로그·SpotBugs 항목, 문서 열두 개를 템플릿이 함께 지고 있었다. 소유자 결정(2026-11-07, design-docs repo-structure/README.md 3.5절, 05-library-repos.md Q1~Q17 승인)대로 라이브러리마다 별도 repo로 옮긴다. gRPC는 템플릿 소비자가 없어 먼저 옮기고, 템플릿은 지우기만 한다(Q13). 코드와 이력은 grpc-library repo에 filter-repo로 옮겼다(옮긴 폴더의 트리 해시가 이 기준 커밋 22df3525와 같다). 지운 것: - src/platforms/grpc, grpc-advanced, optional-build(343파일) - registry의 "build": "optional-grpc" 9행 - ci-quality-gates.yml job optional-platforms·grpc-proto-buf와 그 needs, integration-main.yml optional 성능 단계와 job grpc-optional-platform-integration, release.yml job grpc-stable-release-gate와 이미지 job의 needs 한 줄 - build-logic ca.grpc-platform-module·ca.optional-architecture-registry, MainBuild(두 번째 빌드에서 주 빌드를 찾던 것)와 ArchitecturePlugin의 optional 분기. 도구 설정·이미지 목록·registry는 Gradle 루트에서 찾는다 - 카탈로그 protobufPlugin·protobuf-java-grpc·protoc·plugin protobuf(Q14: 채택 전이라 grpc-library 좌표도 넣지 않는다), SpotBugs 제외의 gRPC 줄 - 옮긴 문서: ADR-GRPC 7개, docs/compatibility/(폴더째), gRPC runbook 둘, gRPC 설계서. 리뷰·기록 본문은 고치지 않았다(Q15). 기록 하나의 머리 블록 「현재 정본」만 새 자리를 말하게 했다 - DeveloperExperienceContractTest의 optional 빌드 lane 계약 시험, adopter API 표면 검사의 optional-build 제외 경로 남긴 것: adapter:inbound:grpc(io.grpc를 직접 쓰고 플랫폼을 쓰지 않는다), src/platforms/messaging(다음 분리 작업), registry의 build 칸 지원 (ModuleRegistry, 일반 기능). 살아 있는 문서: README, docs 지도, capability-status, work/delegate· gates·decisions(새 행 「라이브러리 repo」)·defect-patterns· review-criteria(경계 밖 파일을 경로로 읽는 결합을 결함 후보로), manual 04, jpa migration-guide, build-logic AGENTS·README, testkit 주석. 새 docs/work/reference/related-repos.md가 라이브러리 repo 목록과 같이 고치는 법을 둔다. 파생 서비스 안내는 docs/upgrade 3.8절 B-55·B-56. 위험: 파생 서비스가 이 경로를 고쳤으면 수정 대 삭제 충돌이 난다 (tech-log-backend는 플랫폼을 받은 적이 없다, 설계 12절). 분리 직전 커밋 태그 pre-library-split(설계 12.2절)은 이 브랜치 권한 밖이라 달지 않았다. 검증: desktop 게이트 결과는 PR 본문(ci, mainCheck 계열, releaseCheck, compose smoke, 빠른 시작). 문서 검사 셋 rc=0. BREAKING CHANGE: src/platforms/grpc*·optional-build, :grpc:*·:grpc-advanced:* 프로젝트, ca.grpc-platform-module, 카탈로그 protoc·protobuf-java-grpc·plugin protobuf가 없다. 쓰던 서비스는 grpc-library 좌표 com.hyeonworks.grpc로 받는다(docs/upgrade/2026-11-maturity-review.md 3.8절). Refs: design-docs repo-structure/05-library-repos.md 13.1절 1·2단계 |
||
|
|
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행.
|
||
|
|
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. |
||
|
|
37c88fedd4 |
docs(ledger): 작업마다 예측과 실측을 쌓는 repo 장부를 둔다
작업 시간을 예측해도 실제와 비교해 기록하는 곳이 없어서, 틀린 예측에서 하네스를 고칠 단서를 얻지 못한다. 소유자가 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을 확인했다. |
||
|
|
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행. |
||
|
|
c67c713177 |
feat(agents)!: Agent 금지를 풀고 결과만 돌려주는 서브에이전트 셋을 둔다
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행. |
||
|
|
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행. |
||
|
|
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` 한 줄이다. |
||
|
|
3eb3b06755 |
docs(work): cold-read 시험 2회차 빈틈 52건을 매뉴얼에 반영한다
문제: 2026-11-07 round7 수정 다섯, 통합, round8 확인 리뷰 둘, 문서 과제
하나를 이력 없는 세션 9개로 돌렸다. 매뉴얼에서 답을 못 찾은 곳이 52건
나왔고(1회차 35건), 코드 수정 과제에서 같은 질문이 되풀이됐다: desktop
포매터 결과 가져오기(4세션), 커밋 단위 모순(4), 테스트 수 세는 곳(3), RED 없는
수정의 증거(3), 넘어온 「범위 밖」 항목(3), PR 단계 명령 묶음(2).
고른 방법: 되풀이된 질문은 절차 한 곳에서 끝냈다.
- operate.md 4.1절: spotlessApply 결과를 노트북에 가져와 트리 해시를 맞추는
명령, 결과 XML 보관, 중간 커밋 검증, 도구 설치 단계는 따라 하지 않음
- gates.md: 단계별 묶음 표(PR·main·라운드 끝), 테스트 수 세는 명령, 앞 실행을
증거로 쓰는 조건, 중첩 빌드 FROM-CACHE, 탐침(rc 읽기, --tests 필터, 의존성)
- improve.md: RED 없는 수정의 증거, 같은 원인과 범위 밖의 경계, 업그레이드
안내 행, 약속한 응답으로 맞추기, 「정한 기본값」 확인, 넘어온 항목
- README 4절 커밋 단위(commit-and-pr 정본에 맞춤), 2절 소유자가 정한 큰 변경
- review-criteria 10절 확인 리뷰 README 절 순서, delegate 4.1절 기본값 옮기기
결정 색인에 기본값 일곱을 남겼다(소유자가 뒤집을 수 있다). 처리 표는
evidence.md 11절이다(34행, 고치지 않음 0, 소유자 결정 필요 0). 수정 과제의
답(round8 발견을 어떻게 고칠지)은 쓰지 않았다. 다음 시험이 그 과제다.
위험·한계: 분량 상한에 가까워졌다(improve 143/150, operate 141/150, README
77/80). cold-read 시험은 이 커밋 뒤 3회차가 한다. 기본값 일곱(커밋 단위,
넘어온 항목, 약속한 응답, 검사를 더 엄하게, 업그레이드 안내 행, 태그 단계,
도구 설치)은 소유자 확인 대상이다.
검증(트리
|
||
|
|
6b253c6c75 |
docs(work): 이력 ID 0 규칙을 AGENTS.md와 src/**/CLAUDE.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줄이 있다(대부분 템플릿에서 받은 사본, 고치지 않음).
검증(트리
|
||
|
|
73d39212f5 |
docs(work): cold-read 시험 1회차의 빈틈과 모순을 매뉴얼에 반영한다
문제: 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: 바꾼 것을 패치로 기준 커밋
|
||
|
|
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에서 돌린다 |