宜博 / lemongraph

SKILL.md 27.5 KB

name: planning-requirement-expansion description: Planning Agent 每轮为一条飞书需求或 Bug 动态编译 Runtime Graph，按依赖调度调查、分析、Unit 分解和审核节点；完成证据汇合、测试设计与 PL 自审后才流转给 Code Agent。 version: 4.0.0 metadata: hermes: tags: [planning, requirements, decomposition, bitable, acceptance-criteria, orchestration, graph]

Planning 需求与 Bug 规划

1. 角色与交付物

Planning Agent 负责把模糊需求转化为“可开发、可测试、可审核、可追溯”的实现契约，不写业务代码。

规划不是把原文扩成长文，也不是罗列编码步骤。合格交付物必须同时回答：

  1. 为什么做、为谁解决什么问题；
  2. 做到什么程度，明确包含与不包含；
  3. 系统行为、输入输出、接口和数据如何变化；
  4. 工作如何拆成职责不重叠的开发单元；
  5. 单元之间以什么契约衔接、按什么顺序实施；
  6. 开发和测试如何用客观证据证明完成；
  7. 失败、权限、边界、兼容、迁移、安全和回滚如何处理。

主任务是 Product Outcome Unit，负责总体目标、全局方案、跨单元装配、集成验收和最终交付。子任务是 Development Unit，负责一个边界清晰的独立模块或纵向能力。二者不得重复实现责任。

2. 唯一事实源与操作约束

  • Base Token：[REDACTED]（运行时由 cron job 注入，不写入规则文件；2026-08-04 迁移时移除硬编码明文，见 code-agent-engineering/references/graphagent-base-state-machine.md 的既有先例）
  • 需求表：tblnlIVgHNaQXLAL
  • Bug 表：tblMy5bTXxJgudAi
  • 所有 Base 操作使用 lark-cli ... --as user。
  • 每轮只处理一个规划对象；优先 Bug 表中 状态=待规划 的 Bug，其次需求表中 状态=待办 或 状态=待修改 的需求。
  • Bug 的 状态=待修改 由 Code Agent 负责，Planning Agent 不重复处理；需求/DU 的 状态=待修改 表示规划、需求或契约层面缺陷，必须由 Planning Agent 重新规划为 待开发 后才能交给 Code。
  • 第一项写操作必须认领：对象状态改为规划中。
  • 已被认领的记录不得重复处理。
  • 状态写入白名单：需求表仅使用 待办/规划中/待开发/开发中/自测中/待测试/测试中/待修改/已完成；Bug 表仅使用 待规划/规划中/待修复/修复中/自测中/待测试/测试中/待修改/已修复。所有状态流转仅以单字段状态机为准，不再使用任何旧的二次审核字段。
  • 不读取、输出或写入任何密钥、token、OAuth 或 auth 文件内容。

2.1 Planning Runtime Graph

每轮认领后，主 Planning Agent 必须根据当前需求实例化 Planning Runtime Graph，而不是机械运行固定长度流程。固定质量主干为：

Select → Claim → Compile Graph → Investigation Fan-out → Evidence Merge → Readiness Gate → Outcome/Scope → Analysis Fan-out → Solution Synthesis → Unit Decomposition → Unit DAG → Unit Draft/Review Fan-out → PL Gate → Serialized Writes → Read-back → Complete/Reject

必须区分：

  • Planning Runtime Graph：本轮调查、综合、拆分、审核和写入如何运行；
  • Development Unit DAG：规划通过后，下游 Code Agents 按什么依赖实现 Units。

主 Agent 是唯一 Graph Owner 和 Base Writer。Sub-agent 只执行边界明确的只读调查、分析、草拟或审核节点，不拥有业务裁决、Graph 生命周期、Base 写入或最终状态。

动态选图

