# Planning Agent 方法论研究摘要与来源

完整研究报告：`/Users/yibo/.hermes/profiles/planning/research/planning-agent-methodology/planning-agent-methodology-report.md`

## 研究方法与限制

研究由三个独立研究 Agent 并行完成，主 Agent 再直接读取官方网页及 NASA/ISTQB 官方 PDF 交叉验证。原计划同时使用 Gemini Deep Research API，但当前 Planning profile 无可用 Gemini API key，API 路径没有成功执行。本摘要不冒充 Gemini Deep Research 输出。

## 一、组合四个互补视图

### 范围分解

NASA WBS Handbook 将 WBS 定义为识别硬件、软件、服务及其他交付物的产品导向家族树，不是组织结构；整体需包含 100% 项目范围，包括系统工程、安全和质量保证等使能工作。

Planning 用途：检查所有范围是否有责任归属，避免遗漏和无主工作。不要把 WBS 的技术层直接复制成 Stories。

### 系统分解

NASA Systems Engineering Handbook 的路径是：利益相关方期望 → 技术需求 → 逻辑/功能分解 → 设计方案 → 实现、集成、验证和确认。需求应描述输入、输出、输入输出关系、约束，以及与操作者、维护者和其他系统的交互。

Planning 用途：定义系统边界、组件职责、接口、数据和错误流。系统结构不等于交付顺序。

### 增量交付分解

INVEST 要求 Story 尽量 Independent、Negotiable、Valuable/Vertical、Estimable、Small、Testable。Microsoft Minimal Slices 建议用最小有价值切片频繁交付，尽早反馈。SPIDR 提供 Spike、Path、Interface、Data、Rule 五类拆分线索。

Planning 用途：默认形成纵向 Development Units，不按前端/后端/数据库/测试机械横切。

### 证据分解

ISTQB 强调测试基础、测试条件/风险/测试用例、测试结果和缺陷之间的追溯。

Planning 用途：维护“原始要求 → 主验收 → 责任 Unit → 测试证据 → Bug”的覆盖链。

## 二、Requirement Readiness

NASA 需求质量原则可归纳为：正确、清晰、完整、一致、可行、必要且非冗余、可验证、可追溯。

阻塞性未知不能靠文档扩写掩盖：

- 技术未知可建立时间盒 Spike；
- 业务决策未知必须退回，不得交给 Code Agent 猜测。

Agile Alliance 的 Definition of Ready 是行业实践，不是 Scrum Guide 的正式承诺项。本流水线应称为 Internal Planning Review Gate。

## 三、Planning Unit

本流水线的 Development Unit 是：一个单个 Code Agent 能在一次连贯实现与评审周期中完成，并独立产生 pass/fail 证据的结果闭环。

必须具有：

- 一个主要结果；
- 明确负责和不负责；
- 输入、输出、副作用和错误；
- 有限变更面；
- 显式无环依赖；
- 独立可理解、实现、审核和验证；
- 可执行证据。

不是独立 Planning Unit：创建文件、实现函数、写 SQL、补测试、提交代码等微观编码步骤。

Unit 类型：Vertical Value Slice、Contract/Data、Platform/Enabler、Spike、Migration/Rollout、Bug Repair。

粒度层级必须区分：Product Backlog Item 的 Ready 参考是可在一个 Sprint 内达到 Done；Developers 在 Sprint Planning 中通常再把执行工作拆成一天或更短。Development Unit 的“一次连贯 Code Agent 周期”是本流水线约定，不等于 Scrum 的“一天任务”，也不设置跨团队通用的固定小时或故事点阈值。

公共契约只有在多消费者、冻结契约可解除并行开发阻塞、涉及版本/迁移/安全审批，或契约能独立评审验收时才单独成 Unit；简单契约属于纵向 Story 的交付物。

## 四、分解算法

1. 调查原始记录、知识库、关联项、仓库和测试；
2. 归一化角色、术语、状态和范围；
3. 区分事实、PL 决策、待验证假设、阻塞性未知；
4. 画行为流：触发者 → 输入 → 规则 → 状态/数据变化 → 副作用 → 可观察输出；
5. 建立 Example Map：Story → Rules → Examples → Questions；
6. 建立范围、系统、增量交付、证据四视图；
7. 按用户目标、Path、Rule、Data、Interface 拆分；
8. 技术未知用 Spike，高风险变更用 Migration/Rollout；
9. 建立 Dependency DAG；
10. 建立 Coverage Matrix 并通过自审门。

继续拆分：存在多个独立结果、多个无稳定契约的系统、复杂迁移/异常、Code Agent 仍需重新设计。

