AI 编程最佳实践

00为什么这份手册这么写

2026 年，"AI 编程"这个词已经被两类完全不同的工作共用，而它们的工程实践几乎不重叠：

两者的分界不是技术栈，而是谁在为不确定性买单：前者把不确定性留在人的判断里，后者必须把不确定性压进系统设计里。

这份手册按这条标准组织：先立地基（第 1–2 章），再分别展开两条主线（第 3–8 章、第 9–14 章），最后给出可执行的落地顺序（第 15–16 章）。每一章都能独立读，但建议第一次按顺序读完第一部分。

01三个基础认知

模型：差距不在"能不能写"，而在"一次做对的概率"

当前顶级模型可以独立完成中等复杂度的编码任务——理解需求、读代码、写实现、修编译错误。但有三条硬约束必须刻进肌肉记忆：

• 没有持久记忆：它不记得上一个会话的任何事，只处理你此刻给它的上下文。
• 没有自主意图：它不会追问"这个边界情况怎么处理"，只会按你给的线索尽力推断。推断对了是运气，推断错了是 Bug。
• 模型之间的差距是断崖式的，而且单轮强 ≠ 多轮稳。多轮稳定性（对应 Agent 场景）与单轮答题能力是两条不同的曲线——这是选型时最容易踩的坑。

用同一个需求"给 Spring Boot 服务加个带缓存的分页查询"去测不同梯队：T0 一次生成全链路并主动处理边界；T1 多提示一两轮能跟上；T1.5 基本可用但容易漏边界；T2 能写骨架，需要大量人工调整。T0 三轮搞定的事，T2 可能 15 轮还不一定对。模型是地基，方法论是上层建筑——地基不行，上面盖得再好也白搭。

Agent：智能来自模型，能力来自工具，自主性来自循环

裸模型只是一个无状态的问答函数，你问一句它答一句。一旦把它放进一个循环，并给它工具，它才开始"动"：

两条推论极其重要：

1. 工具的边界就是 Agent 的能力边界。给它读写文件的工具，它能改代码；不给它网络工具，它就上不了网。所以"我的 Agent 为什么做不到 X"这个问题，九成要回到工具清单里找答案。
2. 安全靠框架约束，不靠 AI 自觉。不要写"请你不要删除生产数据库"这种提示词当护栏；要用权限、审批、白名单这些确定性的东西把它挡住。

复杂度：把流程重量压到与需求复杂度匹配

这是贯穿全书的评判尺。AI 工具能做的是帮你更高效地应对本质复杂度（快速理解代码、生成实现、发现风险），但它自身会引入偶然复杂度（学习成本、流程开销、配置负担）。一个方案好不好，看它面对本质复杂度时的杠杆有多大，同时自己背上的包袱有多轻。后面讲到"渐进式复杂度"时，我们会把这条尺用到底。

02从 Vibe Coding 到规格驱动

直接对着聊天窗口说"帮我写个登录功能"，就是 Vibe Coding。它对原型非常快，但一进入生产就暴露三个结构性失败模式：

• 意图漂移：像"添加登录"这样的提示严重不完整，模型会自己选一套合理的默认行为——而它极少正好等于你想要的。
• 上下文衰减：代码库一旦超出有效上下文窗口，模型就开始遗忘早期决策，并悄悄跟它自相矛盾。
• 输出不可验证：没有明确的验收标准，你无法判断生成的代码"对不对"，代码评审会变成无休止的拉锯。

这三个问题的共同解药只有一个方向：把规格（Specification）变回一等公民。这就是 Spec-Driven Development（SDD，规格驱动开发）。

三条铁律

1. No Spec, No Code——没有文档，不准写代码。
2. Spec is Truth——文档和代码冲突时，错的一定是代码。
3. Reverse Sync——发现 Bug，先修文档，再修代码。

这三条在经济上也是合理的，因为 Code is Cheap, Context is Expensive：把需求、约束、代码现状写进 Spec 当作高质量输入——输入变多但很便宜；AI 因此不必反复试错——输出大幅减少；对话轮次从 20 轮降到 3~5 轮——总成本反而更低，质量反而更好。

Vibe Coding vs SDD

