详细版是给想看“施工细节”的读者准备的#

如果前一页的导览版负责回答“这本书大概怎么走”，这一页负责回答“为什么这样排，以及每个 Part 到底解决什么问题”。

它不是仓库底稿的生搬硬贴，而是读者可读版的施工图。

Warning

这一页同样会继续演进。

章节标题、案例重心和局部措辞后面还会继续抛光，但全书主线已经收得更清楚了。

Tip

如果只想快速判断阅读顺序，先看 《导览版》 更高效。

总纲#

这本书真正要教会读者什么#

• 这不是一本 AI 工具图鉴，也不是一堆热词的科普合集。
• 这本书真正要教会读者的，是怎么把 AI 从一个时灵时不灵的外挂，变成一套能稳定推进真实项目的工程工作流。
• 读者读完之后，应该不只会“用一个 AI IDE”，而是能理解：从旧脑回路怎么被打破，到项目怎么收敛、怎么起盘、怎么长主干、怎么接世界、怎么长期运行。
• 再往后一步，不只是个人提效，而是把 AI 用成一个可控、可复用、可治理的生产系统。

目录结构的关键原则#

• Part 1 必须保留，而且必须有意义。
  它不负责正式推进项目实现，但它负责把读者脑子掰过来。如果没有这层认知冷启动，后面的项目主线很容易又被读回“AI 帮我写代码”的老路。
• 从 Part 2 开始，整本书按项目生命周期推进。
  Part 1 先完成认知冷启动，并把主线项目亮相。Part 2 才正式从 PRD、范围、技术栈、架构、仓库和规范开始起盘。后面的长主干、接世界和自运行都顺着项目生命周期继续往下走。
• Rules、Skills、Context、Harness、MCP、Playwright、Agent Team、成本与护栏，都是贯穿能力，不是阶段性插件。
  它们不是“到了某个 Part 才突然出现”的外挂，而是从项目起盘开始一路伴随，只是在不同阶段承担的角色和重要性不一样。
• 知识点要由项目自然逼出来，但不牺牲前置认知引子。
  有些文章的职责不是推进进度，而是建立最小心智框架；有些文章的职责才是把项目往前推。这两类内容不能互相替代，但必须顺滑衔接。

贯穿全书的四条暗线#

• 认知冷启动线。
  为什么很多人觉得 AI 很笨，为什么工具不是信仰，为什么 Prompt、Context、Harness 最后会收束成控制面。
• 产品判断线。
  从 PRD、范围裁剪、验收标准，到优先级管理、版本规划、上线判断。这里会自然带出 AI Product Manager 的思路，但不会把它单独写成一本产品书。
• 控制面资产线。
  Prompt、Context、AGENTS.md、Rules、Skills、SOP、Spec、模板、命令入口，都会随着项目推进不断沉淀。重点不是“学会一个名词”，而是知道什么该沉淀、什么时候沉淀、沉淀成什么形态最值钱。
• 验证与治理线。
  调试、自洽陷阱、测试、回滚、审计、熔断、成本治理、共享记忆、Agent Team、反脆弱 Harness，都会随着项目复杂度逐步升级。它们不是最后才聊的收尾话题，而是从项目早期就不断埋下去的暗线。

项目主线怎么穿#

Part 1 先把脑回路掰过来，再把项目亮出来#

• 先回答“为什么旧工作流不够用了”。
• 再回答“为什么后面必须拿一个真实项目开刀”。

Part 2 正式拿到项目并定盘#

• 从 PRD、需求收敛、技术栈、架构、仓库和规范开始。
• 让项目进入“可以稳定推进”的状态。

Part 3 把 change 真的落下去#

• 把主线从“文档已经写了”推进到“实现真的开始长”。
• 让 Execution Graph、官方路径、分层判断、开发期 Harness 和长任务资产一起进入主干开发。

Part 4 把运行时世界接进控制面#

• 让 CLI、日志、指标、DOM、截图、宿主边界和交付闭环形成一条观察与验证链。
• 让项目从“能写代码”变成“能看见真实系统并稳定交付”。

Part 5 把这套工作流推到自运行#

• 成本、system of record、Agent Team、反脆弱 Harness 和人类 on-the-loop，会在这里被系统化。
• 目标是让这套方法能长期跑下去。

Part 1 · 破局#

目标：这一部分不正式推进项目实现，而是先建立后文所需的最小心智框架。前几篇文章承担的职责是“让后文能成立”，不是“抢着推进项目进度”。

1.1 为什么很多人觉得 AI 很笨：其实是工作流还停在补全时代#

