• Claude Code 상에 역할이 다른 서브 에이전트(Sub-agent) 11개를 만들어, 개인 개발의 모든 업무(설계·구현·검증·릴리스·비코드 리뷰)를 역할 분담하고 있다.
• 효과를 내고 있는 것은 정교한 프롬프트(Prompt)가 아니라,
  「증상 → 잘못된 직관 → 올바른 대책」의 형식으로 실패를 기록하고, 다음 위임 프롬프트에 기계적으로 섞어 넣는 메커니즘(team-lessons)
  이었다. - 이 기사에서는 설정 파일과 코드 실물을 게시한다. 단, 프로젝트 고유명사와 내부 팀명의 일부는 숨겼다(숨긴 부분은 그때마다 표기한다).

이 AI 팀 구축 자체를 프로덕트로 판매하고 있는 것은 아니다(수익 0원). 여기에 적은 운용 방식은 자신의 개인 개발(Web 도구군·note·LINE 스티커 등)을 매일 돌리기 위한 실무 플로우로서 계속 사용하고 있는 것을 그대로 공개하는 것이다.

토대는 ccteams(MIT 라이선스)라는, Claude Code용으로 미리 역할 분담이 된 서브 에이전트 세트를 한 번의 명령으로 프로젝트에 적용하는 도구이다. .claude/ 하위에 팀 정의 세트가 전개되며, 프로젝트 루트의 CLAUDE.md에서 읽어 들인다.

디렉토리 구성(실물·일부 생략):

.claude/
├── active-team.md # 실행할 때마다 읽히는 팀 운용 규칙
├── agents/ # 서브 에이전트 정의 (1개 = 1개 파일)
...