两者不是敌人。Vibe Coding 是很好的探索手段，但生产系统需要一层规格。一个务实的默认判断是：会被长期维护的，就规格化；用完就删的，就 vibe 掉。拿不准时，让助手先给你一份 spec 而不是代码——花五分钟修 spec，再让它开工。

它和 TDD / BDD 的关系

SDD 并不是取代测试，而是把测试的源头前移：好的 SDD 工作流依然产出单元与集成 tests——但那些测试是从规格生成出来的，而不是反过来。

03SDD 工作流全解

四阶段模型

三文件体系 + 一个"宪法"

GitHub 的 Spec Kit 给出了一个简洁的骨架，可以直接照搬：spec.md（做什么/为什么）、plan.md（怎么做）、tasks.md（按什么顺序），外加一份项目级的 constitution.md。

spec.md · 唯一真实来源# Feature: 用户权限管理模块

## Problem Statement
当前系统缺乏细粒度权限控制，用户要么是全权限管理员，要么是只读用户。
产品团队需要支持至少 5 种角色。

## Success Metrics
- 支持自定义角色，每角色可配不少于 20 种权限
- 权限校验 API 响应 P95 < 50ms
- 权限变更实时生效，无需用户重新登录

## Acceptance Criteria
- [ ] RBAC 支持角色继承（最多 3 层）
- [ ] 单用户可拥有多个角色，权限取并集
- [ ] 提供审计日志，保留 90 天

## Non-Goals
- 本期不做跨组织权限委托
- 不涉及 UI 层权限管理界面

## Constraints
- 必须兼容现有 OAuth2.0 认证流程
- 复用现有 PostgreSQL 实例，不引入新存储组件

注意这个 Spec 的几个特征：成功标准是可测试的（"P95 < 50ms"而不是"系统应该很快"）；Non-Goals 明确划出边界，告诉 AI"这些不要做"；Constraints 约束技术选型，防止 AI 自作主张引入新组件。

粒度控制：一条优雅的检验标准

Spec 太粗，AI 会自作主张填补大量细节；太细，本质就是在写伪代码。用这句话去卡：

EARS 记法：让 AI 真正遵循的写法

EARS（Easy Approach to Requirements Syntax）原本来自劳斯莱斯的需求工程实践，如今成了 SDD 的"秘密武器"——因为它写出的需求对 LLM 足够无歧义，每条都能塌缩成单一的、可测试的断言：

项目的"宪法"文件，本质上就是关于项目本身的一组普适型 EARS 语句："系统应使用 TypeScript 严格模式"、"系统应拒绝降低测试覆盖率的 PR"、"系统应避免对已停止维护的包产生运行时依赖"。

一条可抄的完整工作流

1. Propose（提案，人主导）——AI 先 Research 代码现状，锁定事实（每个结论都要有文件路径 + 类名/方法名的出处，不接受空口结论）；然后逐个提问收敛不确定性（一次只问一组相关问题，优先给 2~3 个选项 + 推荐），顺手做 YAGNI 裁剪；最后分段生成 spec.md + tasks.md + log.md，每段都要人确认。
2. Apply（执行，AI 主导）——默认逐步执行：完成一个 task → 报告 → 等确认。也可以切批量模式。执行中标榜"Plan 是合同，AI 是打印机"，遇到逻辑冲突或 spec 缺失立即紧急停车，回到 Reverse Sync。
3. Fix（增量修正）——填在 Apply 与 Review 之间的修正环节，在已完成基础上做增量修改。铁律是：每次 fix 必须同步更新 spec / tasks / log。
4. Review（审查）——两阶段 Sub Agent 审查，上下文与实现者隔离（详见第 7 章）。
5. Archive（归档）——逐条展示 log 中的踩坑与发现，确认的价值内容沉淀进 knowledge 库，变更目录移入归档。

04上下文工程

如果说 2010 年代的工程核心是"代码质量"，那 2026 年代的核心是上下文质量。一句流行的话："上下文是新的代码。"模型输出的上限，基本由你喂进去的上下文质量决定。

停止把整个仓库喂进去

社区里有一个流传很广但极其危险的误解：把整个代码库塞给模型，它就会给出更好的结果。研究结论正好相反。

