[AI] Claude Code 서브 에이전트로 1인 개발회사 만들기 (1/2)
· IT기술 › AI
블로그를 옮길 때 역할별 에이전트를 만들어 일을 나눠 맡겼다(Claude Code 서브 에이전트로 AI에게 일 맡기는 법). 그런데 정의 파일이 그 저장소 안에만 있어서, 새 프로젝트를 시작하면 매번 복사하고 고쳐야 했다.
이번에는 에이전트 팀을 아예 "회사"처럼 다시 짰다. 사람인 나는 CEO 로 승인만 하고, 메인 세션이 개발 PM, 서브 에이전트 12개가 부서원이다. 이번 편은 조직과 정의 파일, 다음 편은 일하는 순서와 안전 규칙이다.
1. 조직표부터 그린다
정의 파일을 쓰기 전에 표부터 만들었다. 누가 무엇을 하고, 어느 단계에 투입되는지다.
| 부서 | 에이전트 | 하는 일 |
|---|---|---|
| 기획 | planning-researcher, planning-spec | 경쟁 서비스 조사, PRD·화면 기획·인수 조건 |
| 백엔드 | be-api, be-domain, be-reviewer | API 명세·컨트롤러, 엔티티·도메인 로직, 테스트·리뷰 |
| 프론트 | fe-design-system, fe-feature, fe-reviewer | 공통 컴포넌트, 기능 화면, 테스트·리뷰 |
| 지원 | qa, infra, dba, security-reviewer | E2E 검수, 배포, 스키마, 보안 점검 |

리뷰어를 따로 둔 이유는 자기 채점을 막기 위해서다. 구현 담당이 자기 테스트를 쓰면 자기 코드에 맞춘 테스트가 나온다. 리뷰어가 쓴 테스트도 QA 가 빠진 시나리오가 없는지 한 번 더 본다. 보안 담당은 반대로 코드를 고치지 않는다. 문제를 찾아 고칠 담당별로 나눠 넘기는 일까지만 한다.
2. 정의 파일 쓰는 법
서브 에이전트는 Markdown 파일 하나다. 위쪽 YAML frontmatter 에 설정을 쓰고, 아래 본문이 그 에이전트의 지침(시스템 프롬프트)이 된다.
---
name: be-reviewer
description: 백엔드 테스트 작성과 코드 리뷰 담당. 구현이 끝난 변경에 테스트를 쓰고 승인 여부를 판단한다.
tools: Read, Write, Edit, Glob, Grep, Bash, Skill
skills: spring-conventions
model: opus
---
너는 백엔드 테스트·리뷰 담당이다.
## 소유 영역
- backend/src/test/ 만 수정한다. 그 밖은 읽기만 한다.
## 하지 않는 일
- 커밋·푸시, 오래 도는 서버 띄우기
## 완료 기준
- ./gradlew test 통과
- name : 에이전트 이름. 필수.
- description : 언제 이 에이전트에게 맡길지. 필수이고, Claude 는 이 문장을 보고 위임 대상을 고른다.
- tools : 쓸 수 있는 도구. 생략하면 쓸 수 있는 도구를 대부분 물려받는다.
- skills : 시작할 때 미리 불러올 스킬. 코딩 규칙 스킬을 여기에 넣었다.
- model :
opus,sonnet,haiku같은 별칭이나inherit.
본문은 모든 에이전트를 같은 순서로 썼다. 소유 영역, 입력, 할 일, 하지 않는 일, 완료 기준, 반환 형식이다. 이 중 가장 신경 써서 쓰는 것은 "하지 않는 일"이다. 할 일만 적으면 에이전트는 친절하게 범위를 넓혀 일한다.
3. 모델은 어디에 쓸까
블로그 프로젝트에서는 자료 조사 담당 하나만 sonnet 으로 두고 나머지는 opus 로 썼다. 조사는 양이 많고 판단은 가벼워서다. 새로 짠 팀은 12개 모두 opus 로 시작했다. 사용 한도에 자주 걸리면 가장 자주, 오래 도는 화면 개발 담당부터 내리고 다음은 QA 로 정해 두었다.
4. 파일마다 주인을 정한다
에이전트 둘이 같은 파일을 고치면 누구 책임인지 흐려진다. 경로별 소유자 표를 운영 규칙 문서(CLAUDE.md)에 넣었다.
backend/.../entity/,repository/→ be-domainbackend/.../controller/,dto/→ be-apibackend/src/test/→ be-reviewer- 마이그레이션 파일 → dba
규칙은 하나다. 자기 영역만 고치고, 남의 영역이 필요하면 직접 고치지 말고 "요청 사항"으로 PM 에게 돌려준다.
5. 공통 에이전트와 프로젝트 전용 에이전트
정의 파일은 두 곳에 둘 수 있다. 사용자 범위인 ~/.claude/agents/ 는 모든 프로젝트에서 쓰고, 프로젝트 범위인 .claude/agents/ 는 그 저장소에서만 쓴다. 이름이 같으면 프로젝트 쪽 에이전트를 사용한다.
이 규칙을 그대로 이용했다. 공통 12개는 사용자 범위에 두고 개인 Git 저장소로 관리한다. 어떤 프로젝트가 Kotlin 이라면 같은 이름의 be-domain.md 를 프로젝트에 두어 그 프로젝트에서만 바꾼다.
교체한 에이전트는 공통 쪽 개선을 받지 못하니, 교체한 이유와 기준 버전을 프로젝트 문서에 남기게 했다. 프로젝트 전용 에이전트는 공통 12개에 없는 역할일 때만 만들고, 만들거나 교체할 때도 내 승인을 거치게 했다. 파일 하나가 늘 때마다 따로 챙길 일이 늘기 때문이다.
다음 편에서는 이 팀이 기능 하나를 어떤 순서로 만들고, 어디서 멈추게 했는지 정리한다.