[AI] Claude Code 서브에이전트 팀 구성 템플릿 공개

· IT기술 › AI

1편에서 에이전트 팀을 만들 때 공통 에이전트 12개는 개인 Git 저장소로 관리한다고 적었다. 그 저장소를 dev-agent-kit 라는 이름으로 공개했다. 한 프로젝트에서 쓰던 팀을 다른 프로젝트에도 바로 깔 수 있게 일반화한 키트다.

팀 구성은 1편, 작업 흐름은 2편, 에이전트에게 일 맡기는 법과 결과 검증, 맡기지 않을 일은 46·47·48번 글에 있다. 여기서는 무엇이 들어 있고 어떻게 쓰는지만 적는다.

1. 저장소 구성

  • global/ : 사용자 범위(~/.claude)에 설치할 에이전트 12개, 규칙 스킬 3개, 확인 창 권한 규칙
  • project-template/ : 프로젝트에 복사할 CLAUDE.md 와 docs/(인수인계 폴더, 규칙 파일 7개)
  • hooks/guard.js : 서브에이전트의 금지 동작을 막는 PreToolUse 훅
  • tests/ : 동기화·가드 훅·문서 정합성 검사
  • install.sh : global/ 을 설치하고 세션 시작·종료 동기화 훅을 등록한다. 기존 파일은 백업 폴더에 복사한 뒤 덮어쓴다.
  • sync.sh : 에이전트·스킬을 저장소를 거쳐 PC 사이에 주고받는다.
  • init-project.sh : 프로젝트 폴더에 project-template/ 을 적용한다.

2. 설치와 사용 순서

  1. 저장소를 포크한 뒤 자기 포크를 clone 한다.
  2. 그 폴더에서 Claude Code 를 열고 "SETUP.md 읽고 세팅해줘"라고 요청한다. 직접 하려면 ./install.sh --with-plugins 를 실행한다.
  3. 새 프로젝트마다 ./init-project.sh <프로젝트 경로> 를 실행한다.
  4. 그 프로젝트에서 "0단계(초기 세팅)부터 시작해"라고 요청한다.

init-project.sh 는 기존 파일을 덮어쓰지 않는다(CLAUDE.md 가 있으면 CLAUDE.dev-company.md 로 저장). 빈 폴더에 적용해 보면 docs/rules/ 에 규칙 파일 7개가 생기고, 마지막 줄이 다음 할 일을 알려 준다.

빈 폴더에 init-project.sh 를 실행해 CLAUDE.md 와 docs 규칙 파일·인수인계 폴더가 만들어진 터미널 출력

PC 간 동기화는 받는 쪽만 자동이다. 세션 훅은 로컬 커밋과 pull 만 하고 push 대기 커밋 수를 알려 주며, 올리는 건 ./sync.sh --push 로 직접 한다. 포크 대신 clone 해서 자기 비공개 저장소로 올려 쓴다면 DEV_COMPANY_SYNC_AUTOPUSH=1 로 자동 push 를 켤 수 있다. 공개 포크에서는 켜지 않는다.

동기화 대상은 키트 에이전트만이 아니라 ~/.claude/agents 전체다(스킬은 키트 스킬만). 그래서 처음 설치한 PC 에 있던 개인 에이전트도 커밋에 들어간다. push 전에 git log -p @{u}..HEAD 로 올라갈 파일을 확인한다. 윈도우는 WSL 이 아니라 Git Bash 에서 같은 방법으로 쓴다.

3. 처음 만든 뒤 더한 것

다른 개인 프로젝트에 처음 적용했을 때, 0단계가 요구사항을 정하기도 전에 기본 스택(Spring Boot + React)으로 골격을 만들기 시작했다. 멈추고 요구사항부터 정리해 보니 그 프로젝트는 Python 백엔드가 맞았다. 그 뒤 공용으로 손본 것들이다.

  • 스택 선택: 백엔드 담당 에이전트들이 docs/rules/stack.md(CLAUDE.md 8장이 불러오는 파일)의 백엔드 스택을 보고 Spring 또는 Python 규칙 스킬을 불러온다. 스택이 비었으면 "결정 필요"로 돌려준다.
  • 클라우드 중립: AWS 전용 설치 옵션과 aws·cdk 명령의 확인 규칙을 뺐다. terraform apply·docker push 같은 공통 명령의 확인 창은 남겼고, 클라우드 CLI 로 리소스를 만드는 일은 CLAUDE.md 7장의 비용 승인 규칙을 따른다.
  • 가드 훅: 키트 에이전트의 커밋·push·브랜치 전환·PR 생성을 막는다. 보안 리뷰와 기획(조사·기획서)처럼 문서만 쓰는 세 역할은 자기 폴더(docs/security/, docs/prd/ 등) 밖 파일을 Edit/Write 로 고치지 못한다. 메인 세션은 건드리지 않고, Bash 리다이렉트로 쓰는 파일은 못 막는다.
  • 정합성 테스트: 에이전트·스킬·문서가 서로 가리키는 이름과 절 번호가 실제로 있는지 검사한다. 규칙을 고칠 때마다 생기던 어긋남을 사람이 찾지 않으려고 넣었다.
  • 에이전트별 최소 컨텍스트: 키트 에이전트는 CLAUDE.md 를 받지 않고(omitClaudeMd: true, Claude Code v2.1.271 이상), 규칙 파일 7개 중 자기 역할에 필요한 것만 읽는다. 써 보니 한 에이전트가 규칙 파일을 두 번씩 읽어서, 한 번만 읽으라는 지시를 넣었다. 얼마나 줄었는지는 재 보지 않았다.

키트 폴더에서 두 테스트를 돌리면 가드 훅 사례 25개가 모두 ok 로 끝나고, 정합성 검사는 한 줄로 끝난다.

가드 훅 테스트 25개 사례가 모두 ok 이고 정합성 테스트가 에이전트 12개·스킬 3개·문서 28개를 확인한 터미널 출력

저장소는 github.com/bcw2104/dev-agent-kit 이고 MIT 라이선스다.

이 키트는 내 작업 방식에 맞춘 기본값 묶음이다. 다른 프로젝트에 처음 깔았을 때 가장 먼저 깨진 게 스택 가정이었으니, 포크한 뒤에는 docs/rules/stack.md 의 기술 스택과 CLAUDE.md 7장 승인 규칙부터 자기 프로젝트에 맞게 고치고 0단계를 시작하는 게 맞다고 본다.

참고