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행.
3.5 KiB
3.5 KiB
AGENTS.md — 백엔드 템플릿의 정본
Java 21 + Spring Boot Gradle 멀티모듈 Clean Architecture 템플릿이다(버전은 src/gradle/libs.versions.toml, 기본 패키지 dev.caskeleton). 서비스는 이 repo를 받아 도메인·유스케이스·adapter만 채운다. 모듈 경계와 의존 방향은 바꾸지 않고, 게이트가 그것을 증명한다. 업무 예제·배포 인프라는 두지 않는다. 속도보다 아키텍처 보존이 먼저다.
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).src/platforms/*는 계층이 아닌 들여온 제품,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의 범위·크기·완료 기준이 먼저다.
검증
- leaf 하나: registry의
gradle_path로./gradlew <gradle-path>:check --console=plain(src/에서). 기억이나 폴더 이름으로 짐작하지 않는다. - 저장소 전체:
./gradlew architectureCheck,./gradlew :app-bootstrap:architectureTest,verifyPublicPathSnapshot·:app-bootstrap:verifyEnvKeys(그 표면을 바꿨을 때). 게이트 고르기는docs/work/reference/gates.md. - 문서·지침을 고쳤으면
python3 scripts/check-work-docs.py와python3 scripts/check-docs.py.
일하는 방식
- 커밋 정책은
human-only다. brief가 허용한 것만 자기 브랜치에 한다(docs/work/README.md4절). - 요청 범위 밖의 큰 리팩터링, 사용자 변경 되돌리기, 요청 없는 파괴적 git 명령을 하지 않는다.
- 파일을 바꾸는 위임은 하위 세션에, 결과만 받는 일(검색·구조 리뷰·실행 검증)은 서브에이전트에 맡긴다. Gradle·Docker는 누가 돌려도 desktop에서다(
docs/work/delegate.md).