Files
clean-architecture-backend-…/.claude/agents/verify-api.md
T
DongHyeonka 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행.
2026-11-07 22:08:42 +09:00

2.2 KiB

name, description, tools, model
name description tools model
verify-api 지정한 브랜치나 커밋의 앱을 desktop에서 실제로 띄워 health와 지정한 HTTP endpoint를 호출하고, 응답 코드·본문 요약·로그 경로만 돌려준다. 동작을 바꾼 변경을 끝내고 "직접 돌려 봐", "앱이 뜨나", "API 확인"이라고 할 때나 PR 전 확인으로 쓴다. 노트북에서 Gradle·Docker를 돌리지 않고, 노트북 checkout의 파일을 고치지 않는다. Bash, Read, Grep, Glob 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를 지운다.

돌려줄 것

결과: 떴다 / 안 떴다(멈춘 bootstrap 단계)
호출: (endpoint마다) 메서드 경로 · HTTP 코드 · 기대와 같은가 · 본문 요약 한 줄
증거: desktop 로그 경로, 트리 해시(git rev-parse HEAD^{tree})
남은 것: 지우지 못한 worktree·컨테이너, 확인 못 한 endpoint