Claude Code Custom Agent 设计之旅：从以Agent为中心到以Task为中心
发布: (2026年2月1日 GMT+8 11:05)
8 min read
原文: Dev.to
Source: Dev.to
请提供您希望翻译的完整文本内容，我将按照要求保留原始链接、格式和代码块，仅翻译正文部分为简体中文。
들어가며
Design Doc 작성을 자동화하고 싶었다.
디자인 시안을 확인하고, 기획서를 읽고, 코드베이스를 파악해서 초안을 뽑아주는 것이 /design-doc Command의 목표였다.
Command는 금방 만들었지만, 그 다음 단계인 Custom Agent 설계가 문제였다. 두 번의 설계 전환과 여러 실패 끝에 현재 구조에 도달했다. 이 글은 그 여정이다.
초기 구조: 고정된 4개 Agent 병렬 호출
/design-doc 실행
↓
Main Agent가 4개 Agent 병렬 호출
├── code-researcher (코드베이스 분석)
├── doc-researcher (내부 문서 분석)
├── external-researcher (외부 도구 전부)
└── app-researcher (실제 앱 동작 확인)
↓
결과 조합 → Design Doc 초안- 구조가 단순하고 역할이 명확해 보였다.
code-researcher가 Opus 모델로 실행되면서 전체가 지연됐다. 다른 Agent들은 이미 끝났는데 하나를 기다리고 있었다.- 입력에 포함되지 않은 소스도 조사하려 했다. 필요 없는 일을 하고 있었다.
external-researcher하나가 디자인 도구, 문서 도구, 웹을 전부 처리해야 했다. 각 플랫폼의 특성이 달라 하나의 프롬프트에 다 담으려니 비대해졌다.
전환: Task 중심 설계
입력: "A 기능 개선. 디자인: ..., 기획서: ..."
↓
Main Agent가 입력 분석 → 필요한 Task 도출
↓
Research Tasks (필요한 것만):
├── design-review
├── feature-spec
└── code-module-analysis
↓
Design Task → Write Task → 완료핵심 변화
- Task가 작고 구체적
- 필요한 Task만 선택적으로 실행
- Agent는 Task 수행을 위한 도구
external-researcher도 분리했다.
external-researcher (1개)
↓ 분리
design-researcher (디자인 도구)
docs-researcher (문서 도구)
web-researcher (웹)각 소스의 특성이 다르다
| 소스 | 특징 |
|---|---|
| 디자인 도구 | 빠른 분석 vs 상세 분석 전략 필요 |
| 문서 도구 | 인증 방식, 페이지 구조 파악 방식이 다름 |
| 웹 | MCP가 아닌 기본 도구 사용 |
실패 처리 차이
- 디자인 도구 권한 없음 → 공유 설정 확인 요청
- 문서 도구 접근 불가 → 토큰 확인 요청
- 웹 타임아웃 → 다른 URL 시도
URL 패턴에 따른 자동 라우팅
| URL 패턴 | 담당 Agent |
|---|---|
| 디자인 도구 URL | design-researcher |
| 문서 도구 URL | docs-researcher |
| 그 외 | web-researcher |
새로운 문제: Agent 실패 알림
MCP 연결이 끊기거나 권한이 없을 때 Agent가 단순히 "접근할 수 없습니다." 라고 반환했다. Command는 재시도 가능한지, 포기해야 하는지 알 수 없었다. 모든 외부 연동에서 같은 문제가 발생했다.
상태 태그 도입
Agent가 결과물 최상단에 상태를 명시하도록 설계했다.
[BLOCKED:mcp-disconnected]分析对象
- URL: https://…
失败原因
MCP 连接已断开。请检查连接后重试。
状态标签定义
| 状态 | 说明 | Command 后处理 |
|---|---|---|
[SUCCESS] | 正常完成 | 进行下一步 |
[BLOCKED:reason] | 需要用户条件 | 传达给用户，等待 |
[PARTIAL] | 部分完成 | 利用结果，标明未完成 |
[FAILED:reason] | 无法恢复 | 通知用户 |
Blocked 原因代码: auth-error, permission-denied, invalid-input, mcp-disconnected
核心规则: [BLOCKED:*] 不能由 Agent 任意跳过。必须传递给调用者。
组件
Agent
- 定义输出格式
- 执行逻辑
- Quality Gate
- 返回状态
Command
- 定义工作流
- 指定 Agent 调用顺序及路径
- 结果组合
- 按状态后处理
Agent 不做的事情
- 决定存储路径（由调用者指定）
- 提及
Command概念（与调用者独立） - 决定下一步（仅返回状态）
原因：Agent 可能被 Command 调用，也可能被用户直接调用，或被其他 Agent 调用。无论调用者是谁，都应以相同方式工作。
章节定义 (6‑Section)
| 章节 | 目的 | 备注 |
|---|---|---|
| YAML Frontmatter | name, description, tools, model | description用于自动委托判断 |
| 角色定义 | 仅用一行概括核心 | |
| 输入 | 必填/可选参数 | 6‑Section中无 |
| 执行 | 分步骤流程（工具较多时包含策略） | |
| Output | 状态标签 + 结果模板（状态标签位于最上方） | |
| Quality Gate | 自检清单 | |
| 失败时 | 针对不同情况的状态码及对应措施 | 6‑Section中无 |
| 注意事项 | 防止常见错误 | 6‑Section中无 |
现有 6‑Section 与 8‑Section 对比
| 项目 | 6‑Section | 8‑Section |
|---|---|---|
| Role Definition | 角色定义 | 角色定义 |
| Expertise Areas | ❌（专业 Agent 不需要） | ❌ |
| Workflow | 执行 | 执行 |
| Communication Protocol | ❌（待改进） | ❌ |
| Output Format | Output（添加状态标签） | Output |
| Quality Checklist | Quality Gate | Quality Gate |
| 입력 | ❌ | ❌ |
| 실패 시 | ❌ | ❌ |
| 주의 사항 | ❌ | ❌ |
尚未实现的部分：Communication Protocol
현재는 상태 태그로 단방향 반환만 한다:
Command → Agent → [SUCCESS] 결과향후 구조화된 프로토콜을 추가하면 더 유연한 통신이 가능해질 것이다:
- 상태 보고에 메타 정보 추가
- Agent 간 위임 요청
学到的点
- 以任务为中心而非代理为中心：如果以代理为单位思考，角色会变得臃肿。请拆分为任务单位。
- 专业化胜于通用化：如果平台特性不同，就要分离。
- 使用状态标签进行沟通：当代理卡住时，需要通过状态告知。
- 职责分离：代理只返回状态，后处理由调用者负责。
- 输入和失败设计：虽然在 6‑Section 中没有，但对外部集成的代理来说是必需的。
- 参考社区，勿盲目相信：请根据自己的情况进行调整。