Appearance
最佳实践与反模式
知道"该怎么做"还不够，更重要的是知道"哪些坑别踩"。本章把前面所有理念收敛成可执行的实践清单与反模式对照。
一、按任务复杂度选流程（别过度工程）
不是所有任务都要上全套。核心判断：返工成本 vs 沟通成本。
| 任务类型 | 建议 |
|---|---|
| 一次性脚本 / 小改动 | 直接 Vibe Coding 即可，别开 Spec Kit |
| 中等功能、单人 | SDD 轻量规格 + TDD |
| 中大型、多人协作 | Spec Kit（治理）+ TDD + 上下文工程 |
| 存量高风险模块 | OpenSpec（变更隔离）+ TDD + Harness |
| 长时自动化研发 | 全套 + Harness Engineering |
💡 反模式之一：给一个 20 行的改动套完整的 spec→plan→tasks 流程。流程是为质量服务的，不是仪式。
二、生产 vs Demo 的关键差异
text
Demo：跑通就行、边界靠猜、没有回归保护
生产：规格锁定边界、测试形成约束、变更可审计、有验证闭环把 AI 产出从"Demo 级"提升到"生产级"，缺的从来不是模型能力，而是这四件事：清晰规格、行为约束、变更隔离、验证闭环。
三、最佳实践清单
- 意图显式化：把"最容易返工的决定"写进 spec，别让约束只活在你脑子里。
- 仓库即事实来源：规范、决策、约定都进版本库；对代理来说，仓库里没有 = 不存在。
- 测试先行：让验收标准变成 AI 必须通过的可执行约束。
- 约束 > 指令：用 lint、结构测试、类型检查"框住"代理，比反复叮嘱提示词更可靠。
- 精准上下文：按阶段喂相关文件和规格，避免整仓污染。
- 小步闭环：改一点、验一点，别攒一大堆再一次性验证。
- 人负责验收：AI 可以生成、整理、首轮验证，但方向、边界、最终判断仍归人。
四、反模式对照表
| 反模式 | 症状 | 正解 |
|---|---|---|
| 无脑 Vibe | 大项目越改越乱、改 A 坏 B | 复杂任务先 SDD |
| 厚文档 SDD | 写几十页没人看的 spec | 轻量、结构化、入库 |
| 上下文灌水 | 把整个仓库塞进去，AI 抓错重点 | 精准文件 + 压缩 + 分层 |
| 让 AI 改测试凑绿 | 测试通过但功能是空的 | 实现阶段禁止改断言 |
| 无约束自动化 | 代理能跑脚本却无闸门 | 搭 Harness：lint/test/审批闸门 |
| 一杆子审批缺失 | AI 直接改生产 / 发布 | 破坏性动作保留人工审批 |
| 把 SDD 只当"规格" | 混淆 Spec/Subagent 两种 SDD | 结合上下文判断含义 |
五、安全红线（涉及自动执行时务必前置）
⚠️ 能力越大，约束越要前置。
- 给代理的自动执行环境必须沙箱化，命令走白名单；
- 隔离凭据与生产环境，代理默认拿不到生产密钥；
- 删库、发布、改权限、发通知等破坏性动作保留人工审批闸门；
- 对 AI 生成的代码保持"安全审计"意识：SQL 拼接、动态反序列化、越权校验这些经典坑，AI 一样会踩。
六、开发者角色的迁移
把这些范式连起来看，最重要的变化不是"模型更强"，而是价值重心在迁移：
text
传统开发者：亲手写出全部代码
AI 时代开发者：定义问题 → 设计边界 → 组织上下文 → 审查结果 → 设计验证与环境软件工程门槛没有消失，只是从"手工编码"转移到了"系统设计与质量控制"。
七、本章小结
- 按复杂度选流程，别过度工程；
- 生产与 Demo 的差距 = 规格 + 约束 + 隔离 + 闭环；
- 记住三条铁律：意图显式化、约束 > 指令、人负责验收；
- 自动执行务必前置安全约束。