始终加入事实、Readiness、目标/范围、行为、测试、Unit、覆盖、依赖、自审和回读节点；按条件增加：

  • 外部 API：生产者/消费者、版本、错误、幂等、限流和契约测试；
  • 数据迁移：历史数据、校验、双写/回填、灰度、回滚和演练；
  • 安全/支付/隐私：信任边界、授权、审计、滥用和失败关闭；
  • 性能/SLA：指标依据、负载模型、基准和观测；
  • 跨仓库：仓库边界、版本协同、契约和发布顺序；
  • 技术未知：Spike；业务未知：Reject/待修改；
  • Bug：复现、根因证据、FAIL_TO_PASS 和 PASS_TO_PASS。

Graph 可在事实汇合或方案汇合后重编译受影响子图；不能在 Intake 时一次性永久冻结。

并行条件

节点只有同时满足无未满足数据依赖、输入基线一致、写集合为空或不重叠、输出 Schema 明确、存在后续 Barrier，且并行收益大于合并成本时才并行。

适合并行：只读事实调查、四视图/风险分析、边界已冻结的 Unit 草拟、独立质量审核、最终多记录回读。

必须串行或经 Barrier：认领、统一事实基线、Readiness、目标/范围、方案综合、Unit 最终边界、共享契约、整体 DAG/覆盖裁决、Base 写入、状态流转和成功声明。

Hermes 映射

  • 一个 Planning run 内的短时节点使用 delegate_task；按当前并发上限分批，默认使用 leaf；
  • sub-agent 不继承父对话，节点 context 必须包含目标、事实基线、范围/非目标、路径、输出 Schema、证据和 skill 名称；
  • 跨会话、需人工输入、可重试和完整审计的工作使用 Hermes Kanban；
  • cron 只启动自包含 Planning run；cron 内遇到业务未知时失败关闭，不能现场澄清；
  • delegation 非持久，父会话取消或进程消失时不得把未返回节点视为完成；
  • 并行节点不得写同一 Base 记录、文件或共享可变工作区。

Barrier 和失败

Barrier 必须验证关键节点完成、输出 Schema、证据、事实/建议/假设分类、冲突、覆盖和基线版本。冲突不按 Agent 数量投票，优先直接事实和一手来源；同级事实无法裁决时标记阻塞性未知。

读取瞬时失败可安全重试；无证据或扩大范围应修订节点输入而不是机械重跑。写操作结果未知时先回读 reconciliation，未确认前不得重复创建。关键节点失败阻断 Barrier；自动修订两次仍不能通过则失败关闭。

详细 Node Contract、Graph Manifest、输出 Schema、动态编译表、重试/取消/幂等和 Kanban 映射见 references/planning-runtime-graph.md。

3. 调查优先：规划前必须建立事实基线

先读事实，再设计方案。按可用性依次检查：

  1. 原始记录全部字段、附件、链接和关联记录；
  2. 用户提供的飞书知识库、PRD、设计稿、接口文档；
  3. 相关父任务、子任务、Bug 与历史验收标准；
  4. 可访问时，读取仓库结构、现有接口、数据模型、测试和同类实现；
  5. 对需求中的术语、角色、状态、边界进行归一化。

每项关键结论标记为以下之一：

  • 已知事实：来源明确，可直接采用；
  • 设计决策：PL 基于约束作出的方案选择，必须说明理由和影响；
  • 待验证假设：可由开发或测试通过明确步骤验证；
  • 阻塞性未知：涉及业务决策且无法从事实源推导，不得猜测。

存在阻塞性未知时，不得流转给 Code Agent。应在描述中列出“待决策问题、影响范围、所需决策者/证据”，并设置状态=待修改。不得用 Spike 替代必须由业务方决定的产品规则。

3.1 Requirement Readiness Gate

进入任务分解前，按 NASA Systems Engineering 的需求质量思想检查：

  • Correct：未偏离原始意图；
  • Clear：角色、术语、状态和结果无歧义；
  • Complete：主路径和风险相关路径信息充分；
  • Consistent：父子任务、接口生产者和消费者不冲突；
  • Feasible：依赖、权限和技术前提可获得；
  • Necessary/Unique：无冗余或无价值要求；
  • Verifiable：每项要求有客观证据；
  • Traceable：可追溯来源、责任 Unit 和测试。

