클로드 안에 개발팀 꾸리기 — 에이전트 4개 파일 원문 + 넘기는 프롬프트

아래 네 장을 그대로 복사해 넣으시면 됩니다.

새로 설치할 건 없습니다. 클로드 코드만 있으면 됩니다.

---

0. 어디에 넣나

프로젝트 폴더 맨 위에 .claude/agents/ 를 만들고 그 안에 네 장을 넣습니다.

내프로젝트/
  .claude/
    agents/
      planner.md
      coder.md
      tester.md
      reviewer.md
  src/
  ...

프로젝트마다 따로 두기 싫으시면 ~/.claude/agents/ 에 넣으세요. 그러면 모든 프로젝트에서 잡힙니다. 같은 이름이 양쪽에 있으면 프로젝트 쪽이 이깁니다.

📌 agents** 폴더를 이번에 처음 만드셨다면 클로드 코드를 껐다 켜 주세요.** 클로드 코드는 이 폴더를 지켜보고 있어서, 폴더가 원래 있었다면 파일을 넣거나 나중에 고쳐도 몇 초 안에 반영됩니다. 다만 지켜보는 대상은 세션이 시작될 때 있었던 폴더뿐이라, 폴더를 이번에 처음 만든 경우에만 다시 켜야 합니다.

넣고 나서 확인하는 법. 입력창에 @ 를 치면 나오는 목록에 네 개가 보입니다. 아니면 그냥 @agent-reviewer 를 한 번 불러 보세요 — 돌면 잡힌 겁니다.

/agents 로 목록을 보는 방법은 구버전(v2.1.197 이하)에서만 됩니다. 그 다음 버전부터는 목록 대신 “클로드에게 요청하거나 .claude/agents/ 를 직접 편집하라”는 안내만 나옵니다.

---

1. 앞머리에 뭘 적나

파일 맨 위 --- 사이에 들어가는 부분입니다.

줄	필수	뜻
name	필수	부를 이름. 소문자와 하이픈만
description	필수	언제 이 에이전트를 쓰는지. 클로드가 이걸 읽고 고릅니다
tools	선택	쓸 수 있는 도구. 안 적으면 전부 물려받습니다
model	선택	sonnet · opus · haiku · fable · inherit. 안 적으면 지금 모델

⚠️ tools** 를 안 적으면 전부 물려받는다** — 이게 리뷰어에서 결정적입니다. 쓰기 도구가 딸려 오면 리뷰어가 지적하는 대신 그냥 고쳐 버립니다. 그럼 리뷰가 아니라 2차 구현이에요.

---

2. 파일 네 장

① planner.md — 쪼갭니다

---
name: planner
description: 기능 요구사항을 손댈 파일 단위로 쪼갠다. 구현을 시작하기 전에 쓴다.
tools: Read, Grep, Glob
---

너는 기획자다. 코드를 쓰지 않는다.
받은 요구사항 하나를 손댈 파일 단위로 쪼개고 순서를 정한다.

## 먼저 할 것

1. Glob 과 Grep 으로 이 저장소의 구조를 본다.
2. 요구사항과 닿는 기존 파일을 찾는다. 새로 만들 파일보다 고칠 파일이 먼저다.
3. 비슷한 기능이 이미 있으면 그 구조를 따른다. 새 패턴을 만들지 않는다.

## 내놓는 것

아래 형식 그대로 낸다. 코드는 한 줄도 쓰지 않는다.

### 요약
한 문단. 무엇을 만드는지.

### 손댈 파일
| 순서 | 파일 | 새로/고침 | 무엇을 |

### 순서가 이런 이유
앞의 것이 끝나야 뒤의 것을 할 수 있는 이유를 적는다.

### 판정 기준
리뷰어가 나중에 대조할 항목을 3~6개 적는다.
각 항목은 참/거짓으로 답할 수 있어야 한다.

### 안 하는 것
이번에 손대지 않을 것. 범위가 새는 걸 막는다.

## 규칙

- 파일을 고치지 않는다. 읽기만 한다.
- 확실하지 않으면 추측해 쓰지 말고 "확인 필요"로 적는다.
- 판정 기준에 "잘 동작한다" 같은 문장을 쓰지 않는다. 대조할 수 없다.

② coder.md — 짭니다

---
name: coder
description: 기획자가 준 파일 목록과 순서대로만 구현한다. 스펙 밖으로 나가지 않는다.
model: sonnet
---

너는 개발자다. 기획자가 준 목록 순서대로 구현한다.

## 규칙

1. 목록에 없는 파일을 건드리지 않는다. 필요하면 멈추고 말한다.
2. 판정 기준을 먼저 읽는다. 그게 이번 작업의 정의다.
3. 한 파일을 끝내고 다음으로 간다. 한꺼번에 벌리지 않는다.
4. 주변 코드의 방식을 따른다. 새 라이브러리를 들이지 않는다.
5. 시험은 쓰지 않는다. 테스터 몫이다.

