문제: 하네스에 분야 지식이 없다. 영속성·메시징·보안·관측·성능·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.
4.4 KiB
4.4 KiB
AGENTS.md — 백엔드 템플릿의 정본
Java 21 + Spring Boot Gradle 멀티모듈 Clean Architecture 템플릿이다(버전은 gradle/libs.versions.toml, 기본 패키지 dev.caskeleton). 서비스는 이 repo를 받아 도메인·유스케이스·adapter만 채운다. 모듈 경계와 의존 방향은 바꾸지 않고, 게이트가 그것을 증명한다. 업무 예제·배포 인프라는 두지 않는다. 속도보다 아키텍처 보존이 먼저다. 비전 전문은 docs/vision.md(소유자가 쓴다), 문제 정의는 docs/problem-statement.md다.
HARD-STOP — 하나라도 어기면 동작해도 완료가 아니다
domain-core가 framework·transport·database·cloud 의존성을 가진다.- controller가 repository·Spring Data interface·persistence entity를 직접 쓴다.
- inbound DTO가
application-core나domain-core로 들어간다. - 업무 규칙이 mapper·filter·configuration·settings·controller로 옮겨 간다.
- 프로젝트 의존성이 registry나 Gradle 의존성 검증을 어긴다.
- 관련 검증 없이, 또는 돌리지 못한 이유를 밝히지 않고 완료를 말한다.
- 결론의 범위와 위험에 맞는 증거 없이 저장소 전체에 대한 결론을 낸다.
지도
- Gradle 루트는 저장소 루트다.
src/에는 계층 코드만 있다(domain/·application/·adapter/·bootstrap/·shared-contract/). leaf 목록·폴더·Gradle path·허용 의존의 정본은 registrygradle/modules.json이다. Gradle path는 폴더와 다르다(:app-bootstrap은src/bootstrap/app). 문서는 leaf 개수를 적지 않는다. - 방향:
app-bootstrap → adapter:inbound:*·adapter:outbound:* → application-core → domain-core, 실행 모듈 →shared-contract. 개별 edge는 registry만 정한다. - 지역 규칙은 작업 파일과 가장 가까운 폴더의
AGENTS.md다(leaf, family,build-logic). 테스트·설정·Docker·문서처럼 폴더를 가로지르는 규칙은.claude/rules/다. - 저장소 루트와
src/최상위에는 정해진 것만 둔다(허용 목록은scripts/check-repo-layout.py). 계층이 아닌 라이브러리는 이 repo에 두지 않고 별도 repo에서 버전으로 받는다(docs/work/reference/related-repos.md).src/bootstrap/은 조립 계층이다(조립 루트app과 조립만 하는composition:*leaf). - capability는
src/bootstrap/app/build.gradle의runtimeOnly한 줄로 켜고 끈다. 기준은docs/manual/10-capabilities.md. 문서 위치 규칙은docs/README.md.
맡은 일
먼저 docs/work/README.md, 그다음 맡은 일의 playbook 하나를 끝까지 읽는다(모두 docs/work/): 새 기능 new-feature.md · 리뷰·수정·리팩터링 improve.md · 대안 비교와 소유자 결정 research-design.md · 문서 docs-writing.md · 게이트·릴리스·파생 서비스 operate.md · 일 나누기 delegate.md. brief가 있으면 brief의 범위·크기·완료 기준이 먼저다.
검증
- 진입점은
scripts/verify.sh <단계>다. 단계 이름은 workflow와 같다(pr·main·nightly·release, 그리고docs·leaf·app·round). Gradle·Docker가 드는 단계는 스크립트가 desktop으로 옮겨 잠금 아래에서 돌린다. - leaf 하나:
scripts/verify.sh leaf <gradle-path>. 경로는 registry의gradle_path다. 기억이나 폴더 이름으로 짐작하지 않는다. - 저장소 전체:
./gradlew architectureCheck,./gradlew :app-bootstrap:architectureTest,verifyPublicPathSnapshot·:app-bootstrap:verifyEnvKeys(그 표면을 바꿨을 때), 단계 묶음은scripts/verify.sh pr등. 게이트 고르기는docs/work/reference/gates.md. - 문서·지침을 고쳤으면
scripts/verify.sh docs(노트북에서 돈다).
일하는 방식
- 커밋 정책은
human-only다. brief가 허용한 것만 자기 브랜치에 한다(docs/work/README.md4절). - 요청 범위 밖의 큰 리팩터링, 사용자 변경 되돌리기, 요청 없는 파괴적 git 명령을 하지 않는다.
- 파일을 바꾸는 위임은 하위 세션에, 결과만 받는 일(검색·구조 리뷰·실행 검증)은 서브에이전트에 맡긴다. Gradle·Docker는 누가 돌려도 desktop에서다(
docs/work/delegate.md). - 여러 분야에 걸친 일은 리드(메인 세션)가 분야 지식을 골라 새 눈 리뷰어에게 맡기고 합친다. 명단·경로표·넘김·충돌 규칙은
docs/work/experts.md다.