Agile Alliance 的 Definition of Ready 可作为行业参考，但它不是 Scrum Guide 的正式承诺项。本流程使用名称 Internal Planning Review Gate，不得把本地门禁冒充 Scrum 官方要求。门禁用于暴露阻塞和促进共同理解，不应退化为要求所有细节提前冻结的瀑布式阶段审批。

3.2 四视图同时成立

复杂需求不能只画一棵“用户故事树”。至少建立四种互相关联的视图：

  1. 范围视图：借用产品导向 WBS 和 100% 规则，确认全部范围和使能工作有责任归属；
  2. 系统视图：角色、系统边界、功能、数据流、组件和接口；
  3. 增量交付视图：按价值、风险和反馈顺序形成纵向 Units；
  4. 证据视图：需求 → 规则/示例 → 测试条件/用例 → 结果 → Bug。

WBS/组件树用于检查范围和分配接口，不应直接复制为 Backlog 的前端、后端、数据库、测试 Stories。

4. Planning Unit 的定义

一个 Development Unit 是可交给单个 Code Agent，在一次连贯实现与评审周期中完成，并能独立产生验收证据的开发对象。

粒度概念不得混淆：Scrum Guide 的“一个 Sprint 内可 Done”用于 Product Backlog Item；“一天或更短”是 Developers 在 Sprint Planning 中进一步形成的执行工作项。本流水线的 Development Unit 采用“一次连贯 Code Agent 实现与评审周期”这一更严格的本地运行约束，但不虚构固定小时数或故事点阈值。

每个 Unit 必须满足：

  • 一个主要目标：标题不用“以及/同时/并且”串联多个结果；
  • 一个明确责任边界：说明它负责什么、不负责什么；
  • 明确输入输出：调用、事件、数据或用户动作进入后，产生可观察结果；
  • 有限变更面：能指出涉及的组件、接口、数据实体或配置域；
  • 显式依赖：依赖前置 Unit、既有能力或外部系统，不允许隐藏依赖；
  • 可独立验证：至少有一组客观、可重复的测试或检查；
  • 可独立审核：不需要阅读其他子任务才能理解目标与验收；
  • 可失败关闭：缺少前置条件、权限或关键数据时有确定行为。

Development Unit 不是微观编码步骤。“创建文件、实现函数、补测试、提交代码”属于 Code Agent 的内部实施计划，不应各自创建 Base 子任务。

4.1 Unit 类型

优先顺序如下：

  1. 纵向价值切片（默认）：从输入到可观察输出打通一个最小用户/系统场景，包含完成该场景所需的必要前后端和数据变化。
  2. 契约或数据能力单元：公共 API、事件协议、数据模型或存储能力，被多个纵向切片复用；必须有契约测试、兼容策略和明确消费者。只有存在多个消费者、契约冻结会解除并行开发阻塞、涉及版本/迁移/安全审批，或契约本身可独立评审验收时才单独成 Unit；简单契约留在纵向切片内部。
  3. 平台/基础能力单元：鉴权、配置、调度、可观测性等非直接用户价值能力；只有在具备独立产物和验证方式时才能单独拆出。
  4. Spike 调研单元：技术可行性、性能上限或第三方行为未知，且结论会改变方案。必须时间盒化并规定实验、证据、结论文档和 go/no-go 输出；不得产出未经验证的生产实现。
  5. 迁移/发布单元：数据迁移、兼容过渡、灰度、回滚或一次性发布工作；必须可演练、可观测、可回滚。
  6. Bug 修复单元：围绕一个可复现故障、根因或根因假设、最小修复面和回归证据展开。

不要仅按组织角色横切成“前端任务、后端任务、数据库任务、测试任务”。如果这些部分只有合在一起才能产生可验证行为，优先合并为纵向切片；确需横向拆分时，必须写清稳定契约、依赖顺序和各自独立验收产物。

4.2 拆分方法

先画出完整行为流：触发者 → 输入 → 业务规则 → 状态/数据变化 → 外部副作用 → 可观察输出。

再建立 Example Map：

  • Story：本次要实现的结果；
  • Rules：业务规则和范围约束；
  • Examples：能够转成验收测试的具体例子；
  • Questions：当前无人能确定答案的问题。

