智能体工程——实施清单
目录
1. 配置规则文件
- 在代码库根目录创建
CLAUDE.md/AGENTS.md。从 10 行开始。 - 覆盖四个方面：
- 技术栈与版本
- 约定（目录结构、命名、你实际使 用的模式）
- 智能体绝不能打破的硬性规则（禁用的包、密钥处理、分层规范）
- 生成代码前后需遵循的工作流程
- 每次智能体做了你不希望重复的事情，就新增一条规则。
- 列出智能体可以调用的工具及其使用时机（API、脚本、数据库模式）。
- 架构决策由你自己做；让智能体来实现，而不是由它来选择。
2. 设计上下文
- 区分哪些是静态（始终加载）vs 动态（按需加载）：
- 静态：规则文件、系统指令、全局记忆
- 动态：技能、工具调用结果、检索的文档、近期对话历史
- 保持静态上下文简短且高信噪比。删掉智能体并不总需要的内容。
- 将可复用的专业知识迁移到技能（skill）中，只在任务匹配时才加载。
- 永远不要将整个代码库粘贴到提示词中。检索与当前任务相关的内容即可。
3. 构建验证机制
- 在让智能体生成功能代码之前，先写好测试。测试即规格说明。
- 针对非确定性部分编写评估（eval）：
- 智能体是否走了合理的路径？
- 它是否选择了正确的工具？
- 输出是否达到质量标准？
- 同时检查结果（能编译、测试通过）和轨迹（如何做到的）。
- 建立反馈闭环：
- 针对基准测试套件运行
- 按根本原因归类失败案例
- 修复导致失败的提示词或工具
- 重新运行回归测试套件
- 监控生产环境中出现的新失败
4. 执行工作
- 根据任务选择模式：
- 指挥官模式（实时、在 IDE 内）——适用于复杂逻辑、调试、不熟悉的代码
- 编排模式（异步、委派后审查）——适用于 Bug 修复、迁移、测试生成
- 根据任务选择智能体位置：
- 编辑器智能体——流畅编辑与建议
- 终端智能体——跨文件工作、运行并响应结果
- 后台智能体——可以描述为一段话并放手不管的任务
- 在沙盒环境中运行代码生成，仅使用已批准的工具。
- 最后 20% 由自己处理：边界情况、错误处理、集成节点、业务逻辑。"看起来没问题"的代码正是 Bug 藏匿的地方。
5. 审查与发布
- 使用智能体做第一轮审查（Bug、风格、安全、性能）。
- 审查每一行将要上线的代码：
- 对精巧的代码保持怀疑
- 确认引入的包真实存在
- 针对真实失败场景检查错误处理
- 在提交/编辑节点添加钩子（例如阻止含有硬编码密钥的提交）。
- 开启可观测性：追踪（trace）、评估结果、Token 用量/延迟/成本、行为漂移。
- 将智能体指向你一直在回避的遗留代码：重构、迁移、废弃 API 更新。
6. 控制成本
- 衡量总体拥有成本，而不仅仅是速度。
- 通过精简的规则文件提高首次成功率，避免重试循环。
- 按任务路由模型：
- 前沿模型——架构设计与高难度实现
- 廉价模型——测试生成、审查、CI 监控
- 使用动态上下文和技能，只为真正需要的 Token 付费。
7. 交付生产智能体
- 明确你在构建什么：
- 脚本——智能体就是终点
- 面向真实用户的产品——智能体需要一套基础设施
- 对于产品，添加：持久化记忆、作用域权限、CI 中的评估覆盖、完整运行追踪。
- 使用技能包，让现有的编码智能体处理构建 → 评估 → 部署 → 观测的完整流程。
- 对于多智能体场景，通过共享状态协调，工具调用使用 MCP，任务委派使用 A2A。
8. 建立团队标准
- 对规则文件、提示词、评估套件和技能进行版本管理，在 PR 中审查，指定负责人。
- 以通过评估套件（附带明确评分标准）作为发布门禁，而不是能运行的 Demo。
- 培训审查者了解生成代码的典型失败模式。
- 明确划定原型与生产的边界（哪些代码库、分支、环境）。
- 一次性构建工作套件，持续打磨完善。
- 招聘与晋升时注重判断力：规格说明能力、评估能力、架构能力。
参考资料
基于 The New SDLC With Vibe Coding（Google）： https://www.kaggle.com/whitepaper-the-new-SDLC-with-vibe-coding