文档优先开发方法论
📖 技能介绍
name: 文档优先开发方法论 slug: stream-coding version: 1.0.0 displayName: 文档优先开发方法论 description: > 文档优先开发方法论专用技能，帮助AI Agent高效完成相关任务。 summary: "文档优先开发方法论专用技能，帮助AI Agent高效完成相关任务。" license: MIT category: 开发者工具 framework: - Claude Code - Codex - Hermes Agent - OpenClaw - QClaw - WorkBuddy platform: multi-platform homepage: "https://github.com/1991513ccie-png" repository: "https://github.com/1991513ccie-png"
Stream Coding v3.5 — 文档优先的开发方法论
概述
核心真相：
混乱文档 → 模糊规范 → AI 猜测 → 反复返工 → 2-3倍速度
清晰文档 → 清晰规范 → AI 执行 → 最少返工 → 10-20倍速度
"如果你的文档足够好，AI 自己会写代码。真正的工作就是文档。代码只是打印输出。"
为什么大多数"AI 辅助开发"失败： 人们给 AI 喂混乱的文档 → AI 基于假设生成代码 → 代码不符合意图 → 无尽的修改循环 → 结果只是比手写快一点点。
适用场景
| 用户说的 | 响应 |
|---|---|
| "构建 [功能]" | 完整方法论（阶段1-4） |
| "创建 [组件]" | 完整方法论 |
| "实现 [系统]" | 检查：是否有清晰文档？ |
| "文档化 [项目]" | 仅阶段1-2 |
| "规范 [功能]" | 仅阶段1-2 |
| "清理 [X] 的文档" | 仅文档审计 |
使用方法
四阶段方法论
| 阶段 | 时间占比 | 重点 |
|---|---|---|
| 阶段1：战略思考 | 40% | 构建什么、为什么重要 |
| 阶段2：AI 就绪文档 | 40% | 怎么构建（规范清晰到 AI 零决策） |
| 阶段2.5：对抗性审查 | 5% | 用敌对评审人压力测试规范 |
| 阶段3：执行 | 10% | 代码生成 + 实现 |
| 阶段4：质量与迭代 | 5% | 测试、优化、防止偏差 |
阶段1：战略思考（40%）
7个问题框架——在写任何新文档之前，用具体性回答这些问题：
- 你到底在解决什么问题？ → 拒绝"帮助用户管理任务"，要求"帮助[具体用户]在[具体场景]中实现[可衡量结果]"
- 成功指标是什么？ → 拒绝"用户节省时间"，要求具体数字+时间线
- 为什么你能赢？ → 拒绝"更好的UI"，要求结构性优势
- 核心架构决策是什么？ → 拒绝"让AI决定"，要求基于明确权衡分析的人工决策
- 技术栈理由是什么？ → 拒绝"我喜欢"，要求业务理由
- MVP 功能是什么？ → 拒绝10+个"必须"功能，要求3-5个真正核心的
- 你不构建什么？ → 拒绝"看用户需求"，要求明确排除项和理由
阶段2：AI 就绪文档（40%）
文档类型架构：
| 类型 | 职责 | 示例 |
|---|---|---|
| 战略型 | 做什么和为什么 | 总蓝图、PRD、愿景文档 |
| 实现型 | 怎么做 | 技术规范、API文档、模块规范 |
| 参考型 | 查阅 | Schema 参考、术语表、配置 |
实现文档必须包含的4个章节：
- 反模式章节——AI 需要知道什么不要做（至少5个反模式）
- 测试用例规范——AI 需要具体的验证标准（至少5个单元测试、3个集成测试）
- 错误处理矩阵——AI 需要知道如何处理每种失败模式
- 深度链接——AI 需要导航到精确位置，永远不用模糊引用
⚠️ Spec Gate（13项检查）——永远不要跳过
这是 Stream Coding 和 vibe coding 的根本区别。7/10 的规范会生成7/10 的代码，然后需要30%的返工。
基础检查（7项）：可操作、最新、单一来源、是决策非愿望、AI 可直接使用、无未来态、无废话
文档架构检查（6项）：类型已识别、反模式位置正确、测试用例位置正确、错误处理位置正确、有深度链接、无重复
执行标准：全部通过 + AI 可理解性评分 ≥ 9/10
阶段2.5：对抗性审查（5%）
Spec Gate 通过（9+/10）后、代码生成前执行。
原则：撰写你规范的 AI 有和你一样的盲点。不同的模型——或被指示攻击的人类评审——能找到你看不到的问题。
流程： 1. 提交规范给不同的 AI 模型（Gemini、GPT、Perplexity）或可信人类评审 2. 使用对抗性提示词模板查找：逻辑矛盾、可信度风险、隐式自由度、缺失考量、防御性缺口 3. 分类发现：CRITICAL / HIGH / MEDIUM / LOW 4. 修复所有 CRITICAL 问题 → 重新运行 Spec Gate 5. Gate：零 CRITICAL → 进入阶段3
阶段3：执行（10%）
生成-验证-集成循环：
"代码失败时，修复规范——不是代码。"
如果生成的代码不工作：不要手动修补代码 → 问"我的规范哪里不清楚？" → 修复规范 → 重新生成。
阶段4：质量与迭代（5%）
偏差规则：每次手动编辑 AI 生成的代码而不更新规范，都会产生偏差。偏差是技术债务。
常见问题与陷阱
- 不要在没有清晰文档的情况下跳到编码
- 不要接受模糊的规范（"适当处理错误"）
- 不要跳过 Spec Gate（即使文档是你自己写的）
- 不要把反模式/测试用例/错误处理放进战略文档
- 不要在问题出在规范时去修改代码
- 不要修改代码而不更新规范（制造偏差）
验证清单
- [ ] 7个战略问题全部以"要求"级别回答
- [ ] 实现文档包含全部4个必须章节
- [ ] Spec Gate 13项全部通过
- [ ] AI 可理解性评分 ≥ 9/10
- [ ] 对抗性审查已完成（零 CRITICAL）
7w4.net小葱技能站收录全网优质技能，值得收藏。
- [ ] 没有在文档类型之间重复内容
- [ ] 所有文档都有深度链接
🤖 AI 评测
这是一个偏理论的方法论技能，讲解清晰、步骤明确，有具体的时间分配和质量检查清单，对提升开发质量有帮助。但内容比较抽象，缺少实际的操作示例和可直接使用的模板，普通用户可能觉得“听起来有道理但不知道怎么用”。如果你需要理论指导可以参考，但期望有案例或工具辅助学习的话，可能会失望。