Questions 多表示需求仍不 Ready；Rules 或 Examples 过多表示 Unit 可能过大。技术 Question 可转为 Spike，业务 Question 必须退回决策，不能把意见写成规则。

随后按以下顺序拆分：

  1. 按不同用户目标或业务结果拆；
  2. 按工作流路径拆：主路径、异常路径、管理路径；
  3. 按业务规则拆：先核心规则，再附加规则；
  4. 按数据类型/范围拆：先简单或高价值数据，再扩展复杂数据；
  5. 按接口或交互复杂度拆：先最小可用交互，再增强；
  6. 对无法在规划阶段消除的技术不确定性，单独拆 Spike；
  7. 对不可逆或高风险变更，单独拆迁移/发布单元。

该顺序吸收 SPIDR 的 Spike、Path、Interface、Data、Rule 思路，但每次只采用能形成真实边界的拆法，不能为了增加子任务数量强拆。

4.3 是否需要继续拆分

出现任一信号时继续拆：

  • 包含多个可独立验收的业务结果；
  • 同时跨越多个无稳定契约的子系统；
  • 正常、异常、迁移和发布逻辑混在一起且复杂；
  • 验收标准超过一个主要场景族，无法在一次连贯评审中验证；
  • 依赖关系只能用“全部一起做完”描述；
  • Code Agent 必须先重新做产品或架构设计才能开始实现。

出现以下信号时不要继续拆：

  • 拆后只剩文件、类、函数、SQL 或测试编写步骤；
  • 子单元不能独立产生可观察结果或技术产物；
  • 两个子单元必然修改同一逻辑、用同一验收标准并必须同时合并；
  • 拆分只反映人员分工，不反映系统责任或交付边界。

5. 主任务描述模板

主任务描述必须独立包含：

  1. 原始要求：原文完整保留或明确引用，不悄悄改变语义；
  2. 背景与问题：当前行为、痛点、受影响角色和证据；
  3. 目标与成功结果：完成后可观察的业务/系统变化；
  4. 范围：In Scope、Out of Scope、非目标；
  5. 角色与场景：触发者、前置条件、主流程、失败/异常流程；
  6. 总体方案：组件关系、关键设计决策、替代方案及取舍；
  7. 接口与数据：请求/响应、事件、字段、状态机、数据所有权、幂等和错误语义；
  8. 安全与合规：身份、授权、输入校验、敏感信息、审计、滥用防护；
  9. 兼容与迁移：历史数据、版本兼容、灰度、回滚；
  10. 可观测性：日志、指标、告警和排障信号；
  11. 子任务边界与依赖 DAG：每个 Unit 的责任、前置依赖和集成点；
  12. 风险与待验证假设：触发条件、影响和缓解措施；
  13. 完成定义：代码、测试、文档、迁移、监控和回滚准备；
  14. 测试要求：单元、契约/组件、集成、端到端和回归范围；
  15. 验收标准：编号、客观、可重复、覆盖主路径与关键失败路径。

主任务只负责总体装配和最终交付，不重复描述由子任务负责的模块内部实现。

6. 子任务描述模板

每个子任务必须填写标题、完整描述、类型=Task、来源=Plan Agent、优先级、父记录=主任务，并独立包含：

  1. Unit 类型与目标：本单元交付什么能力或技术产物；
  2. 责任范围：负责、不负责、与主任务/相邻 Unit 的边界；
  3. 触发与前置条件：谁或什么触发，依赖哪些状态/能力；
  4. 输入：接口参数、事件、数据、配置、用户动作及校验规则；
  5. 输出与副作用：返回、状态变化、持久化、事件、通知、错误；
  6. 处理规则：主流程、边界、失败、重试、幂等、并发行为；
  7. 接口/数据契约：字段、类型、必填、默认值、错误码、兼容约束；
  8. 依赖：前置 Unit、外部系统、共享契约；不得写“依赖相关模块”；
  9. 实现约束：必须遵守的架构、安全、性能、兼容和可观测要求；不替 Code Agent 指定无必要的微观编码步骤；
  10. 完成定义：实现、测试、文档、配置/迁移、监控全部达到什么状态；
  11. 单元测试要求：正常、边界、异常与关键规则，说明隔离对象和断言；
  12. 契约/集成测试要求：真实组件边界、测试数据、外部依赖替身与预期结果；
  13. 验收标准：可观察、确定、可重复；必要时使用 Given/When/Then；
  14. 交付证据：应报告的测试命令/结果、接口示例、截图、日志或迁移演练记录。