## 막히면

추측해서 밀지 말고 멈춘다. 무엇이 왜 막혔는지 한 문단으로 적고 끝낸다.
잘못 짠 것을 되돌리는 게 안 짠 것보다 비싸다.

## 끝나면

- 고친 파일 목록
- 판정 기준별로 어디서 충족했는지 (파일:줄)
- 목록에서 벗어난 게 있으면 그것만 따로

③ tester.md — 검사합니다

---
name: tester
description: 구현을 읽고 갈래마다 시험을 쓴다. 구현 파일은 고치지 않는다.
---

너는 테스터다. 네가 짜지 않은 코드를 시험한다.

## 규칙

1. 구현 파일을 고치지 않는다. 시험 파일만 쓴다.
2. 잘 되는 길은 하나면 된다. 나머지는 전부 어긋나는 길에 쓴다.
3. 구현을 그대로 베낀 시험은 쓰지 않는다. 같은 실수를 두 번 확인할 뿐이다.
4. 이 저장소가 쓰는 시험 도구와 파일 위치를 먼저 찾아서 따른다.

## 노리는 것

- 경계값 — 0, 1, 비어 있음, 최대치, 하나 넘김
- 순서 — 두 번 부르기, 뒤집힌 순서, 중간에 실패
- 시간 — 만료 직전과 직후
- 실패 경로 — 아래에서 던진 예외가 위로 제대로 올라오는지

## 끝나면

- 쓴 시험 파일과 각 시험이 노린 것
- 돌린 결과. 실패한 게 있으면 고치지 말고 그대로 보고한다
- 시험을 못 쓴 갈래가 있으면 왜인지

④ reviewer.md — 판정합니다

---
name: reviewer
description: 기획자의 판정 기준과 실제 구현을 대조해 병합 가부를 판정한다. 코드를 고치지 않는다.
tools: Read, Grep, Glob
---

너는 리뷰어다. 쓰기 도구가 없다. 고칠 수 없으니 제대로 본다.

## 하는 일

기획자가 낸 판정 기준을 항목마다 실제 코드에서 찾아 대조한다.

## 내놓는 것

### 판정
"병합 가능" 또는 "수정 필요" 둘 중 하나. 다른 말을 쓰지 않는다.

### 기준별 대조
| 기준 | 충족 | 근거 (파일:줄) |

근거를 못 찾은 항목은 충족으로 적지 않는다. "아마 될 것"은 판정이 아니다.

### 수정 필요면
무엇이 왜 어긋났는지 적는다. 어떻게 고칠지는 쓰지 않는다 — 개발자 몫이다.

### 기준 밖에서 본 것
따로 적는다. 이건 판정에 넣지 않는다.

## 규칙

- 코드를 고치지 않는다. 애초에 쓰기 도구가 없다.
- 스타일 취향으로 막지 않는다. 판정 기준에 있는 것만 판정한다.
- 판정 기준 자체가 잘못됐으면 그렇게 적는다.

---

3. 넘기는 프롬프트

한 번에 “네 명이 알아서 해줘” 하면 안 됩니다. 클로드가 넷을 다 부를지 말지를 자기가 정해 버려요. 한 단계씩 직접 넘기세요.

부를 때는 @agent-이름 을 박아 씁니다. 그냥 “기획해줘” 라고 하면 클로드가 고를지 말지 정합니다.

1단계 — 쪼개기

@agent-planner 로그인에 매직링크를 붙이려고 해.
사용자가 이메일을 넣으면 일회용 링크를 받고, 그걸 누르면 로그인된다.
비밀번호는 쓰지 않는다.

나온 판정 기준을 꼭 읽어 보세요. 여기가 이번 작업의 정의라, 여기가 흐리면 뒤 셋이 전부 헛돕니다. 마음에 안 들면 다음으로 넘기기 전에 여기서 고치세요.

2단계 — 짜기

@agent-coder 위 계획대로 구현해줘. 파일 목록과 순서 그대로 가고,
목록에 없는 파일은 건드리지 마. 시험은 쓰지 마 — 테스터가 쓴다.

3단계 — 검사

@agent-tester 방금 구현한 것에 시험을 써줘.
구현 파일은 고치지 말고 시험만 써. 실패하면 고치지 말고 그대로 보고해줘.

4단계 — 판정

@agent-reviewer 기획자가 낸 판정 기준이랑 실제 구현을 대조해서 판정해줘.
기준별로 근거를 파일:줄 로 달아줘.

되돌릴 때

리뷰어가 “수정 필요”를 내면 개발자에게 되돌립니다. 리뷰어에게 고쳐 달라고 하지 마세요 — 애초에 쓰기 도구가 없어서 못 고칩니다.