• 从“你写 AI 补”到“你说 AI 做”，中间到底变了什么。
• AI 编程为什么不只是模型变强，而是协作方式、交互方式和开发模式一起变了。
• 这一章负责打破“问题都在模型”的旧误解。

1.2 工具不是信仰：不同产品形态到底在解决什么问题#

• Native IDE、IDE 插件、CLI、Web Agent、Spec 工具分别擅长什么，不擅长什么。
• 为什么“找本命工具”越来越不重要，真正重要的是岗位分工与场景匹配。
• 这一章负责建立“工具不是玩具箱，而是岗位体系”的意识。

1.3 从 Prompt 到 Context 再到 Agent Harness：先把控制面的轮廓看见#

• Prompt 解决任务入口，Context 解决材料分发，Harness 解决 how loop。
• 为什么只会写 Prompt 很快会撞墙，为什么 Context 多了也不等于更好。
• 这一章负责把前两篇的认知收束成控制面轮廓。

1.4 AI 时代为什么先被放大的不是代码生成能力，而是产品判断能力#

• 为什么 AI 一提速，最先暴露的反而是目标模糊、范围失控和优先级混乱。
• AI Product Manager 到底是一种什么能力，而不是一个空名词。
• 这一章负责把“项目主线应该从产品判断开始”这件事先种进读者脑子里。

1.5 把主线项目亮出来：为什么这本书要拿一个真正的大项目开刀#

• 为什么不能拿一个轻量 demo 去承载整本书。
• 主线项目为什么必须同时带着多端、自动化、控制面和治理压力。
• GraphSpec 为什么适合作为这本书的真实战场。

Part 2 · 定盘#

目标：这一部分才正式进入项目生命周期。任务不是“开始写功能”，而是先把 PRD、范围、技术栈、架构、仓库和规范定下来。

2.1 拿到 PRD 后先做什么：需求收敛、范围裁剪与验收口径#

• 怎么从“想做很多东西”收敛到“这一版到底先打哪一仗”。
• 哪些需求是真主线，哪些是未来增强项，哪些应该直接砍。
• 验收标准为什么必须前置，而不是功能写完之后再补。

2.2 技术栈怎么定：别在项目刚开始就把未来钉死#

• 为什么项目开局真正该定的，通常只有底板，而不是整套终局技术图。
• 技术栈选型应该怎么跟着真实问题往前推。
• 这一章的重点不是炫选型，而是避免一开始就把未来拍死。

2.3 仓库起盘：workspace、目录结构、环境与命令入口先搭起来#

• 从 monorepo / workspace 到 apps / packages，到底怎么拆更适合 AI 协作。
• 哪些命令必须一开始就统一，哪些脚手架和模板值得提前搭好。
• 为什么“先把命令入口和环境边界定清楚”会极大降低后面返工。

2.4 系统设计：架构、数据、接口、模块边界先立住#

• 为什么真正的 AI 协作不是边写边猜，而是先把系统骨架和契约立起来。
• 主资产、官方路径、关键边界、已定 / 待定问题要怎么先写成一页初稿。
• 这一章会把“系统设计”从文档装饰拉回实际控制面。

2.5 规范先行：Spec、Rules、Skills、SOP、模板和代码生成怎么落地#

• discussion、issue、proposal、design、specs、tasks 到底怎么一路收紧。
• 什么应该写进 AGENTS.md，什么应该变成 Rules，什么应该沉淀成 Skills 或 SOP。
• 如何让“项目规范”变成 AI 真能用的控制面，而不是人类自己感动自己的文档。

Part 3 · 长主干#

目标：这一部分直接解决主干开发里最容易失控的几类问题。

3.1 从 Change 到 Execution Graph：把 tasks.md 写成真正能跑的执行图#

• tasks.md 为什么不能继续写成线性施工清单。
• 串行阻塞项、并行切片、verifier、checkpoint、handoff artifact 应该怎么进图。
• 这一章要把“任务拆解”升级成“执行图设计”。

3.2 先收官方路径，不要先铺满功能：主资产怎么从最小闭环长出来#

• 为什么 AI 最喜欢的“顺手把副线一起铺开”，恰恰是项目最容易失控的地方。
• 当前 phase 的官方路径到底怎么判断，主资产又应该沿哪条最小闭环先长出来。
• 这一章会把“先做主线”写成真正能操作的判断框架。

3.3 事实层、证据层、投影层：别让 scanner、缓存和视图反客为主#

• 系统真正维护的事实是什么，哪些只是证据，哪些只是投影。
• scanner、cache、report、snapshot、view 最常见的越位方式是什么。
• 这一章会把“为什么项目越做越假”这件事拆到系统分层语言里。