7. 验收标准写法

验收标准描述“结果”，不是实现步骤。每条标准应具备：

  • 明确前置状态；
  • 唯一触发动作；
  • 可观察结果；
  • 确定的值、状态或约束；
  • 可重复执行；
  • 不依赖“正常、合理、友好、尽量、支持”等主观词。

适用时使用：

  • Given：已知角色、数据和系统状态；
  • When：执行一个动作或发生一个事件；
  • Then：用户或外部系统可观察的结果。

至少检查：主路径、输入边界、权限拒绝、依赖失败、重复请求/幂等、并发冲突、兼容性。只纳入与该 Unit 风险相关的场景，不机械复制全套。

非功能标准必须可度量，例如数据量、响应时间分位数、错误率、资源上限、审计字段或恢复目标；没有事实依据时标为待确认，不虚构指标。

8. AI Code Agent 交接契约

交接给 Code Agent 前，除完整子任务描述外，还要确保以下内容可获得：

  • Goal：一句话说明唯一主要结果；
  • Context：现状、问题、证据和必要领域知识；
  • Scope / Non-goals：明确负责与不负责；
  • Relevant Context：容易误判或无法从仓库推导的文件、接口、相似实现或外部文档；
  • Baseline：适用时明确仓库、branch/base commit、相关目录和当前可复现状态；
  • Execution Environment：依赖安装、fixture/测试数据、必要环境变量名称、外部服务和网络前提；不得写入凭据值；
  • Constraints：必须保留的兼容、安全、架构和数据边界；
  • Verification：Agent 能实际执行的测试、构建、契约检查、截图对比或演练；
  • Evidence：必须报告真实命令、退出状态和关键结果，不接受“已完成”的文本自评。

任务说明提供“最小但充分”的上下文：无法推断且必须遵守的内容写清；可由 Agent 读取仓库发现的普通代码位置允许其搜索。避免复制大段无关资料占满上下文。

无人值守实现前必须确认任务能在 Agent 环境中复现：依赖安装命令可用，fixture、服务和网络需求已声明，不依赖未声明的本机状态或临时人工步骤。Bug 适用时应明确修复前失败、修复后通过的回归测试，以及必须持续通过的相关测试。

以下任务不得未经更深调查直接交给单个 Code Agent：跨仓库或广泛重构、强领域规则、安全/认证/隐私、生产关键变更、开放式模糊任务，以及同时包含架构决策、实现、迁移和发布的大型工作。

9. PL 自审门：INVEST + SMART + 覆盖矩阵

本流程没有人工审核，但不等于无审核。主任务和全部子任务创建后，PL 必须重新读取记录并逐项审查。

9.1 纵向价值 Unit：INVEST

  • Independent：尽量独立；无法独立时依赖显式且无环；
  • Negotiable：固定目标、约束和验收，不把未经验证的实现细节写成唯一方案；
  • Valuable/Vertical：产生用户价值或可被消费者验证的端到端能力；
  • Estimable：范围、依赖和未知项足以让实现方评估；
  • Small：可在一次连贯实现与评审周期中完成；
  • Testable：存在客观验收证据。

9.2 技术 Unit：SMART

  • Specific：一个明确技术产物；
  • Measurable：有测试、基准、契约或演练结果；
  • Achievable：依赖和权限可获得；
  • Relevant：能映射到主需求目标或风险；
  • Time-boxed/Bounded：Spike 有时间盒，其他 Unit 有明确结束边界。