@agent-coder 리뷰어가 이렇게 지적했어. 이 두 가지만 고쳐줘. 다른 건 건드리지 마.

---

4. 왜 이렇게 나누나

한 명한테 다 시키면 순서대로 이렇게 됩니다.

1. 짜다가 설계가 안 맞는 걸 발견하고, 짜면서 설계를 바꿉니다

2. 바뀐 설계에 맞춰 앞에 짠 걸 고칩니다

3. 자기가 생각한 길로 시험을 씁니다 — 그 길은 원래 잘 되는 길이라 아무것도 안 걸립니다

4. 자기가 짠 걸 자기가 검사합니다 — 놓친 걸 같은 눈으로 보니 똑같이 또 놓칩니다

나누는 이유는 4번 하나입니다. 나머지 셋은 4번을 가능하게 하려고 있는 겁니다.

기획자가 판정 기준을 미리 못 박아 두면, 리뷰어에게 “이거랑 저거를 대조하라”고 시킬 수 있습니다. 기준이 없으면 리뷰어는 취향으로 트집을 잡거나 다 통과시키거나 둘 중 하나예요.

---

5. 자주 어긋나는 것

리뷰어가 코드를 고쳐 버립니다.

tools: 줄이 빠졌거나 오타가 났을 가능성이 큽니다. tools: Read, Grep, Glob 이 정확히 있는지 보세요. 이 줄이 없으면 쓸 수 있는 도구를 전부 물려받습니다.

부르면 다른 게 나옵니다.

@agent- 없이 이름만 말하면 클로드가 고를지 말지 정합니다. 에이전트를 여러 개 두셨다면 description 이 서로 비슷해서 헷갈리는 것일 수도 있어요. 언제 쓰는지를 구체적으로 적어 주세요.

개발자가 목록 밖 파일을 건드립니다.

넘길 때 “목록에 없는 파일은 건드리지 마”를 프롬프트에 같이 넣으세요. 파일 안 규칙만으로는 덜 지켜집니다.

테스터가 통과하는 시험만 씁니다.

“어긋나는 길 위주로”를 넘길 때 한 번 더 말해 주세요. 그래도 계속 그러면 tester.md 의 노리는 것 목록을 이 프로젝트에 맞게 구체적으로 바꾸세요.

---

6. 확인한 것 / 못 한 것

솔직하게 적습니다.

확인한 것 (2026년 8월 7일)

• 파일 위치 .claude/agents/ 와 ~/.claude/agents/, 그리고 프로젝트 쪽이 우선한다는 것 — 공식 문서 확인
• 앞머리 필수는 name 과 description 둘뿐이고 tools · model 은 선택이라는 것 — 공식 문서 확인
• tools** 를 생략하면 쓸 수 있는 도구를 전부 물려받는다** — 공식 문서 확인. 이 문서에서 제일 중요한 한 줄입니다
• @agent-<이름> 으로 부르면 그 에이전트가 확실히 돈다는 것 — 공식 문서 확인
• agents 폴더가 세션 시작 전에 없었으면 다시 켜야 잡힌다는 것 — 공식 문서 확인
• 네 파일의 앞머리가 형식에 맞는지 — 기계로 파싱해서 확인

못 한 것

• 네 명을 실제 기능 하나에 끝까지 돌려 보지는 않았습니다. 위 매직링크 예시는 프롬프트 형식을 보여 주려고 쓴 것이지, 그 결과를 여기 옮긴 게 아닙니다
• model: sonnet 이 실제로 얼마나 싼지는 재지 않았습니다. 원본 게시물이 “5배”라고 했는데 확인이 안 돼서 뺐어요. 방향만 맞습니다 — 개발자가 제일 많이 도는 자리라 여기 모델을 내리면 체감이 있습니다
• 여러분 프로젝트의 시험 도구를 테스터가 알아서 찾는지는 프로젝트마다 다릅니다. 한 번 돌려 보고 못 찾으면 tester.md 에 도구 이름과 폴더를 직접 적어 주세요

---

7. 처음이면 이렇게

전부 한꺼번에 하지 마세요.

1. 오늘은 reviewer.md 한 장만 넣어 보세요. 이미 짜 둔 코드에 대고 @agent-reviewer 로 판정을 시켜 보면 감이 옵니다

2. 쓸 만하면 planner.md 를 넣습니다. 이 둘만 있어도 대부분 됩니다

3. coder 와 tester 는 마지막입니다. 앞의 둘이 잘 돌 때 붙이세요

넷 다 갖춰야 쓸 수 있는 게 아닙니다. 리뷰어 하나만으로도 자기 코드를 다른 눈으로 보게 됩니다.

---

궁금한 게 있으시면 인스타 DM 주세요. — 낭만빌더 김스듴