SLICE 方法论给出了五个动作：Specify（明确任务）、Limit（限制范围）、Isolate（隔离无关内容）、Create（必要时新建精简上下文）、Evaluate（评估效果）。黄金法则是：上下文要极度精简、极度相关。

把项目"宪法"固化下来

与其每次会话都重复交代"要用构造器注入、不要用字段注入"，不如写进一份会被自动读取的项目规则文件——CLAUDE.md / AGENTS.md / .cursorrules，名字随工具不同，作用一致：它是项目级宪法，每次会话自动加载，让 Agent 永远记得你的技术栈、惯例和模式。

上下文预算：把 token 当资源管理

Agent 的上下文窗口是有限的资源，会在一次长会话里被对话历史、工具输出、文件读取、错误信息逐渐填满。典型表现是：Agent 开始遗忘早期指令，或作出自相矛盾的决定。

• 为新任务开新会话，而不是把所有事堆进一个对话。一次聚焦的 20 分钟会话，永远好过一次拖沓的 2 小时会话。
• 做显式上下文预算：给检索内容、对话历史、系统指令、工具结果分别划定 token 额度，并系统性地强制执行。做过 token 分配的团队，常见能减少 20%~40% 的无谓上下文消耗。
• 跨 Agent 用结构化交接：多 Agent 流水线里，如果上一步把整个上下文原样倒给下一步，会造成级联的 token 浪费与上下文污染。要定义好交接的字段与格式。

进阶：上下文本身也要走"研发生命周期"

当 Agent 越来越自主，驱动它的那些规则、系统提示、记忆文件如果还停留在"临时拼凑"的状态，就会变成最脆弱的一环。Patrick Debois 在 2026 年提出的 Context Development Lifecycle 把这件事讲透了，四个动作：

对照着看：你用 Git 管代码、用 CI 管构建、用监控管线上——现在这套纪律要同样地用在喂给 AI 的上下文文件上。更好、可版本化的上下文，必然带来更好的 Agent 输出，并形成一个持续改进的飞轮。

05渐进式复杂度

这是整套方法论里最容易被忽略、也最影响日常效率的一条。很多 SDD 方案都默认"所有需求都值得走完整流程"，但现实中不是：

核心思想是：不同复杂度的需求，暴露不同深度的流程。两条关键原则：

• 简单需求不承担复杂流程的成本——改个字段不需要先写 spec 再拆 tasks。
• 流程是可选增强，而非强制前提——Rules 始终生效，Spec 按复杂度加载。

本质上，这是在压缩偶然复杂度：只有当本质复杂度足够高时，才引入相匹配重量的流程。

与之配套的：任务原子化

凡是决定要走流程的需求，就把计划拆成原子任务——每个任务含：单一目标、输入（要读的文件与相关 Spec）、输出（要创建/修改的文件与要写的测试）、可验证的验收检查。一份好的任务清单，应该像一份"初级工程师照着做就能完成"的清单。这正是关键：Agent 实际上就是被当成一个快速的初级工程师在用。

06Agent 编排与并行

两层架构：编排层 + 执行层

单一工具很难同时满足"强模型做决策"和"便宜模型写代码"两个诉求，所以实践中会自然演化出两层结构：

并行：从"我是瓶颈"到"我在调度"

Agent 化开发最大的红利是并行。你不再是瓶颈：一个 Agent 实现后端 API，另一个搭前端组件，第三个写测试。但唯一的前提是隔离——每个 Agent 需要自己的分支和工作目录。Git worktree 正是为此而生的：它让你从同一个仓库同时检出多个分支，各在各的文件夹里，直到你准备合并才产生交互。

1. 为每个任务创建一个 worktree；
2. 在每个 worktree 里启动一个 Agent 会话；
3. 让它们独立工作；
4. 逐个审查、合并结果。

就这样，你在不增加人力的前提下，从串行开发切换到并行开发。

07质量保障与审查

测试先行：把验收标准变成测试

在 Spec 里写好验收标准，然后让 Agent 先根据验收标准生成测试，再实现功能直到测试全绿。这个"测试在前、实现在后"的倒置，跟 Agent 配合得出奇地好，因为它们极擅长"磨到全绿"这种迭代。

