译者：Carl Cui
这篇文章来自作者 Reza Rezvani，文章分享了一个基于 Claude Code 原生功能构建 AI Agent 的方案，完全摒弃了 LangChain 等外部框架。作者的实际经验表明，使用简单的 Markdown 文件和 YAML 配置就能构建强大的 AI 代理系统，利用 Claude Code 的内置功能。这个方法简化了开发流程，降低了维护成本，适合在生产环境中部署。
六个月前，我深陷在 LangChain 编排框架中：自定义 ReAct 循环，JSON schema 验证器和一个手工构建的记忆系统，通过三个我已经不再完全理解的 Python 脚本粘合在一起。
然后我删除了所有这些。
Claude Code：如何构建你的 agent | 使用 Gemini 生成
注意： 我使用 AI 进行研究协助。这里描述的 agent 配置、生产工作流和生产上下文来自我每天在工程和运营中运行的系统。
不是因为它没用。它其实挺有用的。但每次我想改变 agent 的行为时，我都在编辑 Python 类、重新部署容器和调试序列化错误。这个系统既强大也脆弱。
替代它的东西简单得令人尴尬：带 YAML frontmatter 的 Markdown 文件，保存在 Claude Code 已经监视的目录中。不需要框架，没有构建步骤，没有部署管道，就只是些文件而已。
现在网上广为流传的那份 How to Build AI Agents from Scratch 的 cheat sheet 并没有错。其中 10 个步骤分别是：定义角色、设计 I/O、调整行为、添加推理、构建 multi-agent 逻辑、添加记忆、输出结果、包装在 UI 中、评估和监控。这些是正确的步骤。但对于 Claude Code，每一步都有原生的解决方案，不需要依赖 LangChain、CrewAI 或 OpenAI Swarm。
这是我实际在用的框架，每一步都映射到我在生产环境运行中的 Claude Code 功能。
从零开始构建 Claude Code agent 的 10 个步骤（无需外部框架）| 使用 Gemini 生成
步骤 1：定义 agent 的角色 - 一个 Markdown 文件，而不是一个类
Cheat sheet 说“定义你的 agent 的角色和目标”。在框架领域，这意味着一个带 system prompt 的 Python 类。在 Claude Code 中，这意味着 .claude/agents/ 中带 YAML frontmatter 的 .md 文件。
---
name: security-reviewer
description: 审查代码更改以查找安全漏洞、
身份验证问题和数据泄露。在任何 PR 涉及
身份验证、支付或用户数据后使用。
model: sonnet
tools: Read, Grep, Glob, Bash
color: red
---
你是一个安全专家，审查代码以查找漏洞。
重点关注：注入缺陷、身份验证绕过、数据泄露、
不安全的配置。报告发现的问题，包括文件路径、
行号和严重程度等级。
description 字段不是 decoration。Claude 会读取它，用来判断什么时候自动把工作分配给这个 agent。使用了一周像“帮忙处理安全相关的事”这样的模糊表述后，我才意识到 description 本质上是路由逻辑。
description用来说明具体何时激活 agent。
在我的 claude-code-tresor 仓库中，每个 agent 都有一个描述，读起来像触发条件，而非任务名称。
步骤 2：设计结构化输入和输出 - 将 Skills 作为 Schema 层
Cheat sheet 推荐使用 Pydantic AI 或 LangChain Output Parsers。在 Claude Code 中，schema layer 是一个 skill：一个带 YAML frontmatter 的 SKILL.md 文件，定义了参数、上下文和预期输出格式。
---
name: pr-review
description: Structured pull request review
arguments:
- name: branch
description: 要审查的分支名称
required: true
- name: focus
description: 审查重点（安全、性能、风格）
required: false
---
审查 {{branch}} 上的 PR。
输出格式：
1. 摘要（2 句话）
2. 关键问题（blocking）
3. 建议（non-blockings）
4. 判断：批准 / 请求更改
不用解析 JSON，也不用序列化。skill 定义了输入什么以及输出什么，Claude 会遵循这个结构。我在 claude-skills 仓库中维护着 48 个 skills。效果最好的 skill 是那些输出格式规范最明确的：当你给 Claude 结构时，它就会遵循结构。
步骤 3：调整行为 - CLAUDE.md 层次结构是你的协议层
Cheat sheet 说“从基于角色的 system prompt 开始，使用 Prompt Tuning 或 Prefix Tuning”。在 Claude Code 中，行为协议就是 CLAUDE.md 文件的层次结构。理解这个文件的覆盖顺序，是区分一个有用的 agent 和一个糊涂的 agent 的关键。
组织策略（企业级） ← 最广泛
↓
项目 CLAUDE.md（提交到 Git） ← 团队约定
↓
用户 ~/.claude/CLAUDE.md ← 个人默认值
↓
.claude/rules/*.md ← 限定于文件模式
↓
MEMORY.md（自动生成） ← 学习的上下文
更具体的覆盖更广泛的，这是由每个会话的加载顺序决定的。
改变我们团队产出质量的生产模式：限定于文件路径的模块化规则。不再是有一个 200 行的 CLAUDE.md 试图覆盖所有内容，我们现在有六个专注的规则文件：
# .claude/rules/api-standards.md
---
paths:
- "src/api/**/*.ts"
---
所有 endpoints 必须包括 Zod 输入验证。
使用标准 AppError 格式处理错误响应。
速率限制配置放在 src/api/middleware/ 中。
我们的前端工程师从来不需要后端规则，我们的 API 开发人员永远不需要加载 React 组件约定。这样噪音就少了，输出效果就好。
步骤 4：添加推理和工具 - tools 字段是你的权限系统
Cheat sheet 推荐使用 LangChain 工具、OpenAI 函数调用、ReAct 框架。Claude Code 已经本地运行 ReAct 循环，你能控制的是每个 agent 可以访问哪些工具。
---
name: db-reader
description: 执行只读数据库查询
tools: Bash
hooks:
PreToolUse:
- matcher: "Bash"
hooks:
- type: command
command: "./scripts/validate-readonly-query.sh"
---
tools 字段是一个权限边界。一个有 tools: Read, Grep, Glob 的 agent 无法修改文件；一个有 tools: Bash 还有 PreToolUse 钩子验证命令的 agent 无法运行破坏性操作。
这是我学到的最昂贵的教训：给每个 agent 完全的工具访问权限是走向混乱的最快路径。我的 OpenClaw multi-agent system 运行在严格的工具隔离之下：监控 agent 获得只读访问权限，事件响应 agent 获得带约束的 Bash，规划 agent 根本没有执行工具。
最小权限原则对生产环境下 agent 是必须的。
步骤 5：构建 Multi-Agent 逻辑 - Subagents vs Agent Teams
Cheat sheet 推荐使用 CrewAI、LangGraph、OpenAI Swarm。Claude Code 有两个本地 multi-agent 模式：subagents 和 Agent Teams。它们解决不同的问题。
subagents - 在你自己的会话内运行，有自己的 context window。它们之间不能互相交流，它们会向父 agent 汇报。主要用它们来处理专注的任务，比如代码审查、代码库探索、文档生成。
Agent Teams - （实验性，需要 Opus 4.6） 是可以互相协调的独立工作会话，它们通过共享的任务板和消息传递来配合。团队成员可以直接沟通，把它们用在真正需要并行处理的工作上，比如一个 agent 在构建后端 API，另一个 agent 在构建前端。
我在运行这两个系统后得出的结论是：subagents 可以投入生产使用的，我每天都在使用它们。Agent Teams 功能强大，但还处于试验阶段，我曾遇到过 15 ~ 20 分钟后协调中断的情况。
对于生产关键工作流，我仍然使用 OpenClaw orchestration pattern，即一个协调者为执行者提供提示，而不是 Agent Teams。
关键约束：subagents 无法生成其他 subagents，这样就不会有无限递归。这是一个故意的设计选择。一旦适应了它，你就能设计出更好的 agent architectures，扁平的，而不是深层的嵌套。
步骤 6：添加记忆和长期上下文 - 三个记忆层
Cheat sheet 推荐 Zep、LangChain Memory、ChromaDB、FAISS。Claude Code 有三个内置记忆层，无需向量数据库。
自动记忆 (
~/.claude/MEMORY.md) - Claude 自己写这个文件，是专门针对某个项目的笔记，而且能在不同的会话之间持续存在。在我们的生产代码库上工作三周后，自动记忆积累了 23 行项目特定知识：包管理器、测试端口、部署脚本、PR 约定。这不是一个知识库。而是一个冷启动的消除器。agent 级记忆 - 在 agent frontmatter 中设置
memory: project或memory: user。Agent 会获得一个跨对话存在的持久目录。我的代码审查 agent 在数周的使用中积累了模式、重复出现的问题和代码库规范。
---
name: code-reviewer
description: 审查代码的质量和最佳实践
memory: project
---
当你审查代码时，用你发现的模式、
约定和重复出现的问题更新你的 agent 记忆。
- CLAUDE.md 作为机构记忆 - 共享的、版本控制的层。当有人发现了项目的怪异之处，它就会在下一次提交中从个人自动记忆提升到共享的 CLAUDE.md。
步骤 7：添加外部功能 - MCP 是你的集成层
Cheat sheet 推荐添加语音或视觉功能。在 Claude Code 中，更广泛的概念是通过 MCP 服务器实现外部功能。浏览器自动化、数据库访问、API 集成、网络搜索，所有这些都通过 MCP 接入。
claude mcp add playwright npx @playwright/mcp@latest
claude mcp add github gh copilot mcp
一旦连接上 MCP，agent 可以浏览页面、与 GitHub 交互、查询数据库，无需自定义集成代码。
我的 OpenClaw 设置通过 MCP 连接 Google Workspace、Jira 和 GitHub，这样 orchestrator agent 就能通过同一个协议访问邮件、日历、项目看板和代码仓库了。
实际约束： 每个 MCP 连接都会增加延迟和 token 开销。我在生产环境里运行了三个 MCP 服务器。我试过七个，有四个被砍掉了，因为增加的上下文消耗不值得这个功能。
步骤 8：输出内容 - Skills 和 Slash Commands 作为输出层
Cheat sheet 说将输出格式化为 Markdown、PDF 或 JSON。在 Claude Code 中，输出层是 skill（用于结构化输出）和 Slash Commands（用于触发输出）的组合。
一个 skill 定义输出格式，而 .claude/commands/ 中的斜杠命令提供触发器：
# /commands/weekly-digest.md
运行周摘要 skill。从过去 7 天的 memory/daily/ 中提取。
输出为结构化简报，包括：亮点、阻塞点、
做出的决定和未解决的问题。
我们 CEO 的早晨简报是这样运作的：输入一个斜杠命令来触发一个 skill，这个 skill 会从记忆中调取信息，格式化输出，然后通过 OpenClaw 发送到 Telegram 上。这个 CEO 什么信息也用不输入，简报就在早上 7 点到了。
步骤 9：包装在 UI 中 - 远程控制和消息传递集成
Cheat sheet 推荐使用 Gradio、Streamlit 或 FastAPI。对于 Claude Code agent，“UI” 是用户们已经熟悉使用的那个界面。
Claude Code 远程控制 - 让你在终端中启动任务并从手机监控。
OpenClaw - 将 Claude Code 桥接到 Telegram、Slack、Discord 或 WhatsApp，所以你的 agent 可以从你的团队已经使用的消息应用程序访问。
对于我们的团队，用户界面是 Telegram。每个 agent 的交互都通过 CEO 已经在使用的消息界面进行。没有新应用。不需要登录。没有学习曲线。因为没什么好学的，所以采用起来非常快。
步骤 10：评估和监控 - Hooks 是你的可观测性层
Cheat sheet 说运行 test prompts、使用日志和基准测试。在 Claude Code 中，hooks 是确定性可观测性层。
{
"hooks": {
"PostToolUse": [{
"matcher": "Write",
"hooks": [{"type": "command", "command": "npm run lint"}]
}],
"Stop": [{
"matcher": "",
"hooks": [{"type": "command", "command": "./scripts/notify-slack.sh"}]
}]
}
}
- 四种 hook 类型覆盖完整生命周期：PreToolUse （执行前验证）、PostToolUse （执行后检查）、Stop （agent 完成时） 和通知 （特定事件时警报）。
这里有个值得了解的高级模式：元裁判。这是一个 Stop hook，它会生成另一个 agent 来评估第一个 agent 的输出。一个 agent 写代码，hook 触发一个审查者 agent 给结果评分。如果评分低于阈值，hook 可以触发重试。
我还没有完全自动化这个循环，agent 评估 agent 的成本影响是真实的，但对于像安全审查这样的关键工作流，额外的验证值得这些 token。
Claude Code：agent 架构 | 使用 Gemini 生成
这个框架的不足之处
上下文窗口降级是真实的 - 每个 subagent 获得自己的 200K-token 上下文，但 multi-agent 工作流仍然消耗 4 ~ 7 倍于 single-agent 会话的 token
Agent Teams 大概能达到 15 倍的性能提升 - 模型路由能起到作用：Haiku 用于简单任务、Sonnet 用于日常工作、Opus 用于复杂推理，但成本总是会增加的
Subagent 嵌套是平面的 - Subagent 无法生成其他 Subagent。如果你的工作流需要三级委托，你需要不同的架构：要么 Agent Teams，要么像 OpenClaw 这样的外部编排器。
Agent Teams 是实验性的 - 我有过协调失败、超时问题和 team lead 失去队友进度跟踪的会话。对于生产关键工作流，我仍然使用 the orchestrator pattern（OpenClaw 协调 Claude Code）而不是原生的 Agent Teams。
没有内置可观测性 - 没有 dashboard、没有跟踪查看器、没有审计日志。Hook 给你事件级控制，但将其聚合到监控系统是你的事情。对于大规模运行 agent 的团队，这是一个真正的差距。
快速参考
快速参考 Claude Code agent | 来自 Alireza Rezvani
构件是原生的，框架是 Markdown 文件，部署是往目录里扔个文件。
这既是现代 AI 开发最优雅的地方，也可能是最可怕的地方，取决于你有多信任那些可以直接访问你系统的纯文本。
我倾向于优雅。但我也在 Tailscale 后面运行每个 agent，没有公共端口。
原文链接
How to Build Claude Code Agents from Scratch — The 10-Step Framework I Actually Use in Production