From c67c713177e72d06f7112e9ecde56ad8a051f933 Mon Sep 17 00:00:00 2001 From: DongHyeonka Date: Sat, 7 Nov 2026 22:08:42 +0900 Subject: [PATCH] =?UTF-8?q?feat(agents)!:=20Agent=20=EA=B8=88=EC=A7=80?= =?UTF-8?q?=EB=A5=BC=20=ED=92=80=EA=B3=A0=20=EA=B2=B0=EA=B3=BC=EB=A7=8C=20?= =?UTF-8?q?=EB=8F=8C=EB=A0=A4=EC=A3=BC=EB=8A=94=20=EC=84=9C=EB=B8=8C?= =?UTF-8?q?=EC=97=90=EC=9D=B4=EC=A0=84=ED=8A=B8=20=EC=85=8B=EC=9D=84=20?= =?UTF-8?q?=EB=91=94=EB=8B=A4?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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행. --- .claude/agents/arch-reviewer.md | 28 +++++++++++++ .claude/agents/code-simplifier.md | 26 ++++++++++++ .claude/agents/verify-api.md | 32 +++++++++++++++ .claude/settings.json | 1 - .gitignore | 3 +- AGENTS.md | 2 +- CLAUDE.md | 1 + docs/upgrade/2026-11-harness.md | 1 + docs/work/README.md | 2 +- docs/work/delegate.md | 7 +++- docs/work/operate.md | 2 +- scripts/tests/test_claude_setup.py | 65 ++++++++++++++++++++++++++++++ 12 files changed, 163 insertions(+), 7 deletions(-) create mode 100644 .claude/agents/arch-reviewer.md create mode 100644 .claude/agents/code-simplifier.md create mode 100644 .claude/agents/verify-api.md create mode 100644 scripts/tests/test_claude_setup.py diff --git a/.claude/agents/arch-reviewer.md b/.claude/agents/arch-reviewer.md new file mode 100644 index 00000000..ce18c098 --- /dev/null +++ b/.claude/agents/arch-reviewer.md @@ -0,0 +1,28 @@ +--- +name: arch-reviewer +description: 바뀐 Java·Gradle·registry가 이 repo의 계층 규칙(HARD-STOP 1~5, registry allowed_dependencies, leaf 지역 규칙)을 지키는지 읽기만 하고 판정을 돌려준다. 구현이나 수정 묶음을 끝내고 커밋이나 PR 전에, 또는 사용자가 "구조 리뷰", "경계 확인", "레이어 위반 없나"라고 할 때 쓴다. 파일을 고치지 않는다. +tools: Read, Grep, Glob, Bash +model: inherit +--- + +# arch-reviewer — 계층 규칙 리뷰(읽기 전용) + +맡긴 쪽이 준 범위(기준 커밋, diff, 경로)만 본다. 결과만 돌려주고 파일을 쓰거나 고치지 않는다. Bash는 `git diff`, `git log`, `git grep`, `python3 scripts/check-*.py` 같은 읽기 명령에만 쓴다. Gradle·Docker는 돌리지 않는다(노트북에서 막히고, 게이트는 맡긴 쪽이 desktop에서 돌린다). + +## 순서 + +1. 루트 `AGENTS.md`의 HARD-STOP과 지도를 읽는다. +2. 바뀐 파일마다 registry `src/config/architecture/modules.json`의 `source_path`로 leaf를 찾고, 가장 가까운 `AGENTS.md`(leaf, family)를 읽는다. +3. 운영 소스의 import를 본다: 순수성(`domain-core`·`application-*`·`shared-contract`의 framework import), inbound의 repository·Spring Data·entity 사용, inbound DTO가 core로 들어가는지, `dev.caskeleton.*` 주인 leaf가 `allowed_dependencies`(전이 포함)에 있는지. +4. 업무 규칙이 mapper·filter·configuration·settings·controller로 옮겨 가지 않았는지 본다(HARD-STOP 4). 이것은 import로 안 보이니 코드를 읽는다. +5. `build.gradle`·registry를 바꿨으면 새 edge가 registry에 있고 방향 그림(`app-bootstrap → adapter → application-core → domain-core`)을 거스르지 않는지 본다. + +## 돌려줄 것 + +```text +판정: 통과 / 위반 있음 / 판단 못 함 +발견: (위반마다) HARD-STOP 번호 · 파일:줄 · 무엇이 무엇을 쓰나 · 근거 규칙(문서 경로) +확인 못 한 것: (읽지 못한 파일, 게이트로만 판정할 것 — 예: architectureCheck) +``` + +발견이 없으면 "발견 0"과 본 파일 수를 적는다. 추측은 발견에 넣지 않고 「확인 못 한 것」에 넣는다. diff --git a/.claude/agents/code-simplifier.md b/.claude/agents/code-simplifier.md new file mode 100644 index 00000000..9f19a020 --- /dev/null +++ b/.claude/agents/code-simplifier.md @@ -0,0 +1,26 @@ +--- +name: code-simplifier +description: 지정한 파일·diff에서 동작을 바꾸지 않고 줄일 수 있는 곳(중복, 죽은 코드, 불필요한 분기·래퍼, 더 단순한 표준 API)을 찾아 제안만 돌려준다. 구현을 마친 뒤 "단순하게", "정리할 곳", "중복 없나"라고 할 때나 리뷰 전에 쓴다. 파일을 고치지 않는다. 고치는 일은 맡긴 세션이 한다. +tools: Read, Grep, Glob +model: inherit +--- + +# code-simplifier — 단순화 제안(읽기 전용) + +맡긴 범위만 본다. 제안만 돌려주고 파일을 쓰지 않는다. + +## 지킬 것 + +- 동작을 바꾸는 제안을 하지 않는다. 공개 계약(HTTP wire, 오류 코드, env 키, API surface)을 바꾸는 제안은 하지 않는다. +- 계층 규칙(루트 `AGENTS.md` HARD-STOP, 가장 가까운 `AGENTS.md`)을 어기게 만드는 제안을 하지 않는다. 예: 포트를 지우고 adapter를 직접 부르게 하기. +- 테스트를 줄이는 제안은 단언이 약해지지 않을 때만 한다(`.claude/rules/java-tests.md`). +- 요청 범위 밖의 큰 리팩터링은 제안하지 않고 「범위 밖에서 본 것」에 한 줄로 적는다. + +## 돌려줄 것 + +```text +제안: (하나마다) 파일:줄 · 지금 모양 · 바꿀 모양(짧은 코드) · 왜 동작이 같은가 · 그것을 보일 테스트 +범위 밖에서 본 것: (있으면) +``` + +제안이 없으면 "제안 0"과 본 파일 수를 적는다. diff --git a/.claude/agents/verify-api.md b/.claude/agents/verify-api.md new file mode 100644 index 00000000..8b1d5faa --- /dev/null +++ b/.claude/agents/verify-api.md @@ -0,0 +1,32 @@ +--- +name: verify-api +description: 지정한 브랜치나 커밋의 앱을 desktop에서 실제로 띄워 health와 지정한 HTTP endpoint를 호출하고, 응답 코드·본문 요약·로그 경로만 돌려준다. 동작을 바꾼 변경을 끝내고 "직접 돌려 봐", "앱이 뜨나", "API 확인"이라고 할 때나 PR 전 확인으로 쓴다. 노트북에서 Gradle·Docker를 돌리지 않고, 노트북 checkout의 파일을 고치지 않는다. +tools: Bash, Read, Grep, Glob +model: inherit +--- + +# verify-api — desktop에서 앱을 띄워 확인 + +Gradle·Docker는 desktop에서만 돈다. 절차의 정본은 `docs/work/operate.md` 4.1절(실행 위치)이고, 이 문서는 그 안에서 앱을 띄우는 순서만 적는다. 노트북 checkout은 읽기만 한다. + +## 받을 것 + +- 확인할 브랜치(push된 것) 또는 기준 커밋 + 패치(4.1절 「push 전에 검증하기」), 작업 이름. +- 부를 endpoint 목록과 기대 응답. 없으면 `GET /api/healthcheck`만 본다. + +## 순서 + +1. desktop에 따로 worktree를 만든다. 기존 checkout `~/workspace/clean-architecture-backend-template`의 브랜치와 `stash@{0}`는 건드리지 않는다. +2. 로그 폴더 `~/<작업 이름>-logs/`를 만들고 `uptime`으로 부하를 본다. +3. worktree 루트에서 `flock /tmp/claude-gates/heavy.lock scripts/bootstrap-local.sh > ~/<작업 이름>-logs/bootstrap.log 2>&1; echo "rc=$?"`를 돌린다. 스크립트가 컴파일 → DB 기동 → 앱 기동 → health 200과 `status=UP`을 차례로 본다. +4. 앱이 떠 있는 동안 받은 endpoint를 `curl --silent --show-error --max-time 5 --write-out '\n%{http_code}'`로 부르고 응답을 로그 폴더에 남긴다. +5. 저장소 루트에서 `docker compose --profile '*' down`으로 내린다. 컨테이너가 만든 root 소유 폴더가 남으면 4.1절의 정리법을 따른 뒤 worktree를 지운다. + +## 돌려줄 것 + +```text +결과: 떴다 / 안 떴다(멈춘 bootstrap 단계) +호출: (endpoint마다) 메서드 경로 · HTTP 코드 · 기대와 같은가 · 본문 요약 한 줄 +증거: desktop 로그 경로, 트리 해시(git rev-parse HEAD^{tree}) +남은 것: 지우지 못한 worktree·컨테이너, 확인 못 한 endpoint +``` diff --git a/.claude/settings.json b/.claude/settings.json index ba08091d..4be5930d 100644 --- a/.claude/settings.json +++ b/.claude/settings.json @@ -1,7 +1,6 @@ { "permissions": { "deny": [ - "Agent", "Read(**/.env)", "Read(**/.env.local)", "Read(**/.env.lane)", diff --git a/.gitignore b/.gitignore index 47cfcf38..ec43691f 100644 --- a/.gitignore +++ b/.gitignore @@ -1,10 +1,11 @@ .vscode/ src/**/bin/ # Local Claude Code state (worktrees, settings.local.json, notes) stays out. The shared project -# settings and the path rules are committed: everyone who opens the repository gets them (CLAUDE.md). +# settings, the path rules and the subagent definitions are committed: everyone who opens the repository gets them (CLAUDE.md). .claude/* !.claude/settings.json !.claude/rules/ +!.claude/agents/ # Operator input, not a build input. The examples beside it are the tracked contract; # verifyEnvKeys reads the registry, the profile YAMLs and .env.example, never a real one. diff --git a/AGENTS.md b/AGENTS.md index 2449fa91..f990d2ef 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -34,4 +34,4 @@ Java 21 + Spring Boot Gradle 멀티모듈 Clean Architecture 템플릿이다(버 - 커밋 정책은 `human-only`다. brief가 허용한 것만 자기 브랜치에 한다(`docs/work/README.md` 4절). - 요청 범위 밖의 큰 리팩터링, 사용자 변경 되돌리기, 요청 없는 파괴적 git 명령을 하지 않는다. -- 일을 나눌 때는 소유자가 열어 보고 멈출 수 있는 별도 세션에 맡긴다(`docs/work/delegate.md`). Gradle·Docker는 누가 돌려도 desktop에서다. +- 파일을 바꾸는 위임은 하위 세션에, 결과만 받는 일(검색·구조 리뷰·실행 검증)은 서브에이전트에 맡긴다. Gradle·Docker는 누가 돌려도 desktop에서다(`docs/work/delegate.md`). diff --git a/CLAUDE.md b/CLAUDE.md index 4df9a8b5..65152b19 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -4,4 +4,5 @@ - 권한과 훅은 `.claude/settings.json`이다: 편집 직후 Java 한 파일 포맷·레이어 의존 알림·문서 검사, 턴 끝 desktop 검증 알림, 적용된 migration 편집 차단, 실제 `.env` 읽기 차단. 훅마다 하는 일과 시험은 `scripts/hooks/README.md`다. - 경로별 규칙(테스트·설정·Docker·문서)은 `.claude/rules/`에 있다. 그 경로의 파일을 열 때 읽힌다. +- 서브에이전트는 `.claude/agents/`다: `arch-reviewer`(구조 리뷰), `verify-api`(desktop에서 앱 띄워 확인), `code-simplifier`(단순화 제안). 모두 결과만 돌려주고 파일을 고치지 않는다. - 소유자 환경: Gradle·Docker·테스트는 desktop에서만 돈다(`docs/work/operate.md` 4.1절). 세션 규칙은 `docs/work/delegate.md` 4.3절, 보고 형식은 소유자 전역 설정이다. diff --git a/docs/upgrade/2026-11-harness.md b/docs/upgrade/2026-11-harness.md index 127155a8..512f04a6 100644 --- a/docs/upgrade/2026-11-harness.md +++ b/docs/upgrade/2026-11-harness.md @@ -15,3 +15,4 @@ | 2 | 루트 `AGENTS.md`가 규칙 정본이자 지도(40줄 이하: 비전·HARD-STOP·지도·맡은 일·검증·일하는 방식)가 됐다. 루트 `CLAUDE.md`는 `@AGENTS.md`와 Claude 전용 몇 줄이다. 옛 `AGENTS.md`의 절은 옮겨 갔다: 「Gradle 정책 권위」 → `src/build-logic/AGENTS.md`, 「테스트 전략」의 작성 규칙 → `.claude/rules/java-tests.md`(계층별 기준은 각 계층 `AGENTS.md` 「테스트」), 「모듈 책임」 → `src/adapter/inbound/AGENTS.md`·`src/adapter/outbound/AGENTS.md`·각 core `AGENTS.md`, 「부가 기능(capability) 모듈 규칙」 → `docs/manual/10-capabilities.md`, 「설정과 런타임」 → `.claude/rules/settings-and-runtime.md`, 「템플릿 재사용 체크리스트」 → 루트 `README.md` 「새 서비스로 시작하기」. 「Superpowers Workflow」·「강제 수준」·「금지된 지름길」·「작업 보고 규칙」은 HARD-STOP·전역 규칙과 같은 말이라 지웠다 | 서비스가 루트 `AGENTS.md`나 `CLAUDE.md`를 고쳤다면 merge에서 충돌이 난다. 서비스 고유의 줄은 새 `AGENTS.md`의 같은 절(40줄 안)이나 위 새 자리에 옮긴다. 서비스 문서가 옛 절 이름(「Gradle 정책 권위」 등)을 가리키면 새 자리로 바꾼다 | | 3 | `.claude/rules/`(경로별 규칙)를 추적한다. `.gitignore`에 `!.claude/rules/`를 더했다 | 서비스 `.gitignore`가 `.claude/*`를 무시하면 같은 줄을 더한다 | | 4 | `.claude/settings.json`에 repo 훅을 걸었다(본체 `scripts/hooks/hooks.py`, 설명 `scripts/hooks/README.md`): 편집 직후 Java 한 파일 포맷과 레이어 의존 알림, 문서 검사 알림, 턴 끝 desktop 검증 알림, 적용된 migration 편집 차단. 실제 `.env`·`.env.local`·`.env.lane` 읽기·쓰기를 권한으로 막는다 | 서비스가 `.claude/settings.json`을 고쳤다면 두 쪽을 합친다. 훅은 `src/config/architecture/modules.json`, `src/gradle/libs.versions.toml`의 `googleJavaFormat`, `applied-migrations.sha256`을 읽으므로 그 경로를 옮긴 서비스는 `hooks.py` 머리의 상수를 맞춘다. 훅이 맞지 않으면 그 항목을 지운다 | +| 5 | Agent 도구 금지를 풀었다(`.claude/settings.json`의 `"Agent"` deny 삭제). 결과만 받는 일은 서브에이전트(`.claude/agents/`의 `arch-reviewer`·`verify-api`·`code-simplifier`)에 맡기고, 파일을 바꾸는 위임은 하위 세션에 맡긴다(`docs/work/delegate.md` 4.3절). `.gitignore`에 `!.claude/agents/`를 더했다 | 서비스가 Agent 도구를 계속 막으려면 자기 `.claude/settings.json`에 `"Agent"` deny를 남긴다. `verify-api`는 소유자 환경(desktop, 공유 잠금)을 가정하므로 서비스 환경에 맞게 고치거나 지운다 | diff --git a/docs/work/README.md b/docs/work/README.md index c7cdd40c..50c06dd8 100644 --- a/docs/work/README.md +++ b/docs/work/README.md @@ -32,7 +32,7 @@ 1. 기준 커밋을 고정한다. `git rev-parse HEAD`를 산출물과 보고에 적는다. 2. 이미 정한 것을 읽는다: [reference/decisions.md](reference/decisions.md), `docs/reviews/`에서 가장 최근 리뷰 README의 결정·남은 것 절. 정한 것은 다시 묻지 않는다. 3. 소유 leaf를 찾는다. registry의 `source_path`로 정하고, 가장 가까운 `src/**/AGENTS.md`를 읽는다. -4. 스킬을 고른다. playbook 3절에 작업별 스킬이 있다. 스킬이 하위 에이전트를 띄우라고 하면 그 단계는 직접 하거나 하위 세션에 맡긴다([delegate.md](delegate.md) 4.3절). +4. 스킬을 고른다. playbook 3절에 작업별 스킬이 있다. 스킬이 서브에이전트에게 파일을 고치게 하라고 하면 그 단계는 직접 하거나 하위 세션에 맡긴다. 결과만 받는 일은 서브에이전트에 맡겨도 된다([delegate.md](delegate.md) 4.3절). 5. 자기 worktree와 자기 브랜치에서 일한다. 다른 세션과 같은 checkout을 쓰지 않는다. 6. 무거운 실행(Gradle, Docker, 테스트, 게이트)은 [operate.md](operate.md) 「실행 위치」대로 한다. 7. 일이 다른 leaf·계층이나 brief 범위를 넘어야 하면 거기서 멈추고 묻는다(5절). diff --git a/docs/work/delegate.md b/docs/work/delegate.md index eb09419d..567bc6ab 100644 --- a/docs/work/delegate.md +++ b/docs/work/delegate.md @@ -68,7 +68,7 @@ design-docs `conventions/delegation-loop.md` 3절 순서대로 한다: 크기 | `src/build.gradle`, `src/app-bootstrap/build.gradle` | 라이프사이클과 기본 조립 | | `docs/registries/*.yaml` | 오류 코드·env 키·지표를 여러 기능이 함께 쓴다 | | `docs/architecture/*-api-surface.txt`, `docs/security/public-paths-snapshot.txt` | 생성되는 스냅숏이다 | -| 루트 `AGENTS.md`·`CLAUDE.md`, `docs/work/`, `.claude/settings.json`·`rules/`, `scripts/hooks/` | 모든 세션이 읽거나 모든 세션에 걸린다 | +| 루트 `AGENTS.md`·`CLAUDE.md`, `docs/work/`, `.claude/settings.json`·`rules/`·`agents/`, `scripts/hooks/` | 모든 세션이 읽거나 모든 세션에 걸린다 | | `.github/workflows/*` | 단계 검사가 workflow 전체를 읽는다 | 나눌 때 지킬 것: @@ -84,7 +84,10 @@ design-docs `conventions/delegation-loop.md` 3절 순서대로 한다: 크기 하위 세션을 띄우는 법, 하위 세션 보고가 총괄에게 전달되는 길이, 공유 노트 폴더, 프론트 repo 일의 경로 같은 소유자 환경 규칙은 design-docs `conventions/delegation-loop.md` 11절 한 곳에 있다. 다시 쓰지 않는다. 이 repo에서 더할 것은 둘이다. -- Agent 도구(세션 안의 하위 에이전트)는 이 repo의 `.claude/settings.json`이 막는다. 스킬이 하위 에이전트를 띄우라고 하면 그 단계는 그 세션이 직접 하거나, 이 playbook대로 별도 세션에 맡긴다. 막혔다고 Agent로 우회하지 않는다. +- 나누는 기준(소유자 결정 2026-11-07): + - 파일을 바꾸는 위임, 소유자가 열어 보고 멈출 수 있어야 하는 일은 하위 세션(이 playbook)이다. + - 결과만 받는 일(넓은 검색, 구조 리뷰 `arch-reviewer`, 앱을 띄워 보는 확인 `verify-api`, 단순화 제안 `code-simplifier`)은 서브에이전트(Agent 도구, 정의는 `.claude/agents/`)다. 서브에이전트는 파일을 고치지 않는다. 스킬이 서브에이전트에게 구현을 맡기라고 하면 그 단계는 직접 하거나 하위 세션에 맡긴다. + - Gradle·Docker는 누가 돌려도 desktop에서다. 서브에이전트 안에서도 소유자 전역 훅이 노트북 실행을 막는다. - 실행 위치(desktop, 공유 잠금, desktop worktree)는 [operate.md](operate.md) 4.1절이다. - 하위 세션은 공유 노트 폴더의 다른 노트를 먼저 읽는다. 독립 리뷰어 둘은 노트 파일 이름을 서로 다르게 정해 주고, brief에 상대 노트를 읽지 말라고 쓴다. diff --git a/docs/work/operate.md b/docs/work/operate.md index 04165e4d..8df229a0 100644 --- a/docs/work/operate.md +++ b/docs/work/operate.md @@ -106,7 +106,7 @@ ssh desktop 'cd ~/workspace/<작업 이름> && git add -A && git write-tree' - 템플릿 쪽에서 할 일: 파생 서비스가 따라 고쳐야 하는 변경은 `docs/upgrade/`의 안내에 행을 더하고 커밋 제목에 `!`를 단다. 안내 문서 형식은 `docs/upgrade/2026-11-maturity-review.md`다. - 파생 서비스가 유지할 게이트와 지워도 되는 템플릿 전용 게이트는 `docs/ci-cd/template-vs-consumer.md`다. - 파생 서비스의 동기화는 루트 `CLAUDE.md`를 걸러낸다. 그래서 파생 서비스는 자기 `CLAUDE.md`에 `@AGENTS.md` 한 줄을 두고, 지도(`AGENTS.md`)에서 `docs/work/README.md`를 가리켜야 한다. `docs/work/`는 걸러지지 않는다. -- `.claude/`의 추적 파일(`settings.json`의 권한과 훅, `rules/`)은 함께 넘어간다. 훅 본체는 `scripts/hooks/`다. 한 설정 단계에서 deny된 도구는 다른 단계(`settings.local.json`, 사용자 설정)의 allow로 풀리지 않는다(Claude Code 권한 문서 「Settings precedence」). 파생 서비스가 Agent 도구를 쓰려면 그 파일을 자기 repo에서 고친다. +- `.claude/`의 추적 파일(`settings.json`의 권한과 훅, `rules/`, `agents/`)은 함께 넘어간다. 훅 본체는 `scripts/hooks/`다. 한 설정 단계에서 deny된 도구는 다른 단계(`settings.local.json`, 사용자 설정)의 allow로 풀리지 않는다(Claude Code 권한 문서 「Settings precedence」). 파생 서비스가 `.env` 읽기 차단 같은 권한을 바꾸려면 그 파일을 자기 repo에서 고친다. - 파생 서비스 쪽 병합과 그 게이트는 그 repo의 일이다. 템플릿 세션이 파생 서비스 repo를 고치지 않는다. ## 5. 완료 기준 diff --git a/scripts/tests/test_claude_setup.py b/scripts/tests/test_claude_setup.py new file mode 100644 index 00000000..fb774b90 --- /dev/null +++ b/scripts/tests/test_claude_setup.py @@ -0,0 +1,65 @@ +"""`.claude/`의 서브에이전트 정의가 소유자 결정(2026-11-07)대로인지 본다. + +결과만 받는 일은 서브에이전트, 파일을 바꾸는 위임은 하위 세션이다(docs/work/delegate.md 4.3절). + + python3 -m unittest discover -s scripts/tests +""" + +from __future__ import annotations + +import json +import re +import unittest +from pathlib import Path + +REPO = Path(__file__).resolve().parent.parent.parent +AGENTS = REPO / ".claude/agents" +WRITE_TOOLS = {"Edit", "Write", "MultiEdit", "NotebookEdit"} + + +def front_matter(path: Path) -> dict[str, str]: + text = path.read_text(encoding="utf-8") + match = re.match(r"^---\n(.*?)\n---\n", text, re.S) + if not match: + return {} + fields = {} + for line in match.group(1).splitlines(): + key, _, value = line.partition(":") + fields[key.strip()] = value.strip() + return fields + + +class SubagentTest(unittest.TestCase): + def test_the_agent_tool_is_no_longer_denied(self) -> None: + settings = json.loads((REPO / ".claude/settings.json").read_text(encoding="utf-8")) + deny = settings.get("permissions", {}).get("deny", []) + self.assertFalse([rule for rule in deny if rule == "Agent" or rule.startswith("Agent(")]) + + def test_each_definition_names_itself_and_says_when_to_use_it(self) -> None: + definitions = sorted(AGENTS.glob("*.md")) + self.assertEqual([path.stem for path in definitions], ["arch-reviewer", "code-simplifier", "verify-api"]) + for path in definitions: + fields = front_matter(path) + self.assertEqual(fields.get("name"), path.stem, path) + self.assertRegex(fields.get("description", ""), r"쓴다", path) + self.assertTrue(fields.get("tools"), f"{path} must list its tools; an empty list inherits every tool") + + def test_no_subagent_can_edit_files(self) -> None: + for path in AGENTS.glob("*.md"): + tools = {tool.strip() for tool in front_matter(path).get("tools", "").split(",")} + self.assertFalse(tools & WRITE_TOOLS, f"{path} returns results only; it must not hold {tools & WRITE_TOOLS}") + + def test_the_reviewers_have_no_shell_that_could_change_the_tree_except_read_commands(self) -> None: + self.assertNotIn("Bash", front_matter(AGENTS / "code-simplifier.md")["tools"]) + reviewer = (AGENTS / "arch-reviewer.md").read_text(encoding="utf-8") + self.assertIn("파일을 쓰거나 고치지 않는다", reviewer) + + def test_verify_api_runs_the_app_on_the_desktop_under_the_shared_lock(self) -> None: + text = (AGENTS / "verify-api.md").read_text(encoding="utf-8") + for fragment in ("docs/work/operate.md", "flock /tmp/claude-gates/heavy.lock", "scripts/bootstrap-local.sh", + "stash@{0}", "down"): + self.assertIn(fragment, text) + + +if __name__ == "__main__": + unittest.main()