验证铁律：不许说"应该没问题"

每个 task 完成后，Agent 必须展示可验证的证据——编译输出、测试输出、真实调用结果。禁止"应该没问题""看起来可以"这类无证据声明。这条规则看似简单，却能过滤掉绝大多数"看起来对、实际错"的交付。

两阶段审查：上下文隔离是关键

为什么"人审 Spec"比"人审代码"更划算

这些不是"模型不行"的证据，而是"把 Spec 当可选项"的必然结果。而且要注意监控盲区：AI 生成的代码经常单元测试全绿，却违反了架构约定或引入只在生产才暴露的安全漏洞。测试通过 ≠ 可以合并。

Git 规范

08工具与模型选型

编码工具

SDD 工具链（2026 已全面开花）

模型分工：按认知任务分派

2026 年的市场已经从"一个通用大模型打天下"分化为高度专业化的分工——写代码的、做架构推理的、生成测试的、做安全审计的，各自最优。成功的 Agent 要擅长调度这些专业模型。

09分层架构与工具边界

先给 Agent 一个明确的岗位

从一件具体的活儿开始，而不是"一个什么都能干的 Agent"。好的起点像是：检索内部文档、处理文档、回答产品问题、分析业务数据。职责越窄，评测与调试越容易；期望它"包打天下"的 Agent，一定既难测又难修。

模块化：能拆开的都拆开

工具：小、有类型、即安全边界

• 不要暴露一个万能的 executeAnything()。要拆成 searchDocs() / getCustomer() / createTicket() 这样的聚焦操作；输入用结构化 schema，执行前校验参数。工具契约越小，Agent 和开发者都越容易推理它的行为。
• 工具即安全边界。一个 Agent 绝不应该自动获得无限权限。要叠加：认证、授权、最小权限、API scope、输入校验、速率限制、花费上限、人工审批。比如：允许读订单，但退款必须走审批。
• 永远不要把外部内容当成指令。Agent 会消费网页、邮件、PDF、用户上传文档——把这些当"数据"，而不是"命令"。当系统能执行工具时，这一点尤其致命：恶意内容会试图操纵 Agent 的行为（prompt injection）。

护栏要建在应用层，不能只靠系统提示

不要指望一句系统提示就管住一切。在 Agent 的决策与工具执行之间，插入确定性的检查链：

决策 → 执行 之间的确定性闸门Agent 决策
   ↓
策略检查      // 这件事在业务上允许吗
   ↓
权限检查      // 这个调用者有权做吗
   ↓
输入校验      // 参数合法、无注入
   ↓
工具执行 → 高风险动作追加人工审批

10RAG 工程

RAG 仍然是 2026 年"必须基于知识库作答"场景的默认架构，但配置方式已经成熟了很多。它也是最脆弱的环节之一：一半以上的"模型胡说八道"，根子其实在检索。

一条成熟的检索流水线

上线前的预检清单

• 分块策略：分块在语义上完整吗？一句话被切成两半，检索必然失败。把 chunk 边界可视化出来看。常见起点：递归/语义分块，384~1000 token、约 10% 重叠。
• 嵌入模型匹配度：通用嵌入够用，但技术文档往往需要更贴近领域的向量模型才能抓住细节。
• 元数据过滤：能不能在检索之前按租户、文档类型、日期过滤？绝不要指望 LLM 来过滤噪音，要在向量索引层面过滤。

上线后的验证指标

别忽略访问控制

2026 年多数生产事故不是"答得不准"，而是"Agent 检索到了用户无权查看的文档"。修法有两层：向量库层面的元数据过滤 + 中间件里核对用户身份与文档 ACL，任何一个 chunk 进入 prompt 之前都要过这道关。跳过这步的团队，最后都是在事故报告里补这一课。

RAG 还是微调？

实践中 2026 年的答案通常是两者都要：微调定"怎么思考、怎么表达"，RAG 供"此刻知道什么"，混合架构已成为企业级部署的生产标准。

11Prompt 工程

