跳转至

用 AI 编码智能体重建全书 — 规范先行的工作流

这一章讲什么: 如果这本书早几年写,上一章就是结尾。但 LLM(大语言模型——靠预测下一个词生成文本的 AI)已经成了 开发者工作流里的现实工具。本章做一件务实的事:把第 8–14 章建好的 整个应用用 AI 编码智能体从零重建——全部用提示词驱动。 而它的真正论点藏在流程里:AI 不是让前 14 章过时,前 14 章恰恰是你 指挥动 AI 的前提。

1. 全景:三代工具与为什么选 Claude Code

AI 辅助开发三代:代码补全(Copilot 看着你打字,补下几行——样板最适用) → 对话式编码(用自然语言描述,换回一块代码,你自己决定贴哪) → 智能体式编码(agentic coding,AI 不只给建议、而是自己操作工具的编程方式;代表工具有 Claude Code、Cursor Background Agents、Aider: 读你的项目、跑命令、建文件、执行测试、对着失败迭代——你说 「加 JWT 认证和 refresh 旋转」,它自己决定建哪些文件、装哪些包)1。

选 Claude Code 的理由同当年选 Vite:成熟、广泛采用、适合作业的形状。 四个关键能力:CLAUDE.md(项目级指令文件,跨会话持久——「给 AI 的 README」);MCP(开放标准,把外部工具/数据库/API 接进来,本章直接 连 PostgreSQL);Hooks(在 Claude 工作流的特定点自动跑的 shell 脚本—— 与 CLAUDE.md 的「建议性」不同,hooks 是确定性的(不受模型心情影响,说要跑就一定跑); 多智能体编排(multi-agent,一个大任务拆给多个 AI 分头做再汇总;大任务派生子 agent,独立上下文工作,回报摘要)2。

2. 非确定性与旧知识:本章代码不能复现

和其它章不同,这里的代码不是确定性的:同样的提示敲两遍,输出不同; 换个模型,结构风格全变;半年后模型更新,结果又漂移——这是 LLM 的根本 属性,不是 bug。提示词与其背后的推理才重要,不是具体输出3。

更要命的现实是模型的训练知识会过期(模型靠训练数据学习,数据有截止日期)。软件开发日新月异,模型可能给出 过时 API、已废弃的包、两版之前改掉的配置格式——作者亲见的实例: Prisma 7 引入了 prisma.config.ts,模型靠训练数据学习、数据有截止日期,知识偏旧的模型还在生成 Prisma 5 的写法;React Router v6→v7、OpenTelemetry 包名同样中招。 对策:每个会话开始先让模型调研所有要用的库的当前版本——几秒钟 成本,省下调版本问题的几个小时3。

3. vibe coding 的数字,与规范先行的理由

「vibe coding」(Karpathy 2025 年 2 月造词):描述想要的东西,AI 出码, 照单全收。原型和一次性脚本尚可;生产应用的数字很难看:Veracode 2025 GenAI 代码安全报告(80 个编码任务、100+ 模型)发现 AI 在 45% 的场景里 自选不安全方案;CodeRabbit 对 470 个开源 PR 的分析发现 AI 代码的 逻辑/正确性问题多 1.75 倍、安全问题多至 2.74 倍4。

vibe coding 的真正风险不是「AI 会犯错」,而是没人能认出错: 代码能跑、测试能过,但 refresh token 没做旋转、密码哈希算法偏弱、 分页在高负载下崩——写提示的人若没有评估这些决策的技术背景, 错误就无声滑过5。

规范(specification)是对症药。对比两种提示:「建一个带认证的 Express API」——几十个决策全交给 AI,错一片;而「Express 5.x、jose 签 JWT、Argon2 哈希、Prisma 枚举出 USER/ADMIN、access 15 分钟、 refresh 7 天存库且用时旋转」——AI 照样写码,但架构决策是你做的。 规范的字里行间没有「用个好点的哈希」「加个分页」这类愿望句式, 每个决策点名具体库、格式、取舍——规范与愿望清单的区别,就是 AI 产出可用代码与通用废板的区别5。

4. 工作流四件套:CLAUDE.md、MCP、Hooks、提示序列

CLAUDE.md(每次会话开始时被读):上限约 200 行的军规—— 「每行都要挣到位置:删掉它 Claude 会不会犯错?」臃肿不只是 浪费上下文,还降低遵从度。放「代码里猜不出来的东西」:确切命令、 非默认约定、已知坑;IMPORTANT: 前缀留给绝不能违反的规矩 ( sparingly )6。

MCP:.claude/settings.json 里配一个 postgres server,Claude 就能 自己查库表结构和迁移状态,不用你往聊天里贴查询结果。配置保持精干; 已有 CLI 的工具(如 gh)直接调 CLI 往往更省上下文7。

Hooks:PostToolUse 匹配 Write|Edit → 管道给 prettier—— 格式化从此不依赖模型记不记得规矩。同模式可复用:改 schema 后 prisma validate、改源码后跑受影响测试8。

提示序列:不把整份规范一次性砸过去,拆成 13 个聚焦提示, 每个做好一件事、建立在上一个的输出之上——顺序刻意镜像第 8–14 章 的章节序:构建项目的次序,指挥 AI 时和手写时同样要紧9。

5. 主线例子:13 个提示重建全书,以及 AI 的翻车现场

全书主线,一步一验收:

# 提示 对应章 要点
1 调研当前版本 — 先立版本基线,后面用它纠偏
2 脚手架 8–9 ESM/strict/tsx smoke test;--env-file 细节
3 路由与中间件 8–9 helmet/cors/日志/错误处理;中间件次序要查
4 Prisma 建模 10 最易翻车:Prisma 7 的 config.ts/适配器/global omit
5 分页/过滤/seed/TypedSQL 10 检查是否真用了 cursor 而非 skip
6–7 认证基建与路由 11 分层建,逐层审
8–9 前端与路由 12 token 放模块变量而非 localStorage,AI 放错要立刻纠正
10–12 Docker/CI/OTel 13–14 多阶段层序、healthz/readyz、--import 军规
13 全量评审 全部 跑测试+安全清单,机器问题自动修,人的决策列出来

9

翻车展(全是 Prisma 7 相关):import 路径写成 @prisma/client 而不是生成路径;migrate dev 之后不重新 generate(7 代不再 自动,import 直接解析失败);TypedSQL 忘了 generate --sql;seed 配置 写在旧式 package.json 块里——Prisma 7 只看 prisma.config.ts 的 migrations.seed,旧块被静默忽略10。另一个教学陷阱:Prompt 5 的 seed 造了 10 个没有 password 的用户,Prompt 6 给 User 加必填 password 列,迁移直接中止——开发库清表重来,seed 补上哈希, 第 3 章的 POST /users 也得改写或退役11。

安全评审检查点(全书最重要的一段警告):AI 生成的认证代码必须 逐行人审——旋转是否删旧令牌、并发是否安全(删-计数-事务, 不然 StrictMode 双跑竞态把用户踢下线)、登录错误是否统一措辞 (防枚举)、verify 是否真的验了过期、global omit 是否兜住密码。 「绝不让 AI 生成的认证代码未经彻底评审上生产。代码可能看起来对、 测试可能过,漏洞只在对抗条件下显形。这是全项目唯一「能跑」不够的 地方。」12

6. 踩坑与修法:上下文管理和纠偏纪律

前端提示常一次生成一大堆文件,跨文件不一致(store 和 client 用不同的 类型名)多半是上下文管理问题:显式指定共享类型文件; 对话变长用 /compact 压缩历史、腾上下文——「主窗口只放高信号 token」 就是所谓上下文工程13。

走偏时的纪律:Esc 中断(保留上下文)、/rewind 回滚到检查点、 两次纠偏失败就 /clear 重来——空上下文里的干净提示,几乎总能 打败塞满半成品纠正的长线程13。

7. 分工的结论:AI 干什么,人干什么

AI 擅长(模式明确、见过的例子多):样板与脚手架、模式重复 (CRUD 路由、Redux slice、测试文件)、文档与注释、机械重构与改名14。

必须留给人(设计判断,不是编码问题):安全决策(威胁建模)、 架构决策(单体还是微服务、Redux 还是 React Query——「知道该 要什么」才是难点)、业务逻辑(领域规则、监管要求的校验)、 性能取舍(cursor 还是 offset、哪些列建索引、页该多大)14。

上生产前的安全评审清单(十条):输入校验全覆盖、令牌过期正确、 旋转删旧、授权与归属检查、无字符串拼接 SQL、XSS 默认转义是否够、 CORS 白名单非 *、认证端点限流、错误不泄露内部信息、密钥全在 环境变量15。

全书最后一句的分量:「生成代码的质量,追踪的是你规范的质量, 远甚于你选的模型。把力气花在命名库、格式与取舍上,代码自然 跟上。规范花了 15 分钟,省了几小时的来回纠正,更重要的是它逼我们 在生成代码之前想清楚了决策——那个想清楚的过程,才是让你成为 更好开发者的部分。AI 只是打字更快。」16

8. 作者的判断与证据

  • 45%/1.75×/2.74× 三个数字转引自 Veracode 2025 与 CodeRabbit 报告, 是「规范先行」立论的实证支柱4。
  • 「前 14 章是驾驭 AI 的前提」是贯穿全书的元论点16。
  • 「AI 生成的认证代码必须逐行人审」是全章最强语气,与第 13、14 章的 安全口径一致12。
  • 「Claude Code 不是唯一选择;提示与策略通用,工具可换」是诚实的 去锁定声明2。

9. 边界与局限

  • 强时点性:工具(Claude Code/MCP/hooks)、模型名、各库版本都会 漂移;作者明说「推理重要,输出不重要」;
  • 绑定 Anthropic 生态(MCP 虽已成开放标准,本章演示以 Claude Code 为壳);Copilot/Cursor/Aider 只在对照表里;
  • 多智能体与 Agent SDK 只到演示/展望,没有实操;
  • 45% 等数字来自 2025 年报告,模型迭代后可能改善——引用时需注明时点。

判断(我们的,不是书里的): 本章是全书结构上最巧的一章: 它把前 14 章变成弹药库——每个「AI 翻车展」都精确对应前面 某一章的概念(Prisma 7 配置对应第 10/11 章,旋转竞态对应第 14 章, token 存储对应第 15 章)。读到这里,前 14 章的每个决策突然都有了 「没有它你会在此被 AI 坑」的实证——这是任何总结章都做不到的回收。 如果错,会错在: 「规范先行」对有经验者是正确工作流,但对 初学者可能变成新门槛——写不出好规范的人恰恰是最需要 AI 的人; 本书默认读者已读完前 14 章(能写出规范),这个隐含前提值得明说。

10. 可带走的

  1. 三代工具:补全 → 对话 → 智能体(读项目、跑命令、迭代测试)。
  2. LLM 输出非确定、知识会过期——会话开始先调研版本基线。
  3. vibe coding 的数字:45% 自选不安全方案;风险是没人能认出错。
  4. 规范先于提示词:点名库、格式、取舍;愿望句式是废板之源。
  5. CLAUDE.md ≤200 行,每行挣位置;IMPORTANT 省着用;代码里猜得出的别写。
  6. 提示序列:小步、顺序镜像手写构建次序;每步评审再走下一步。
  7. 测试是给 agent 的客观目标——能让它自己迭代到绿。
  8. 走偏两次就清上下文重来;长会话用 /compact。
  9. 分工:AI 写样板/模式/文档/机械重构;人守安全/架构/业务/性能取舍。
  10. AI 生成的认证代码逐行人审——这是全项目唯一「能跑」不够的地方。

11. 原文地图

主题 原书章 原文位置
三代工具 From autocomplete to autonomous agents text/169-fm-from-autocomplete-to-autonomous-agents.txt:5(搜「three stages」)
Claude Code 四能力 Why Claude Code? text/170-fm-why-claude-code.txt:21(搜「CLAUDE.md: A project-level」)
非确定性与旧知识 Non-determinism, model choice, and stale knowledge text/171-fm-non-determinism-model-choice-and-stale-knowledge.txt:7(搜「not deterministic」) · text/171-fm-non-determinism-model-choice-and-stale-knowledge.txt:41(搜「Prisma 5」)
45% 与 1.75× Vibe coding vs. specification-driven development text/171-fm-non-determinism-model-choice-and-stale-knowledge.txt:61(搜「45%」)
规范 vs 愿望清单 Why specification matters more than prompting tricks text/176-fm-why-specification-matters-more-than-prompting-tr.txt:35(搜「specification that says」)
CLAUDE.md 军规 Writing an effective CLAUDE.md text/173-fm-writing-an-effective-claude-md.txt:13(搜「200 lines」)
hooks 确定性 Setting up hooks for code quality text/175-fm-setting-up-hooks-for-code-quality.txt:7(搜「deterministic」)
13 提示序列 Breaking the project into prompt sequences text/178-fm-breaking-the-project-into-prompt-sequences.txt:5(搜「sequence of focused prompts」)
AI 翻车模式 When the AI gets it wrong text/187-fm-when-the-ai-gets-it-wrong.txt:5(搜「Wrong import path」)
迁移陷阱(必填列) Prompt 6: Auth infrastructure text/188-fm-prompt-6-auth-infrastructure.txt:42(搜「One ordering trap to watch for: we seede」)
认证代码逐行审 The critical review checkpoint text/190-fm-the-critical-review-checkpoint.txt:57(搜「line by line」)
token 不进 localStorage Prompt 8: Frontend scaffolding and API client text/191-fm-prompt-8-frontend-scaffolding-and-api-client.txt:21(搜「- Store access token in a module-level v」)
Docker 层序检查 Prompt 10: Containerization text/195-fm-prompt-10-containerization.txt:34(搜「layer cache」)
/compact 与纠偏 Multi-file changes and context management text/193-fm-multi-file-changes-and-context-management.txt:13(搜「Use /compact when the conversation get」) · text/180-fm-plan-mode-and-course-corrections.txt:29(搜「/clear」)
分工结论 Lessons learned: where AI shines and where it falls short text/202-fm-agent-sdk.txt:74(搜「Boilerplate and scaffolding」) · text/202-fm-agent-sdk.txt:104(搜「Security decisions」)
安全清单十条 The security review checklist text/203-fm-the-security-review-checklist.txt:3(搜「Here is a minimum」)
规范是最重要的工件 The specification is your most important artifact text/204-fm-the-specification-is-your-most-important-artifac.txt:1(搜「The specification is your most important」)

  1. 出处:「From autocomplete to autonomous agents」第 3–33 段(text/169-fm-from-autocomplete-to-autonomous-agents.txt:11,搜「code completion」;:23,搜「agentic coding」)。 ↩

  2. 出处:「Why Claude Code?」第 5–33 段(text/170-fm-why-claude-code.txt:21,搜「CLAUDE.md: A project-level」;:19,搜「MCP」;:25,搜「deterministic」)。 ↩↩

  3. 出处:「Non-determinism, model choice, and stale knowledge」第 3–31 段(text/171-fm-non-determinism-model-choice-and-stale-knowledge.txt:7,搜「not deterministic」;:17,搜「Prisma 5」;:29,搜「research the current versions」)。 ↩↩

  4. 出处:「Vibe coding vs. specification-driven development」第 3–15 段(text/171-fm-non-determinism-model-choice-and-stale-knowledge.txt:61,搜「45%」;:37,搜「1.75」)。 ↩↩

  5. 出处:「Why specification matters more than prompting tricks」第 3–41 段(text/176-fm-why-specification-matters-more-than-prompting-tr.txt:13,搜「missing dozens of decisions」;:27,搜「specification that says」;:37,搜「nobody catches them」)。 ↩↩

  6. 出处:「Writing an effective CLAUDE.md」第 5–25 段(text/173-fm-writing-an-effective-claude-md.txt:13,搜「200 lines」;:7,搜「make a mistake」;:45,搜「cannot guess」)。 ↩

  7. 出处:「Configuring MCP servers」第 3–21 段(text/174-fm-configuring-mcp-servers.txt:34,搜「Keep the configuration lean」;:19,搜「context-efficient」)。 ↩

  8. 出处:「Setting up hooks for code quality」第 3–21 段(text/175-fm-setting-up-hooks-for-code-quality.txt:7,搜「deterministic」;:17,搜「no longer depends」)。 ↩

  9. 出处:「Breaking the project into prompt sequences」第 3–33 段(text/178-fm-breaking-the-project-into-prompt-sequences.txt:5,搜「sequence of focused prompts」;:31,搜「order in which you build」)。 ↩↩

  10. 出处:「When the AI gets it wrong」第 3–29 段(text/187-fm-when-the-ai-gets-it-wrong.txt:5,搜「Wrong import path」;:11,搜「does not regenerate」;:25,搜「silently ignored」)。 ↩

  11. 出处:「Prompt 6: Auth infrastructure」第 27–43 段(text/188-fm-prompt-6-auth-infrastructure.txt:44,搜「migration aborts」;:41,搜「Argument password is missing」)。 ↩

  12. 出处:「The critical review checkpoint」第 3–51 段(text/190-fm-the-critical-review-checkpoint.txt:57,搜「line by line」;:31,搜「not sufficient」)。 ↩↩

  13. 出处:「Multi-file changes and context management」第 3–15 段与「Plan mode and course corrections」第 3–15 段(text/193-fm-multi-file-changes-and-context-management.txt:13,搜「Use /compact when the conversation get」;text/180-fm-plan-mode-and-course-corrections.txt:29,搜「/clear」;:15,搜「clean prompt」)。 ↩↩

  14. 出处:「Lessons learned: where AI shines and where it falls short」第 21–55 段(text/202-fm-agent-sdk.txt:74,搜「Boilerplate and scaffolding」;:39,搜「Security decisions」;:43,搜「Architecture decisions」)。 ↩↩

  15. 出处:「The security review checklist」第 3–31 段(text/203-fm-the-security-review-checklist.txt:3,搜「Here is a minimum」)。 ↩

  16. 出处:「The specification is your most important artifact」第 3–21 段(text/204-fm-the-specification-is-your-most-important-artifac.txt:1,搜「The specification is your most important」;:11,搜「15 minutes」;:19,搜「types faster」)。 ↩↩