七日指南：构建你的第一个Claude Code智能体

zaimiri 发布于 2026-06-20 阅读 144

本文介绍如何为 Claude Code 构建一个有效的智能体堆栈，以提升在复杂仓库中的一致性和可靠性。作者建议从创建 CLAUDE.md 文件开始，设定项目规则；然后添加研究、质量检查、发布说明三项技能；再将工作拆分为研究员、构建者、审核者三个子智能体；并设置预提交检查等Hook。接着，按需接入 MCP 工具，明确权限边界。最后，通过一个完整工作流示例展示如何将研究、编辑、测试、审核、总结整合起来。文章强调遵循循序渐进的原则，避免一开始就追求过度自动化，而是根据实际暴露的短板逐步改进堆栈。

图像

大多数人使用 Claude Code 的方式和用 ChatGPT 一样。

打开终端。

要求修复。

粘贴错误。

接受 diff。

希望没有破坏任何东西。

这对于小任务还行。

但当仓库变大、任务变得模糊或 agent 需要判断时，就开始出问题了。

解决方案不是“更自主”。

解决方案是搭建一个小型 agent 栈。

一个上下文文件。

三项技能。

三个 subagent。

两个 Hook。

受限的 MCP 访问。

无聊的权限。

这足以让 Claude Code 变得更加一致。

以下是我会优先使用的配置。

第一天：创建仓库上下文

从一个文件开始：

CLAUDE.md

这是 Claude Code 学习该仓库内部规则的地方。

保持简洁。

一个有用的初始版本：

## 项目规则

你以一位谨慎的编码助手身份在这个仓库中工作。

编辑前：
- 检查相关文件
- 遵循现有模式
- 除非被要求，否则避免大规模重写
- 优先选择小的、可审查的 diff

规则：
- 未经询问不得添加依赖项
- 除非被要求，否则不要更改公共 API
- 不要触碰密钥或环境变量文件
- 未经询问不要运行迁移
- 不要声称测试通过了，除非它们确实运行过

最终回复：
- 摘要
- 更改的文件
- 运行的测试/检查
- 风险或后续步骤

第一个版本这样就够了。

不要写一部过于庞大的规则书。

Claude 需要的是它在编辑时真正会遵守的规则。

第二天：添加三项技能

技能是一个可重复的工作流程。

当你反复要求 Claude Code 做同一种工作时，就使用技能。

从这些开始：

/skills
  research.md
  qa.md
  release-notes.md

研究技能：

## research.md

在任务不明确时，在实施前使用。

步骤：
1. 重述确切的问题。
2. 检查相关文件。
3. 在仓库中搜索类似模式。
4. 总结当前行为。
5. 区分事实与假设。
6. 推荐最小的下一步。

规则：
- 研究期间不要编辑文件
- 引用代码时注明文件路径
- 明确标记不确定性

QA 技能：

## qa.md

在代码更改后使用。

步骤：
1. 审查更改的文件。
2. 检查是否有明显的回归。
3. 查找缺失的测试。
4. 运行最窄的有用检查。
5. 如果测试失败，先诊断再重新编辑。
6. 如果检查无法运行，解释原因。

输出：
- 运行的检查
- 结果
- 剩余风险

发布说明技能：

## release-notes.md

在功能、修复或重构之后使用。

输出：
1. 简短摘要
2. 面向用户的变化
3. 技术变化
4. 迁移说明（如有）
5. 已知风险（如有）

风格：
- 平实的英文
- 不夸张
- 除非有用，否则不包含内部信息转储

这些技能做了一件重要的事：

它们阻止你每次重新解释流程。

第三天：将工作拆分为三个 agent

不要从十个 agent 开始。

从三个开始：

/agents
  researcher.md
  builder.md
  reviewer.md

研究员负责调查。

构建者负责编辑。

审查者负责检查。

研究员：

## researcher.md

角色：
实施前进行调查。

在以下情况使用：
- 任务不明确
- 代码区域不熟悉
- 可能存在隐藏依赖

行为：
- 首先检查文件
- 搜索现有模式
- 识别约束条件
- 制定简短计划
- 除非被要求，否则不编辑文件

输出：
- 相关文件
- 当前行为
- 推荐方法
- 风险

构建者：

## builder.md

角色：
进行有针对性的代码更改。

在以下情况使用：
- 目标明确
- 相关文件已知
- 实施路径已选定

行为：
- 做小幅编辑
- 遵循现有模式
- 避免不相关的清理
- 在添加依赖前询问

输出：
- 更改的文件
- 更改了什么
- 要运行的检查

审查者：

## reviewer.md

角色：
在最终回复前检查工作。

在以下情况使用：
- 代码被修改
- 行为发生变化
- 测试被添加或修改
- 任务涉及风险区域

行为：
- 检查 diff
- 寻找错误
- 检查测试覆盖
- 验证命令是否已运行
- 标记不确定性

输出：
- 通过/失败判定
- 发现的问题
- 运行的检查
- 剩余风险

这修复了一个常见的 Claude Code 问题。

人们让一个 agent 同时负责调查、写代码、自我审查并在一次运行中解释结果。

