하네스 설계(design-docs harness/01-harness-design.md)는 검증 진입점 scripts/verify.sh와 비전 문서 docs/vision.md가 함께 생긴다고 했다. verify.sh는 이 브랜치가 만들었는데 비전과 문제 정의 자리가 없었다. claude-harness template/docs의 두 양식을 옮긴다. vision.md는 세 문장 자리만 두고 소유자가 쓴다(에이전트는 읽기만 한다). problem-statement.md는 고객의 말 그대로·지금 버티는 법·하지 않는 것·잴 수 있는 성공 기준 칸을 둔다. AGENTS.md 첫 문단과 docs/README.md 「폴더 밖 문서」가 두 파일을 가리킨다. 검증: python3 scripts/check-docs.py, check-work-docs.py 통과.
4.0 KiB
4.0 KiB
AGENTS.md — 백엔드 템플릿의 정본
Java 21 + Spring Boot Gradle 멀티모듈 Clean Architecture 템플릿이다(버전은 src/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/다. leaf 목록·경로·Gradle path·허용 의존의 정본은 registrysrc/config/architecture/modules.json이다. 문서는 leaf 개수를 적지 않는다. - 방향:
app-bootstrap → adapter:inbound:*·adapter:outbound:* → application-core → domain-core, 실행 모듈 →shared-contract. 개별 edge는 registry만 정한다. - 지역 규칙은 작업 파일과 가장 가까운 폴더의
AGENTS.md다(leaf, family,src/build-logic). 테스트·설정·Docker·문서처럼 폴더를 가로지르는 규칙은.claude/rules/다. - 저장소 루트와
src/최상위에는 정해진 것만 둔다(허용 목록은scripts/check-repo-layout.py). 계층이 아닌 라이브러리는 이 repo에 두지 않고 별도 repo에서 버전으로 받는다(docs/work/reference/related-repos.md).src/composition/*는 조립만 한다. - capability는
src/app-bootstrap/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(그 표면을 바꿨을 때,src/에서), 단계 묶음은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).