3.4 开发期 Harness：不是护栏大全，而是让 agent 真能稳定推进#

• 为什么 guardrails 很重要，但 guardrails 不是 Harness 本体。
• 执行现场、最小 verifier、运行时观测、checkpoint、rollback、review loop 应该怎样一起进入主干开发。
• 这一章负责把 Harness 从抽象概念拉回开发现场。

3.5 长任务不断线：Progress Log、Handoff Artifact 和 Repo Memory 怎么设计#

• 为什么长任务经常不是“做不完”，而是“一断就重来”。
• progress log、handoff artifact、repo memory、context compaction 各自该落在哪里。
• 这一章要解决的是“项目怎么继续”，而不是“系统怎么多记一点”。

Part 4 · 接世界#

目标：这一部分解决的不是“还能再加哪些功能”，而是让 agent 真正看见运行时世界，并把外部系统和交付闭环一起接进来。

4.1 让 Agent 看见运行时世界：CLI、日志、指标、DOM 和截图怎么进同一条 loop#

• 为什么很多所谓 debug，本质上只是 agent 对着代码猜运行时。
• CLI 为什么不只是命令入口，而是最容易接入运行时信号的观察面。
• 这一章会把日志、指标、DOM、截图和 trace 拉进同一条观察链。

4.2 Playwright 不是测试工具，是运行时 Verifier#

• Playwright 为什么在 AI Native 工作流里应该被理解成 verifier，而不只是 E2E。
• 页面、流程、视觉回归、失败现场怎么被回放、定位和验收。
• 这一章会尽量把“看起来像对”拉回“可以机械验证”。

4.3 把外部系统和宿主边界接进 loop：数据库、第三方 API、文件系统与 IPC#

• 为什么联调阶段真正难的，是外部系统和宿主边界，而不是再多几个页面。
• 数据库状态、第三方 API 失败语义、文件系统、IPC、权限模型应该怎样进入同一条 loop。
• 这一章不是炫跨端，而是把“落地前最后一层”真正补全。

4.4 联调、验收、发布、回退：真正的交付闭环怎么收口#

• release gate 到底卡什么，approval pause 到底为什么值钱。
• incident replay、rollback、人工升级为什么必须提前设计。
• 这一章要把“最后一公里”拉回主线，而不是继续当成收尾杂项。

Part 5 · 自运行#

目标：当项目真的被做起来之后，问题会自然抬升到成本、长期记忆、Agent Team、反脆弱 Harness 和人类 on-the-loop。这里讨论的是系统怎么一直跑。

5.1 成本与吞吐治理：别只盯 token，要算整条交付链的总账#

• 为什么真正吃预算的，经常不是模型单价，而是低质量吞吐。
• 模型分层、任务分层、上下文预算、并行度和 verifier 成本要怎么一起算。
• 这一章会把“AI 太贵”重新拉回工程账本。

5.2 System of Record 与共享记忆：什么必须写回 repo，什么必须及时忘掉#

• 什么必须成为 repo 内的长期可信状态，什么只适合作为短期任务记忆。
• 为什么 append-only context 特别容易把系统拖进 semantic drift。
• 这一章会把“记住什么、忘掉什么”彻底拉回治理问题。

5.3 Agent Team：多 Agent 不是多开窗口，而是有合同、有边界、有合流点的团队#

• planner、worker、reviewer、verifier、merger 应该怎样分工。
• 共享状态、锁、合同、合流点和 merge discipline 应该怎么设计。
• 这一章不会神化 MultiAgent，而是专门回答它什么时候值钱、什么时候只是在并行复制混乱。

5.4 反脆弱 Harness：让系统因为失败变稳，而不是因为失败更乱#

• 什么叫 failure taxonomy，哪些失败必须被升级成 rule、verifier、skill 或 cleanup job。
• background cleanup、doc gardening、garbage collection 为什么不是边角活。
• 这一章真正要讲的是：成熟 Harness 的价值，不只是防错，而是会在失败之后继续收敛。

5.5 人类退到 on-the-loop：AI Product Manager、架构师和项目经理的新位置#

• 当执行越来越自动化之后，人类真正值钱的位置为什么在往上移。
• 目标定义、节奏控制、边界设计、风险升级和责任兜底会怎样重新组合。
• 这一章会给整本书一个真正的收束：人类到底该成长成什么样的控制面设计者。

最后一句话#

这本书最终要回答的，不是“哪个工具最强”，而是：

怎样让一个项目从旧脑回路被打破开始，到拿到 PRD、完成交付，再到长期运行，都能在 AI 的帮助下被稳定推进。