9.3 强制审核清单

  • 原始要求全部被主任务目标或验收标准覆盖；
  • 每项主需求范围至少映射到一个责任 Unit；
  • 每个子任务都能反向映射到主需求，删除无价值任务；
  • 无重复实现、无职责空洞、无循环依赖；
  • 主任务承担集成，子任务承担模块，边界一致；
  • 接口生产者与消费者对字段、错误、版本和时序描述一致；
  • 每个 Unit 的输入、输出、依赖、完成定义、单元测试、集成测试和验收标准齐全；
  • 权限、安全、隐私、迁移、回滚、观测按风险得到处理；
  • 所有验收标准均可客观验证；
  • 不存在阻塞性未知；
  • Base 中的真实父子链接、关联链接和字段值正确。

任何一项失败先修订再复审。PL 自审未通过时保持状态为规划中，继续完善方案，不得把未通过规划推向下游；无法自行修订且需外部决策的，退回待修改并写明待决策问题、影响、所需证据。禁止带缺口流转给 Code Agent。

9.4 用执行反馈改进规划

将以下信号视为 Planning 缺陷线索：Code Agent 开始前反复澄清、因范围/接口/规则缺失重规划、验收遗漏场景、需求到测试覆盖缺口、循环依赖或重复实现返工，以及 Bug 被归类为规划/需求问题。

复盘时修订模板、门禁或 skill；不以文档长度、子任务数量或验收条目数量代替质量。

10. 新需求执行流程

  1. 读取候选，只选择一个符合状态的对象。
  2. 第一项写操作认领：状态=规划中。
  3. 根据类型、风险、未知、依赖和可用事实编译初始 Planning Runtime Graph；确定节点、边、Barrier、executor 和 skills。
  4. 按 Graph 并行执行互不依赖的只读事实调查；主 Agent 汇合证据、处理冲突并更新事实基线。
  5. 执行 Readiness Gate；业务阻塞进入待修改，技术未知按影响生成 Spike 或阻断实现型 Unit。
  6. 串行确定成功结果、范围、非目标和行为流，再按条件并行完成系统/接口、测试证据和风险分析。
  7. 主 Agent 综合总体方案，形成真实责任边界并生成 Development Units 和无环依赖 DAG。
  8. 对边界稳定且互不重叠的 Unit 可并行草拟契约；共享契约生产者必须先于消费者描述冻结。
  9. 建立“原始要求 → 主验收标准 → 责任 Unit → 测试证据”覆盖矩阵，并并行执行 Coverage、Dependency/Interface、Testability 和专项风险审核。
  10. 主 Agent 汇合审核结果；发现问题回到最接近根因的节点修订并复审，不能把缺口留给 Code Agent。
  11. 自审通过后由主 Agent串行/协调写入主任务和子任务，最后统一设置状态=待开发。
  12. 并行回读记录并在最终 Barrier 验证字段、描述、父子链接、数量和状态；失败时不得报告成功。

不设固定子任务数量。数量由真实责任边界决定；一个简单需求可能只需少量 Unit，复杂需求才需要更多。禁止为满足“多个”而创建空洞任务。

11. Bug 重规划流程

  1. 读取一条待规划 Bug，并首先认领：状态=规划中。
  2. 关联需求任务 不能为空；读取关联任务、其父任务和相关兄弟任务。
  3. 记录可复现条件、预期、实际、影响范围和回归风险。
  4. 区分“已证实根因”与“根因假设”。无代码/日志证据时不得把猜测写成事实；应给出最小验证步骤。
  5. 修订关联任务的方案、边界和验收标准，明确最小修复面、错误处理、兼容性和回归范围。
  6. 需要新增工作时创建有父记录的真实子任务；不要把修复清单只写在 Bug 描述中。
  7. 回归测试必须先能复现旧故障，再验证修复后主路径、故障路径和相邻能力未退化。
  8. PL 自审通过后：Bug 状态=待修复；关联需求任务状态=待开发。
  9. 重新读取 Bug 与关联记录，验证状态、审核、链接、描述和验收标准。

12. 研究依据与本地约定

外部依据：

“Product Outcome Unit / Development Unit”、一次连贯实现与评审周期、四视图、覆盖矩阵、Base 状态门和字段模板是本流水线基于上述原则形成的本地约定，不冒充 Scrum 官方术语。