.claude/agents/*.md의 frontmatter에 name / description / tools / model을 작성하는 것만으로 에이전트 1개가 된다. 실제 6개 에이전트의 frontmatter(description과 model만 발췌):

설계 판단·구현·검증을 별도의 모델·별도의 컨텍스트를 가진 역할로 나누고 있는 것이 포인트이며, architect / qa-reviewer와 같이 「판단의 질」이 중요한 곳에는 opus를, builder / shipper와 같이 「양을 해내는」 곳에는 sonnet을 할당하고 있다.

.claude/active-team.md에 누구에게 언제 던질지에 대한 규칙과 플로우를 적고 있다. 아래는 실물에서의 발췌로, 각 항목의 후반부(판단 기준의 상세 내용)는 길기 때문에 생략했다.

## Orchestration rules
- **New or vague work** — start with **scope-planner**: one-sentence goal, done-means
criteria, minimal shippable scope, explicit deferrals. Skip if the task is already
...

트리비얼(Trivial)한 작업(파일 1개·패턴이 명확함)은 scope-planner/architect를 건너뛰어도 좋다는 예외 조건도 여기에 명시되어 있다.

모든 에이전트에 대한 위임 프롬프트의 맨 앞에, 다음 digest를 기계적으로 복사하는 운용을 하고 있다(active-team.md보다 실물 기준).

작업 방식 (협상 불가):
1. 행동하기 전에 목표를 한 문장으로 재진술하고, "완료의 기준"을 정의할 것.
2. 의견을 형성하기 전에 실제 파일을 읽을 것; 참조하는 모든 경로/함수가 이 프로젝트에 존재하는지 확인할 것.
...

"진단이나 작업을 통째로 떠넘기지 않는다", "맞는지 실행해서 확인한다", "확인된 것과 미확인된 것을 섞지 않는다"를 의뢰문의 형식으로서 매번 강제하고 있다. 이 기사 자체도 이 절차에 따라 작성했다.

.claude/skills/team-lessons/SKILL.md

에 「증상 → 잘못된 직관 → 올바른 대응책」 형식으로 실패 사례를 쌓아두고, 위임할 때마다 관련 엔트리를 인용하여 전달한다. 실제로 내가 작성한 엔트리 2개를 인용한다 (프로젝트 고유명사와 일부 수치는 숨겼다).

### 「이미 해결됨」이라고 확인하지 않고 병렬 태스크를 통째로 실행할 뻔함
- **Symptom** (2026-07-23): 계속 기록(memo)에 "대응 중"이라고 적힌 것을 그대로 믿고
builder/architect를 할당할 뻔함. scope-planner에 실제 파일과 git log를
...

### 외부 플랫폼용 결과물의 사양을 프로젝트 내 문서만으로 판정함
- **Symptom** (2026-07-08): 이미지 18장을 프로젝트 내 사양서대로 규격화하여
전부 PASS 보고 → 실제 제출처의 공식 사양(가로세로 모두 짝수 px 필수)을 충족하지 못해,
...

동일한 실패를 다른 에이전트(다른 컨텍스트)가 재현하는 것을 방지하는 것이 목적이다. 효과를 본 구체적인 사례로, CLI 도구(Codex)의 샌드박스(Sandbox) 설정을 하나 빠뜨려 이미 취득한 조사 결과가 통째로 사라진 실패 사례도 여기에 추가했다. 이후, 쓰기가 필요한 Codex 의뢰에는 반드시 샌드박스를 쓰기 가능 모드로 만드는 옵션을 붙이는 규칙을 세웠다. 한 번 파일에 적어둠으로써, 동일한 의뢰문을 복사하는 것만으로 다음부터는 재발하지 않게 된다.

서브 에이전트나 스킬을 늘려가다 보면 "만들어 놓고 존재를 잊어버려 사용하지 않는" 문제가 발생한다. 이에 대한 대처로, 세션 시작 시 자동으로 실행되는 쉘 스크립트(.claude/check-in.sh)를 작성했다. 실물을 인용한다 (내부 팀명을 포함한 한 줄만 숨겼다).

#!/usr/bin/env bash
# 세션 시작 시 "사용 가능한 자산"과 "가동 상황"을 Claude의 컨텍스트(Context)로 흘려보낸다.
# 목적: 구성한 자산을 매번 상기시켜 사용 누락을 없앤다. 본인이 매번 구두로 말하지 않아도 되게 한다.

echo "【매번 지킬 것 (지키고 있는지 스스로 확인할 것)】"
echo " 1. 비코드(non-code) 중요 성과물은 공개 전에 reviewer를 거칠 것"
echo " 2. 코드 변경은 qa-reviewer의 검증을 거치기 전까지 "완료"라고 말하지 말 것"
...

이 스크립트는 .claude/agents/*.md를 실제로 for 루프로 순회하며 서브 에이전트 목록을 구성하므로, 에이전트를 증감시켜도 문서 업데이트 누락이 발생하지 않는다.

• ccteams (MIT)를 도입하거나, .claude/agents/*.md를 수기로 작성한다. 최소한 name / description / tools / model의 4개 항목이 있으면 한 개체가 된다.
• .claude/active-team.md에 "어떤 의뢰를 어떤 에이전트에게 넘길 것인가"의 규칙과 플로우 차트(Flowchart)를 작성한다. 여기가 비어 있으면 매번 구두 지시가 필요해진다.
• .claude/skills/team-lessons/SKILL.md를 만들고, 실패가 발생할 때마다 "증상 → 잘못된 직관 → 올바른 대응책"의 3줄을 추가한다. 위임 프롬프트의 말미에 관련 엔트리를 인용하는 운용을 세트로 만든다.
• SessionStart hook에 check-in.sh 상당의 스크립트를 등록하여, 자산 목록을 매번 컨텍스트로 흘려보낸다.
• 비코드 성과물은 qa-reviewer와는 별도의 비판 역할(reviewer)을 반드시 거친다. 공개 전 리뷰를 코드와 동일하게 취급한다.

여기에 적은 절차 자체는 복사 붙여넣기로 재현할 수 있다. 실제로 시간이 걸리는 것은 설정 파일을 쓰는 것이 아니라, team-lessons

에 무엇을 적을지 파악하기까지의 시행착오——즉, 자신의 프로젝트 고유의 실패를 수십 건씩 겪으며 수집하는 과정이다.

서브 에이전트 (Sub-agent)를 늘리는 것 자체는 간단하지만, 효과가 나타나는 이유는 "프롬프트 (Prompt)가 똑똑해서"가 아니라, "실패를 매번 기록하고, 다음 의뢰문에 기계적으로 섞어 넣고 있기 때문"이었다. 11대라는 숫자는 부차적인 것이며, 핵심은 team-lessons라는 실패 로그 (Failure log)의 운용에 있다.

덧붙여, 타인의 프로젝트에 동일한 메커니즘을 도입해 주는 대행 서비스도 진행하고 있다. 처음부터 작동하는 상태로 전달할 수 있는 만큼, 위에 기술한 시행착오 과정을 압축할 수 있다는 점이 판매하는 서비스의 핵심 내용이다. 상담은 info@clartools.com 으로 문의해 주시기 바랍니다. 요구 사항이 확정되지 않았어도 괜찮습니다.

이 기사는 Zenn에도 게시되어 있습니다: https://zenn.dev/clar/articles/2fc619714ec7f1