Appearance
使用编码智能体的基本原则
Last updated: 2026-07-05
这些通用原则适用于编写 CLAUDE.md、Skills、Subagents——一切由编码智能体消费的内容。
写出更好的提示词
先给上下文，再下指令
你能做的最高效的一件事，就是在提示词开头提前铺垫上下文。智能体不了解你的代码库、业务逻辑，也不清楚你的团队约定。你在开头填补的信息缺口越多，输出质量就越好。
简单任务，一句话就够："在 dashboard 页面添加一个加载转圈动画。"
复杂任务，请像写一个规范的 GitHub Issue 那样组织你的提示词：
- 目标 — 这次改动要达成什么，为什么重要
- 方案 — 整体思路，以及如何拆分步骤
- 相关文件 — 涉及哪些模块、组件或配置文件
- 约束 — 哪些地方不能动，有哪些边界情况需要处理
- 验收方式 — 测试命令、期望行为或验收标准
任务越复杂，就应该写得越详细。花五分钟写提示词，可以省去一个小时的来回沟通。
指明起点
不要让智能体在你的代码库里"寻宝"。哪怕是个大概的指引，也能帮上大忙：
- "认证逻辑在
src/services/auth/里" - "先读一下
docs/v3-migration.md里的迁移指南" - "这个和
UserGroupController遵循相同的模式"
你不需要知道确切的文件名。"订单模块里的 API 路由处理器"远比什么都不说要好得多。
说清楚可能出错的地方
想想一个聪明但刚入职的人会如何误解你的需求，然后提前消除这些歧义：
- "别动那个遗留适配器——它正在被单独废弃处理"
- "测试套件需要一个运行中的 Docker 容器，先执行
make dev-up" - "这个接口是对外公开的——输入校验不容妥协"
预判潜在的失败场景，比在"理想路径"上堆砌细节更有价值。
使用前沿模型（Opus 4.6、o3 等）时： 对于成熟的固定模式，可以适当放宽要求。如果你在一个干净的代码库里要求写一个标准 CRUD 接口，模型大多数时候能正确推断出约定。把防御性提示留给真正有歧义或高风险的改动。
给智能体提供反馈闭环
智能体真正的超能力不是一次生成正确的代码——而是犯错、看到报错、自我纠正的能力。你的任务是让这个循环尽可能紧凑。
为智能体提供以下工具：
- 类型检查 — TypeScript strict 模式、Python 类型注解配合 mypy
- 测试 — 每次修改后都能运行的单元测试
- 代码检查 — ESLint、Ruff，或你项目使用的任何工具
- 运行命令 — 明确说明如何安装依赖、运行测试、启动开发服务器
有完善测试套件的编码智能体，其效果是没有测试的 5 倍。测试就是它的眼睛。
使用前沿模型时： 早期模型需要你明确说"每次修改后都要跑测试"。当前支持扩展思考和工具调用的模型会自然而然地这样做。测试仍然需要存在——你只是不用再盯着那个循环了。
可规模化的结构化工作流
一个人用智能体搞代码是一回事，在一个交付生产软件的团队里使用智能体又是另一回事。以下是高效工程团队中正在形成的工作流模式：
1. 先设计，再编码。 从技术设计文档开始——系统架构、数据流、关键权衡。由高级工程师评审。架构决策由人来做，不由 AI 决定。
2. 拆解任务，再移交执行。 设计评审通过后，将工作分解为边界清晰的小任务。每个任务应当能在一个智能体会话中完成。模糊、范围宽泛的任务只会产出模糊、冗杂的代码。
3. 先写测试，再写实现。 以 TDD 的方式使用智能体：先写测试（或让智能体写、你来审批），再让智能体写代码让测试通过。这能让智能体始终锚定在具体行为上，而不是漫无目的地发散。
4. 所有改动都要评审。 每一次变更都要经过代码评审——由人来做，可以借助 AI 辅助。然后是预发布环境，最后才是生产。智能体加速的是流水线的中间环节，而不是取消两端的护栏。
采用这种模式的团队反映，从想法到上线的周期缩短了约 30%，同时没有牺牲质量——因为严谨性（设计 → TDD → 评审 → 预发布）已经融入了流程本身，而不是事后补打的补丁。
这套 FAANG 工作流在个人层面已经有效；到了团队层面，它会从“好习惯”升级为“工程系统”。当多人同时使用多个智能体时，真正的挑战不再是单次提示词怎么写，而是如何维护共享上下文、统一工程规范、建立验证闭环。第四章会从这个问题展开：为什么团队级开发更需要工程化。
时间管理——知道何时放手
与智能体协作需要一种新的自律：知道何时停下来。
识别死局的信号
如果智能体一再无视你的纠正、反复在同一个错误上打转，或者每次回复都离目标更远——停下来。 一长串纠正对话，几乎总是意味着你遇到了根本性的问题，而不是提示词的问题。继续发消息解决不了。
低成本重启，频繁重启
用一个写得好的单次提示词开启新会话，几乎总是优于一个有 30 条纠正消息的旧会话。旧会话里积累了大量上下文污染——改了一半的代码、相互矛盾的指令、混乱的环境。重新开始不是认输，而是好的工程实践。
扬长避短
在早期多尝试不同类型的任务，找出智能体擅长和不擅长的地方。然后毫不留情地利用它的优势。如果某件事它做得很差，你自己十五分钟就能搞定，就没必要花一个小时带着它转——把智能体引导到它能发挥 10 倍效果的地方去。
使用前沿模型时： "死局"的阈值已经大幅提升。Opus 级别的模型能从更深的困境中恢复，也能跟上更长的纠正链。但原则依然成立——如果你已经来回纠正超过约 10 次，而输出却越来越差，那就重启吧。