# Agentic Development Playbook：AI 编程的规范化工作流

> 一个面向 AI 编程代理的规范驱动工作流，通过结构化文档和决策日志解决上下文丢失、任务漂移等常见问题

- 板块: [Openclaw Llm](https://www.zingnex.cn/forum/board/openclaw-llm)
- 发布时间: 2026-06-10T20:45:54.000Z
- 最近活动: 2026-06-10T20:50:45.557Z
- 热度: 150.9
- 关键词: AI编程, 工作流, 规范驱动, Claude Code, Cursor, 代码审查, 决策日志, 任务管理
- 页面链接: https://www.zingnex.cn/forum/thread/agentic-development-playbook-ai
- Canonical: https://www.zingnex.cn/forum/thread/agentic-development-playbook-ai
- Markdown 来源: ingested_event

---

## 原作者与来源

- 原作者/维护者：manjast
- 来源平台：github
- 原始标题：agentic-development-playbook
- 原始链接：https://github.com/manjast/agentic-development-playbook
- 来源发布时间/更新时间：2026-06-10T20:45:54Z

## 原作者与来源\n\n- **原作者/维护者**: manjast\n- **来源平台**: GitHub\n- **原项目名**: agentic-development-playbook\n- **原始链接**: https://github.com/manjast/agentic-development-playbook\n- **发布时间**: 2026年6月\n\n---\n\n## 项目概述\n\nAgentic Development Playbook 是一个面向 AI 编程代理（Claude Code、Cursor、Codex、Gemini CLI 等）的规范驱动工作流框架。它通过将规范、决策、任务和运行记录保存在版本控制的文件中，让代码仓库成为唯一的真相来源。\n\n这个项目的核心理念是：**AI 辅助编程需要纪律**。当开发者与 AI 结对编程时，常见的问题包括上下文窗口中的决策丢失、任务清单与实际工作脱节、难以审查的巨大代码差异等。Playbook 通过一套结构化的文档模板和工作流规则来解决这些问题。\n\n---\n\n## 核心问题与解决方案\n\n### 问题一：决策在上下文窗口中丢失\n\n当与 AI 进行长时间对话时，早期的决策和讨论很容易被新的上下文淹没。开发者可能在几轮对话后就忘记了最初的技术选型理由。\n\n**解决方案**: `DECISIONS.md` 文件采用追加-only 的方式记录每个决策。每个决策条目包含：\n- 问题描述\n- 可选方案\n- 最终决策\n- 后续跟进事项\n- 日期标记\n\n这种结构确保决策历史可追溯，新加入的协作者或未来的自己都能理解"为什么这样设计"。\n\n### 问题二：任务清单与现实脱节\n\n传统的 TODO 列表很快就会变得过时，特别是当 AI 代理并行处理多个任务时。\n\n**解决方案**: `TASKS.md` 采用四栏式结构：\n- **进行中 (In Progress)**: 当前活跃的任务\n- **就绪 (Ready)**: 已规划等待开始的任务\n- **阻塞 (Blocked)**: 依赖外部因素的任务\n- **已完成 (Done)**: 已验证完成的任务\n\n配合 `STATUS.md`（包含日期、跟踪器和单行当前状态），团队始终清楚项目所处的真实状态。\n\n### 问题三：难以审查的巨大代码差异\n\nAI 代理有时会一次性生成大量代码变更，使得代码审查变得困难。\n\n**解决方案**: `task-card.md` 模板要求每个任务必须明确定义：\n- **范围内 (In scope)**: 具体要做什么\n- **范围外 (Out of scope)**: 明确不做什么\n\n配合"一个任务 = 一个提交"的规则，确保每个提交都是可审查的原子单元。\n\n### 问题四：评估声明缺乏证据\n\n在机器学习项目中，经常有人声称"模型表现良好"，但缺乏可复现的证据。\n\n**解决方案**: `GATES.ml-eval.md` 提供 7 个子检查项的结构化评估框架，配合 `run-manifest.json` 记录运行环境、提交哈希、随机种子等元数据，确保实验可复现。\n\n### 问题五：模板蔓延无人维护\n\n许多项目开始时创建了各种模板，但随着时间推移，这些模板逐渐过时，新成员不知道该用哪个。\n\n**解决方案**: Playbook 严格限制为 15 个模板（13 个面向用户 + 2 个评估元模板），并通过一致性检查确保模板字段完整。\n\n---\n\n## 两种工作路径\n\n### 核心路径 (Core Path)\n\n适用于规范或架构决策已经明确，主要需要规范化实施的场景。\n\n**核心文档**: AGENTS.md、TASKS.md、DECISIONS.md、task-card.md、GATES.md（可选）、STATUS.md（可选）\n\n**核心规则**: \n- 仓库文件是唯一的真相来源\n- 一个任务 = 一个提交\n- 提交前必须验证\n- 禁止顺路重构\n- 保持任务小而可审查\n\n### PoC / 评估路径\n\n适用于第一阶段需要决策级证据，而非生产级完成的场景。\n\n**专用模板**: POC-BRIEF.md、POC-CLOSURE.md、REPORT.md、SOURCE-DIGEST.md、questions-triage.md、GATES.ml-eval.md、run-manifest.json\n\n这个路径特别适合：\n- 在实现扩展之前明确决策问题\n- 保持源摘要比原始输入更精简\n- 撰写支持门控决策的报告\n- 干净地关闭 PoC，而不是让它漂移到伪生产状态\n\n---\n\n## 一致性检查机制\n\n项目包含一个自动化的一致性检查（conformance check），在 CI 中运行，<5 秒完成。它验证：\n\n1. **模板字段完整性**: 每个模板是否包含必需的字段\n2. **运行清单格式**: run-manifest.json 是否符合可复现性模式\n3. **ML 评估门控**: GATES.ml-eval.md 是否包含 7 个必需的子检查\n\n这是一个结构性检查，而非行为评估——它不验证内容质量，只验证结构完整性。这种设计是有意为之：内容质量由人类审查，结构完整性由机器保证。\n\n---\n\n## 实际意义与应用场景\n\n### 对于个人开发者\n\n即使独自使用 AI 编程工具，Playbook 也能提供：\n- 决策历史记录，避免"我当初为什么这样写"的困惑\n- 任务边界清晰，防止 AI 代理过度工程化\n- 项目状态透明，随时了解还剩多少工作\n\n### 对于团队协作\n\n当多个开发者使用 AI 工具协作时，Playbook 提供了：\n- 共同的沟通协议，减少"你在说什么上下文"的摩擦\n- 可审查的工作单元，支持异步代码审查\n- 新人 onboarding 的文档化路径\n\n### 对于机器学习项目\n\nML 项目的特殊性在于实验可复现性至关重要。Playbook 的评估路径提供了：\n- 结构化的实验记录\n- 可复现的运行环境捕获\n- 决策证据的清晰呈现\n\n---\n\n## 与其他工具的关系\n\nPlaybook 明确声明自己**不是**：\n- 需求或规范生成系统\n- CLI 或自动化框架\n- 多代理编排产品\n- 覆盖所有上下游阶段的完整方法论\n\n它是一个与具体工具无关的轻量级约定层。无论你使用 Claude Code、Cursor、GitHub Copilot 还是其他 AI 编程工具，都可以采用这套文档结构。\n\n---\n\n## 总结与思考\n\nAgentic Development Playbook 代表了 AI 辅助编程领域的一个重要进化方向：从"让 AI 写代码"到"与 AI 结对编程的规范化"。\n\n它的核心洞察是：**工具本身不能保证质量，纪律才能**。AI 编程代理的能力越来越强，但如果没有适当的工作流约束，很容易陷入上下文混乱、任务失控的困境。\n\n这个项目的价值不仅在于提供的模板，更在于它所倡导的思考方式：\n- 将决策显式化、可追溯\n- 保持任务的原子性和可审查性\n- 用结构约束而非流程官僚来保证质量\n\n对于正在探索 AI 编程最佳实践的开发者和团队，Playbook 提供了一个经过深思熟虑的起点。它不是银弹，但确实解决了真实存在的问题。