停止拆分：下一层只剩文件/函数/SQL/测试步骤；拆后没有独立产物；两部分必须同改同验同合并；拆分只体现人员分工。

## 五、任务契约和 AI Handoff

GitHub Copilot、OpenAI Codex、Anthropic Claude Code 官方指南共同支持：AI Agent 更适合清晰、范围明确、上下文充分、约束显式、具有完整验收标准和可运行验证的任务。

任务契约应包含：Goal、Context、Scope/Non-goals、Entry Conditions、Inputs、Outputs/Side Effects、Rules、Interface/Data Contract、Dependencies、Constraints、Definition of Done、Tests、Acceptance Criteria、Evidence。

适用时还应绑定仓库与 branch/base commit、相关入口、依赖安装、fixture/测试数据、服务和网络前提。任务不得依赖未声明的本机状态或临时人工操作；Bug 应尽量明确修复前 FAIL_TO_PASS 和必须持续通过的 PASS_TO_PASS 回归集合。

给出易误判或无法从仓库推导的上下文；可由 Agent 搜索发现的普通代码位置不必全部复制。复杂跨仓库、强领域、安全、认证、生产关键和开放式任务应先研究、规划或继续拆分。

Anthropic 强调给 Agent 可运行的 pass/fail 信号；否则 Agent 只能依赖“看起来完成”。SWE-bench 用真实仓库测试执行判断补丁是否解决问题，支持“真实执行证据优于文本自评”。

## 六、验收与测试

验收标准描述 Unit 特有的可观察行为；Definition of Done 是通用最低质量契约。适用时使用 Given/When/Then；Then 验证用户或外部系统可观察输出，而不是内部函数调用。

按风险选择：主路径、边界、异常、权限、依赖失败、幂等、并发、兼容、迁移和回归。测试深度按风险决定，不机械要求所有 Unit 具备所有测试层级。

一般测试属于 Story 的 Done；只有共享测试环境/框架、性能、安全、灾备、迁移演练或外部认证具有独立产物时，才建立单独 Test Unit。

## 七、自审与治理

- 纵向 Unit：INVEST；
- 技术 Unit：SMART；
- 总体：Coverage Matrix + Dependency DAG + Risk/Test Review。

无法通过时失败关闭：能补则修订；技术未知建 Spike；业务未知退回；不得留给 Code Agent 开发时再决定。

可用于复盘的信号：开发前澄清次数、重规划率、验收遗漏、覆盖缺口、循环依赖/重复实现返工、规划/需求归属 Bug 的重复模式。指标用于改进 skill，不用于鼓励文档膨胀。

## 权威来源

1. Scrum Guide: https://scrumguides.org/scrum-guide.html
2. Agile Alliance INVEST: https://agilealliance.org/glossary/invest/
3. Agile Alliance Definition of Ready: https://agilealliance.org/glossary/definition-of-ready/
4. Agile Alliance Definition of Done: https://agilealliance.org/glossary/definition-of-done/
5. Mountain Goat SPIDR: https://www.mountaingoatsoftware.com/blog/five-simple-but-powerful-ways-to-split-user-stories
6. Cucumber Gherkin: https://cucumber.io/docs/gherkin/reference/
7. Cucumber Example Mapping: https://cucumber.io/blog/bdd/example-mapping-introduction/
8. NASA WBS Handbook: https://explorers.larc.nasa.gov/APSMEX/MO/pdf_files/NASASP-2010-3404-WBS-handbook.pdf
9. NASA Systems Engineering Handbook: https://ntrs.nasa.gov/citations/20170001761
10. Microsoft Minimal Slices: https://github.com/microsoft/code-with-engineering-playbook/blob/main/docs/agile-development/advanced-topics/backlog-management/minimal-slices.md
11. ISTQB CTFL: https://istqb.org/certifications/certified-tester-foundation-level
12. GitHub Copilot Coding Agent: https://docs.github.com/en/copilot/tutorials/cloud-agent/get-the-best-results
13. OpenAI Prompting Codex: https://developers.openai.com/codex/prompting/
14. Anthropic Claude Code: https://code.claude.com/docs/en/best-practices
15. SWE-bench Evaluation: https://github.com/SWE-bench/SWE-bench/blob/main/docs/guides/evaluation.md
16. Hermes Context Files: https://hermes-agent.nousresearch.com/docs/user-guide/configuration

Product Outcome Unit、Development Unit、一次连贯 Code Agent 周期、四视图和 Base 状态门是本流水线综合约定，不是上述框架的官方术语。