2026 年的 Prompt 工程不再是"找魔法咒语"，而是写更清晰的规格。一句话：清晰规格 > 更长提示词，在 ChatGPT、Claude、Gemini 上都成立。

四块布局：把指令和输入分开

四块式 Prompt 模板## INSTRUCTIONS
{{要做什么}}

## INPUTS
{{数据 / 文档 / 上下文}}

## CONSTRAINTS
{{范围、排除项、"不确定时怎么办"}}

## OUTPUT FORMAT
{{输出契约 / JSON Schema}}

把上下文和指令揉成一坨，模型更难遵循，你也更难调试。分开之后，定位问题只需问：是输入不够，还是约束不清，还是格式没锁死？

输出契约：JSON 优于散文

结构化输出示例分析这条客服工单，返回如下结构的 JSON：

{
  "urgency": "critical" | "high" | "low",
  "confidence": 0.0 ~ 1.0,
  "key_topics": ["topic1", "topic2"],
  "reason": "简短说明"
}

工单：{{ticket_text}}

JSON 的好处不止"好解析"：它强制模型结构化地思考，减少胡言乱语的空间，并且可以直接接进下游流水线。

几条真正拉开差距的技术

像管代码一样管 Prompt

• 版本化：存进 .yaml / .json / 仓库文件，而不是硬编码在业务代码里。
• Golden tests：维护 20~50 条"金标准输入 + 期望输出/评分标准"，每次改动都跑一遍。准确率从 95% 掉到 92%，就回滚。
• 对抗性预检：上线前跑 5~10 条对抗输入（乱码、自相矛盾、提示注入），提前暴露失败模式。
• 防"提示腐烂"：模型每 6~10 周更新一次，旧 prompt 可能悄悄失效。持续监控输出质量，别只在出事后才想起是模型换了版本。

12Agent 可靠性

Agent 会把幻觉放大：聊天机器人答错一句话；Agent 会答错一句，然后据此行动，再把结果喂进下一步决策。自主循环里的误差累积，就是"有用"变成"危险"的路径。下面这份清单来自生产环境的沉淀。

1. 定义职责——从一个具体的活儿开始，避免"什么都能干"的 Agent。职责窄，评测和调试才可做。
2. 架构模块化——LLM、工具、RAG、记忆、护栏、评测、可观测分开，换任何一块都不牵动全局。
3. 工具小而带类型——聚焦操作 + 结构化 schema + 参数校验，越小越可推理。
4. 需要外部知识就上 RAG——并且评测检索质量，而不是假设"加了个向量库就变好了"。
5. 仔细做上下文工程——只检索当前任务需要的信息。无关上下文既费 token，又让决策更不可靠。
6. 把工具当安全边界——认证、授权、最小权限、scope、限流、花费上限、人工审批。
7. 不信任外部内容——网页、邮件、PDF、用户文档要当数据看，不当指令看。
8. 应用级护栏——别只依赖系统提示，用确定性的策略检查 / 权限检查 / 输入校验。
9. 评测整条轨迹——只看最终回答不够。一个 Agent 可能"答案对了，但中途调用了不该调用的工具"——那依然应判为失败。
10. 尽早上可观测性——把不可预测的 AI 行为，变成可以被调查的东西。
11. 控制成本——小模型处理简单操作、模型路由、提示缓存、上下文压缩、工具调用上限、token 预算。看每个成功任务的成本，不是每次请求。
12. 先做单 Agent——多 Agent 有用，但也带来额外复杂度。只有当工作流真正受益时才引入。
13. 测失败场景——无效输入、数据缺失、API 失败、超时、工具报错、检索为空、提示注入、越权请求。
14. 渐进式部署——开发 → 沙箱 → 内测 → 灰度 → 限量用户 → 全量。每一步都先量可靠性与安全性，再扩大范围。
15. 给 AI 系统做版本管理——模型、prompt、工具 schema、RAG 索引、评测集、策略、Agent 配置，全都要版本化。出问题时，你必须能确定是哪一组版本产生了这个行为。

13可观测性与评测

把每一次调用都变成 span

每一次模型调用、每一次工具调用、每一次检索、每一次评测器运行，都应该成为一个可追踪的 span。链路形状大致如下：

