Claude Code .claude/agents/ 설계 실무 — 19개의 에이전트를 Markdown으로 관리하는 방법

19개의 Markdown이 회사를 움직이고 있다

/root/ai-sales-company/.claude/agents/

에는 Markdown 파일이 19개 있다. 약 자동판매기 영업, 인쇄 서비스 영업, 사과 선물 기획, 경쟁사 조사, 주가 분석, 부업 수익화. 이 19개의 에이전트가 심야에 스케줄러(Scheduler)로부터 기동되어, 오늘도 어딘가에서 움직이고 있다.

파일 목록은 다음과 같다.

$ ls .claude/agents/
accea.md audit.md bvsync_intel.md ceo.md
designer.md fukugyo.md globalinfo.md kabutan.md
...

이 기사에서는 "왜 Markdown으로 에이전트를 관리하는가"와 "어떻게 작성해야 정밀도가 올라가는가"를 실제 코드를 인용하여 설명한다.

에이전트 MD의 구조

각 파일의 선두는 YAML frontmatter이다.

---
name: yakujihan
description: 약 자동판매기(OTC 의약품 IoT 판매기·스마트메즈 24)의 영업 에이전트. 약국·드럭스토어·호텔·역·상업 시설 대상의 리드 획득, 제안서 작성, 메일 문구 작성, 텔레마케팅(Tele-appointment) 스크립트, 팔로업 관리, Gmail 로그 확인, 약국 접근 전략 수립 등. "약 자판기", "OTC", "브이싱크", "스마트메즈", "약국 영업", "호텔 설치", "설치 장소"에 관한 작업은 이 에이전트에게 의뢰한다.
...

frontmatter 직후에 @로 시작하는 행이 이어진다.

@/root/ai-sales-company/output/yakujihan/HANDOFF.md
@/root/ai-sales-company/output/yakujihan/lessons_learned.md
@/root/ai-sales-company/memory/company_lessons.md

이 @ 참조가 핵심이다. 에이전트가 기동될 때마다 지정한 파일의 내용이 시스템 프롬프트(System Prompt)에 자동으로 삽입된다. HANDOFF.md에는 "이전의 진행 상황"이, lessons_learned.md에는 "과거의 실패 사례"가 들어있다. 세션을 넘겨도 컨텍스트(Context)가 계승되는 이유가 바로 이것이다.

description 작성 방식에 따라 정밀도가 달라진다

Claude Code는 여러 에이전트가 등록되어 있을 때, description을 읽고 어떤 에이전트를 기동할지 판단한다. 따라서 description은 "무엇을 할 수 있는가"보다 "어떤 단어로 불리는가"를 중심으로 작성해야 한다.

NG:

약 자동판매기 영업 담당 에이전트

OK:

약 자동판매기(OTC 의약품 IoT 판매기·스마트메즈 24)의 영업 에이전트.
약국·드럭스토어·호텔·역·상업 시설 대상의 리드 획득, 제안서 작성,
메일 문구 작성, 텔레마케팅 스크립트, 팔로업 관리, Gmail 로그 확인, 약국 접근 전략 수립 등.
...

차이점은 두 가지가 있다. 첫 번째는 고유명사를 열거하고 있다는 점이다. "스마트메즈 24", "브이싱크"와 같은 정식 명칭과 약칭을 모두 적는다. 사용자가 생략된 표현으로 불렀을 때도 올바르게 라우팅(Routing)된다.

두 번째는 호출 패턴을 말미에 명시하고 있다는 점이다. "〇〇에 관한 작업은 이 에이전트에게 의뢰한다"라는 문구가 Claude의 에이전트 선택 로직에 직접적으로 작용한다.

HANDOFF.md 설계 패턴

에이전트의 기억은 HANDOFF.md에 집약한다. 포맷 예시:

# 약 자판기 영업 에이전트 HANDOFF
최종 업데이트: 2026-06-27
## 진행 중인 태스크
...

세 가지 점을 철저히 지키고 있다. 최종 업데이트일을 서두에 넣을 것(오래된 정보를 믿을 리스크를 방지), 완료된 사항을 남겨둘 것(다음 세션에서 중복 작업을 방지), 금지 사항을 전용 섹션으로 관리할 것(같은 실수가 반복되기 쉽기 때문).

금지 사항은 본문 중에 묻어두는 것보다 독립된 섹션으로 만드는 것이 확실하게 기능한다. 실제로 yakujihan.md의 본문 서두에 "⚠️ 반드시 지켜야 할 금지 사항" 섹션을 마련한 이후로, 리스트 혼입 실수가 멈췄다.

session_end.js가 자동으로 git push한다

에이전트가 업무를 마쳤을 때, HANDOFF.md가 수중에 있는 파일로 남아있다면 의미가 없다. 다음 날 기동 시 오래된 상태를 읽기 때문이다.

.claude/hooks/session_end.js

가 이 문제를 해결한다. 세션 종료 시 자동으로 실행되며, 변경 사항이 있을 때만 git commit & push를 수행한다.

// session_end.js (발췌)
const diff = execSync('git diff --name-only HEAD', { cwd: REPO }).toString().trim();
const hasHandoff = diff.split('\n').some(f => f.includes('HANDOFF') || f.includes('output/'));
...

끝부분의 process.exit(0)

는 필수다. 생략하면 Claude Code의 UI가 프리즈(freeze)되어 터미널 자체가 멈춰버린다. 한 번 겪어봤다.

실패를 통해 배운 점

에이전트를 20명 이상으로 늘렸더니, 누구에게 부탁해야 할지 알 수 없게 되었다.

description이 중복되면 Claude가 혼란을 겪는다. "약국"이라는 키워드로 yakujihan과 bvsync_intel(경쟁 조사)이 모두 검색되어, 영광스러운 업무가 잘못된 에이전트(wrong agent)에게 흘러갔다.

해결책은 간단했다. description 끝에 "〇〇에 관한 작업은 이 에이전트에게 의뢰한다"라는 문장을 각 MD 파일에 명시하여, 충돌하는 키워드를 정리했다.

HANDOFF.md가 2000행을 넘었을 때도 막막해졌다.

컨텍스트 윈도우(Context Window)를 압박하여, 정작 중요한 업무 지시가 끝으로 밀려난다. 대책은 월 단위의 "증류(distillation)"다. 완료된 태스크를 삭제하고 요점만 남긴다. 이를 소홀히 하면 점진적으로 정밀도가 떨어진다.

이 시스템의 전체 구현을 공개하고 있는 책

.claude/agents/

의 설계, HANDOFF.md 설계 패턴, hooks 구현, 스케줄러와의 연동을 통째로 해설한 Zenn의 유료 서적이 있다.

¥4,980. 가상의 샘플이 아니라, 현재 작동 중인 시스템의 실제 코드와 설정 파일을 그대로 실었다.

Discussion