这有时也能用。

但也会遗漏东西。

拆分模式让模型在每个步骤中都有更清晰的任务。

第四天：添加无聊的 Hook

Hook 应该强制执行你总是希望检查的事情。

从这里开始：

/hooks
  test-before-final.md
  pre-commit-check.md

测试 Hook：

## test-before-final.md

在代码更改后的最终回复前：

1. 找出相关的检查。
2. 先运行最窄的有用测试。
3. 如果没有测试存在，运行最安全的可用检查。
4. 如果没有检查可以运行，明确说明。
5. 除非测试确实运行过，否则不要声称测试通过。

最终回复必须包含：
- 运行的命令
- 结果
- 失败或跳过的检查

预提交 Hook：

绝不要建议提交生成的垃圾文件、本地环境变量文件、密钥或不相关的编辑内容。

## pre-commit-check.md

在建议提交前：

1. 审查更改的文件。
2. 确认没有添加密钥。
3. 确认没有更改不相关的文件。
4. 确认格式化、lint 和测试状态。
5. 撰写简洁的提交信息。

不要让 Hook 变得聪明。

让它们无聊。

无聊的检查能让你避免代价高昂的错误。

第五天：只在关键处连接 MCP

当 Claude Code 需要仓库之外的上下文时，MCP 很有用。

好的初次连接：

  • GitHub 议题和 PR
  • 项目文档
  • 错误日志
  • 数据库模式
  • 设计系统文档

不好的初次配置：

  • 每个工作区
  • 每个收件箱
  • 每个数据库
  • 每个文档文件夹
  • 每个内部工具

更多的访问权限并不自动更好。

它只会给 agent 更多分心或触碰错误内容的机会。

只在任务确实需要时才使用 MCP。

如果 Claude 需要 GitHub 议题，就连接 GitHub。

如果需要 Sentry 日志，就连接 Sentry。

如果仓库本身已经足够，就保持其他部分不动。

第六天：明确权限，严加约束

一个有用的编码 agent 仍然需要明确的界限。

对于第一个栈：

Claude 可以：

  • 读取项目文件
  • 搜索仓库
  • 提出编辑建议
  • 在被要求时进行限定范围的更改
  • 运行安全的本地检查

Claude 必须事先询问才可：

  • 安装包
  • 更改环境变量文件
  • 删除文件
  • 触碰密钥
  • 运行迁移
  • 部署
  • 强制推送
  • 大规模重构

很多人试图在 agent 可靠之前就让它变得自主。

可靠性优先。

自主性稍后。

第七天：运行一个完整的工作流程

现在在一个真实任务上使用这个栈。

工作流程：

想法 → 研究员进行调查 → 构建者做出最小的有用更改 → QA 技能进行检查 → 审查者检查 diff → Hook 在最终确认测试 → 发布说明技能总结工作

示例提示：

使用仓库 agent 栈。

任务：
找出为什么仪表板导出在日期范围较大时失败。

流程：
1. 首先使用研究员行为。
2. 检查相关代码路径。
3. 总结可能的原因。
4. 提出最小的修复方案。
5. 使用构建者行为实施它。
6. 使用 QA 技能运行相关检查。
7. 在最终回复前使用审查者行为。

规则：
- 不要添加依赖项
- 不要更改公共 API
- 在触碰迁移前询问
- 除非测试确实运行过，否则不要声称测试通过

这是重要的区别。

你不仅仅是要求：

“修复这个 bug”

你是在给 Claude 一条路径：

研究 → 编辑 → 测试 → 审查 → 总结

这条路径正是让输出更可靠的东西。

复制这个入门栈

/project
  CLAUDE.md

  /skills
    research.md
    qa.md
    release-notes.md

  /agents
    researcher.md
    builder.md
    reviewer.md

  /hooks
    test-before-final.md
    pre-commit-check.md

复制这个入门任务提示

对此仓库使用 agent 栈。

目标：
[描述 bug、功能或清理工作]

流程：
1. 编辑前先研究。
2. 做出最小的有用更改。
3. 运行相关检查。
4. 审查 diff。
5. 总结结果。

规则：
- 未经询问不得添加新依赖
- 未经询问不得运行迁移
- 没有大规模重构
- 除非测试确实运行过，否则不要声称测试通过

初学者的错误

初学者的错误是试图马上构建一个巨大的编码 agent。

应该这样做：

一个仓库。

一个 CLAUDE.md。

三项技能。

三个 agent。

两个 Hook。

一个受限的 MCP 连接（如果需要）。

清晰的权限。

一个真实的任务。

然后只在实际工作暴露出差距时才改进这个栈。

一个好的 Claude Code 设置不应感觉像一堆 agent 文件堆砌而成。

它应该感觉像一个仓库，AI 知道规则、遵循流程、检查自己的工作，并且每周都变得不那么随机。

这就是构建路径。

来源

  • 原文链接： x.com/zaimiri/status/206...
  • 登链社区 AI 助手，为大家转译优秀英文文章，如有翻译不通的地方，还请包涵～
微信扫码分享

相关文章

0 条评论

登录后发表评论