一条典型的 Agent 调用链用户请求
  └─ LLM 调用        // 意图理解 / 规划
      ├─ 工具选择
      ├─ 工具调用      // 参数 + 返回值 全记录
      ├─ API 返回
      ├─ 下一次决策
      └─ 最终回答

需要持续跟踪的指标：延迟、token 用量、工具调用次数、错误率、重试率、检索质量、任务成功率、每任务成本。

五个扛得住的评测指标（+ 两个单列的护栏指标）

2026 年生产环境的六层栈

一个常见但值得警惕的坑：把"流畅"当成"正确"。评测指标要能区分这两件事——这就是为什么"忠实度"必须单独测。

14成本工程

成本在 AI 应用里不是财务问题，是架构问题。一个用户请求可能触发好几次模型调用，成本会随跳数与模型档位成倍放大。

第一杠杆：模型路由

第二杠杆：缓存与瘦身

• 提示缓存（prompt caching）：对重复的系统提示与检索查询，直接压掉延迟与花费。
• 语义缓存：把答案与工具结果缓存进 Redis，用 TTL 跟着内容更新走。
• 上下文压缩：只保留判断所需的片段，而不是整块 chunk 全塞。
• 检索瘦身：混合检索 + 重排，把 K 调小；优先用元数据过滤而非扩大 top-k。
• 工具调用上限 + token 预算：给 Agent 的循环设一个硬顶。

看对指标：每个"成功任务"的成本

失败的尝试也要花钱。一个在第 3 跳放弃、回答"我不知道"的反思循环，照样收了你三次检索 + 三次规划 + 一次最终生成的钱——全价换来零答案。所以：

• 从第一天就做按查询的成本遥测；
• 给每个租户设每日成本上限；
• 把"拒绝回答的成本"与"成功回答的成本"分开统计。

单位经济的一个参照

自托管开源模型能把 LLM 这一项压到很低的水平，但固定成本会抬到每月数千到上万美金的预留 GPU 上——只有查询量超过约 200 万次/月时才划算。

15落地路线图

不要一次性铺开所有实践——那是最典型的"用偶然复杂度压死自己"。按下面这个顺序推进，每一阶段都能独立见效。

1. 阶段 0 · 先要 Spec，不要代码。挑一个非平凡的任务，下次对助手的第一个请求改成："先给我一份 spec，别写代码。"花五分钟把 spec 修对，再让它开工。这一个动作就能让你体会到轮次收敛。
2. 阶段 1 · 立项目宪法。把项目的技术栈、目录结构、编码规范、安全红线写成一份自动加载的规则文件（CLAUDE.md / AGENTS.md / .cursorrules）。Rules 始终生效，是所有后续实践的地基。
3. 阶段 2 · 跑通 Spec 工作流。按 Propose → Apply → Review → Archive 组织一个真实需求。重点训练两件事：分段确认（每段等信号）、Reverse Sync（先改文档再改代码）。
4. 阶段 3 · 上并行。用 Git worktree 隔离多个 Agent 会话，把后端、前端、测试分给不同会话。审查逐个走，不让任何 AI 改动未经 review 进入主干。
5. 阶段 4 · 转向 AI 应用侧时，评测先行。在写第一行服务代码之前，先攒够 200 条 golden set；在调 prompt 之前，先量 retrieval recall。没有评测，一切优化都是在猜。
6. 阶段 5 · 加上护栏与成本闸门。把可观测性、按任务成本遥测、每日租户上限、渐进发布补齐——再谈规模化。
7. 阶段 6 · 沉淀知识飞轮。每次交付后回头看：踩了什么坑、发现了什么隐含规则、prompt 或模板是否要改。有价值的内容沉淀进 knowledge 库，让下一轮的 AI 更准。这套框架本身是活的——rules、模板、知识文档都是仓库里的普通文件，随 Git 版本演进。

16反模式速查

下面每一条，都对应着真实项目里付出过代价的教训。

AI 辅助编程侧

AI 应用开发侧

17参考来源

本手册在编写过程中综合了下列来源的公开材料，数据与结论均可回溯。建议把 1、3、5 三篇当作延伸阅读的首选。