Claude Code를 깊이 있게 사용하다 보면, 대략 다음과 같은 순서로 문제에 봉착한다고 생각합니다.

CLAUDE.md가 비대해져서 무엇이 어디에 적혀 있는지 스스로도 알 수 없게 된다 - 서브 에이전트(Sub-agent)를 만들 때마다 프롬프트(Prompt)를 복사해서 붙여넣어야 하며, 규칙을 하나만 바꿔도 모든 파일을 수정해야 하는 상황이 된다

• 프로젝트가 늘어나면 어떤 것이 현재 어떤 상태인지 알 수 없게 된다

저는 현재 16개의 프로젝트를 병행하면서, 8개 직종의 에이전트(Agent)에게 역할을 나누어 운영하고 있습니다. 매일 아침 7시에 모든 프로젝트의 진척 파일로부터 '오늘의 다음 단계'를 집약하여 LINE으로 보내주는 단계까지 자동화했습니다.

그 과정에서 효과적이었던 설계만을 그대로 사용할 수 있는 템플릿으로 만들어 공개합니다.

대단한 에이전트에 대한 이야기가 아닙니다. 에이전트가 늘어나도 파탄 나지 않는 배치 규칙에 대한 이야기입니다.

① 에이전트 정의에는 지식을 쓰지 않는다

우선 이 부분이 가장 효과적이었습니다.

.claude/agents/영업.md

의 내용은 십수 줄에 불과합니다. 역할의 선언과 "작업 전에 직업/영업/CLAUDE.md를 읽어라"라는 지시뿐입니다.

---
name: 영업
description: 영업 담당. 프로젝트 탐색, 제안서 작성, 단가 판단 담당.
...

지식은 전부 직업/◯◯/CLAUDE.md 쪽에 둡니다. 저희 쪽은 직업 쪽에서만 794줄에 달합니다.

왜 나누느냐 하면, 규칙을 바꾸고 싶을 때 에이전트 정의를 건드리지 않아도 되기 때문입니다.

에이전트 정의에 지식을 직접 쓰면, 규칙을 하나 바꿀 때마다 모든 에이전트의 프롬프트를 열어야 합니다. 이것이 처음에는 "파일이 3개뿐이니 괜찮겠지"로 시작하지만, 9개 직종까지 늘어난 시점에서는 완전히 사고로 이어졌습니다.

로더(Loader)와 지식을 분리해 두면, 운영상의 튜닝이 "텍스트 파일 한 장을 수정하는 것"으로 끝납니다. 프롬프트 엔지니어링(Prompt Engineering)이라기보다, 배치 설계의 문제입니다.

② 「직업(형태)」과 「사업(실체)」을 직교시킨다

폴더를 두 축으로 나눕니다. 이곳을 섞으면 반드시 파탄 났습니다.

영업 규칙을 한 번 써두면, 사업이 아무리 늘어나도 재사용할 수 있습니다. 반대로 사업 폴더 안에 "방법"을 쓰기 시작하면, 사업이 늘어날 때마다 같은 규칙을 다시 써야 합니다.

저의 경우, 직업/이 9개, 사업/이 16개이며, CLAUDE.md는 총 19개입니다. 이 개수를 형태와 실체를 뒤섞은 채 늘려갔다면, 아마 5개 정도에서 관리를 포기했을 것입니다.

참고로 .claude/agents/의 각 에이전트는 직업/과 1대1로 대응시키고 있습니다. 이 부분이 어긋나면 어떤 파일을 읽게 해야 할지 스스로도 알 수 없게 됩니다.

③ 진척도의 「%」를 금지한다

각 사업 폴더에 STATUS.md를 한 장 두고, **그것을 진척도의 정전(正典)**으로 삼고 있습니다. 현재 11개 사업에서 작동 중입니다.

핵심은 포맷의 제약입니다.

• 진척률(%)을 사용하지 않는다
• 상태는 ✅ 완료 / 🔨 진행 중 / (공란) 미착수의 3가지 값만 사용한다
• 현재 위치를 단 한 줄만 **🔨 ← 지금 여기**로 표시한다

| | 페이즈 | 상태 |
|---|---|---|
| ① | 기획·설계 | ✅ |
...

"70% 완료"라는 말은, 쓴 본인조차 3일 뒤에는 그 의미를 복원할 수 없습니다. 무엇이 끝났고 무엇이 남았는지, 그 숫자로부터는 아무것도 알 수 없습니다.

3가지 값으로 제약하면, 진척도를 부풀리는 것이 구조적으로 불가능해집니다. 이는 AI에게 쓰게 할 때 특히 효과적입니다. 내버려 두면 AI는 보통 진척도를 부풀려 보고하기 때문입니다.

또한 은근히 중요한 것이, "파일이 정(正)이고, 대시보드는 거울이다"라고 정해두는 것입니다. Notion이나 스프레드시트 등에 동일한 정보가 있으면, 인간과 AI 모두 별도로 작성하게 되어 반드시 어긋납니다. 한쪽을 거울(동기화되는 것)로 만들면 이중 관리가 사라집니다.

비용 이야기 (이 부분은 별도 기사로 분리했습니다)

상주시키는 구성으로 하면, 비용 절감 포인트가 직관과는 전혀 다릅니다.

실측한 결과, claude -p는 1회 호출당 고정적으로 약 29,000 토큰이 쌓여 있었으며, 프롬프트를 줄여도 효과는 거의 제로였습니다. 13KB의 CLAUDE.md...

내용을 읽게 하지 않는 빈 폴더로 측정해도 $0.070 → $0.068로 거의 변하지 않았습니다.

효과가 있는 것은 실행 횟수와 모델뿐입니다. 게다가 줄이는 순서가 있습니다. 자세한 내용은 여기에 작성했습니다.

사용할 때의 주의사항

템플릿을 공개하긴 했지만, 직업은 9개나 필요하지 않습니다.

저도 갑자기 9개를 만든 것이 아니라, "같은 지시를 3번이나 썼네"라고 생각되는 시점에 분리해 나갔더니 결과적으로 이렇게 되었습니다. 우선 2~3개부터 시작하는 것이 체감상 가장 잘 작동합니다. 사용되지 않는 직업은 유지보수 비용이 될 뿐이기 때문입니다.

그리고 이것은 직접 써보며 알게 된 사실인데, 직업/◯◯/CLAUDE.md에

일반론을 적으면 즉시 효과가 없어집니다.

"친절하게 대응한다"와 같은 내용을 적어도 출력은 1mm도 변하지 않았습니다. 효과가 있었던 것은 "내가 실제로 저질렀던 실수"를 적었을 때였습니다. 저희 영업직의 경우, 단가를 확인하지 않고 착수하여 공수가 맞지 않게 된 이야기나, 템플릿 제안문을 보내서 회신율이 떨어진 이야기 등이 부끄럽지만 구체적으로 적혀 있습니다.

그 부분을 읽게 했을 때만 판단이 바뀌었습니다.

템플릿은 MIT 라이선스이므로 자유롭게 사용하세요.

만들고 있는 것의 상세 내용은 craftcodejp.com과 note에 올려두었습니다.

Discussion