mohamedwaleed/specshape-plan

specshape-plan 是做什么的？

代码审查，在代码存在之前：在变更处于草图阶段时展示其形态，并保留每一个决策。

你编写一份计划：一份粗粒度、基于代码的工作内容描述，保存到 .specshape/<id>.md。 用户审阅、引导并批准它。代码稍后由 /specshape-build 一次一个任务地编写。此技能绝不编写代码。

你可以更改的内容

• .specshape/ 下的文件：计划，以及批准后的 .specshape/context.md。
• 在用户明确同意后，且仅在批准时：他们工单追踪器中的工单，以及仓库的 AGENTS.md 中的一行。

其他任何内容都不可以。不涉及源文件、分支、提交、工单评论或更改状态的命令。 如果用户要求你实施已规划的工作，请遵循步骤 7 中的可用性规则；绝不要在此处实施。 一次微调结束此技能并移交至普通代理工作（步骤 3）。

0. 定位

1. 阅读上下文。 如果存在，请阅读 .specshape/context.md，以及它所链接的任何词汇表。 其中的词汇表、约定和规则适用于你编写的所有内容。阅读 AGENTS.md 和项目自身的约定（CLAUDE.md、CONTEXT.md、ADR、贡献指南）。
2. 确定输入是什么。 首先检查 .specshape/ 中现有的计划：
   • 一个现有的计划 id → 修订该计划（参见 修订计划）
   • 一个现有计划内的故事 id → 规划该故事（参见 规划故事）
   • 一个工单键或 URL、一个规格文件或自由文本 → 新工作
   • 如果输入可能有两种含义，问一个问题，然后继续
3. 为新工作选择 id： 如果有工单键则使用，否则使用一个简短的 kebab-case 风格标识符。

1. 阅读请求

完整阅读工单或规格：描述、验收标准、评论、关联和父工单、关联的合并请求。写下验收标准；计划必须覆盖每一个，或将其列为范围外。如果输入过于模糊无法评估工作量，问一个能消除评估障碍的问题，仅此而已。

2. 调查代码

事实是你的工作。 永远不要向用户询问你可以在代码、工单或你拥有的工具中找到的信息。如果你可以将探索工作委托给辅助工具，则这样做；否则自己动手。

深入程度取决于规模，所以先快速通过一次，评估工作量（步骤 3），然后根据需要深入：

规模	调查
变更，功能	完整查看受影响的代码：有什么可以构建的基础，缺少什么，当前是如何连接的（入口点、调用路径、配置），附近的测试及其编写方式
倡议	仅查看受影响的区域：入口点和主要类型，每个都有 path:line。深度阅读在规划每个故事时进行
项目	无：没有代码

为你将依赖的每个事实记录 path:line。注意代码中使用的领域术语，以及工单和代码对同一事物使用不同词汇的地方。不要根据 Git 状态或文件列表推断未更改的内容；重新读取受影响的文件或与已验证的内容基线进行比较。

3. 评估工作量

使用 sizing.md 评估工作量。以工作量和决定工作量的信号开始你的回复，然后继续。 不要等待确认；用户可以在任何时候覆盖它（“按变更处理”）。覆盖更改的是询问轮次和计划细节，而不是计划审阅或批准。

微调 → 在此停止。用 1-3 行说明更改内容和位置，以及不需要计划。结束语：“请让你的代理直接进行此编辑，或在此处说‘修复它’以继续在 Specshape 之外操作。”不保存任何内容，也不进行任何源代码更改。此后的修复请求属于此技能之外的普通代理工作；不需要 /specshape-build。

4. 询问

提出能改变计划形态且只有用户才能回答的问题：意图、优先级、含义、代码无法解决的各种权衡。

规模	轮次
变更	无
功能	一轮。仅在答案引出新问题时进行第二轮
倡议，项目	直至没有遗留任何未解决的问题

• 在一轮中提出所有可以立即回答的问题。 依赖于尚未获得答案的问题将等待后续轮次。
• 对于项目，第一轮是关于词汇表：每个核心术语的含义以及术语之间的关系（“什么是账户？一个用户能属于两个账户吗？”），然后再涉及栈或形态。
• 当工单和代码对同一事物使用不同词汇时，询问哪个是正确的。
• 没有真正的问题，就没有轮次。 不要为了凑齐轮次而编造问题。对于倡议/项目，检查答案是否留下了未解决的实质性边界；栈或托管选择并不能解决暴露、注册或传输策略。在声称发现完成之前，先询问依赖性问题（参见 review.md）。
• 计划本身可见的选择（命名、哪个模块拥有什么）不是问题。它们是计划中的决策，默认采用你的建议。

按如下格式提出每个问题，并等待回答：

❓ **Q1 - <标题>**: <问题，如果有选项则列出>

➡️ <你的推荐答案及原因>

5. 编写计划

按照 plan-format.md 中的格式编写 .specshape/<id>.md。计划包含的内容取决于规模：

规模	包含内容
变更	摘要、决策、变更映射、一个包含 1-4 个任务的扁平列表
功能	摘要、决策、带有代码草稿的设计形态、变更映射、任务
倡议	摘要、决策、受影响区域、故事（目标和验收，不含任务）
项目	摘要、决策、形态（文件夹、模块、数据模型、主流程）、故事；第一个故事是行走骨架

每个计划在添加或更改词汇表术语、约定或规则时，也需要一个 上下文变更 部分（参见 context-format.md）。

规则：

• 证据。 关于现有代码的每个声明都必须引用 path:line。任何你无法验证的内容必须标记为 assumption:。验证引用支持声明，包括现有的测试覆盖。永远不要为了证明推荐意见而编造项目历史或过去的失败。
• 粗粒度，而非详细。 代码草稿展示签名、类型和体现核心想法的行，最多约 15 行。在公共边界说明无效输入的行为；经过验证的 CLI 并不能使无效参数对直接服务调用者变得不可达。每个任务的详细草稿将在其预览阶段、即将构建之前提供。
• 决策。 包含具有有意义的替代方案、影响设计或行为的选择。直接在其形状或任务中处理例行工作（记录一个标志、遵循既定的验证约定），除非它涉及重大的权衡。标准解析器验证不需要仅仅因为自定义验证是可能的就形成一个决策。例行工作仍在范围内：更新现有使用文档以反映已更改的公共接口；排除不相关的清理。D1、D2…… 对整个计划进行编号，包括故事。每个决策都有选项、你的推荐意见，以及用户关心的后果（“默认值为 true，因此即席运行现在会因 groupBy 而失败”）。状态：open 直到被回答；decided 当用户做出选择时；assumed 当用户未做出选择而批准时。“全部使用推荐”是一个明确的选择。
• 任务。 每个任务都使构建和测试保持绿色，并命名其文件、它执行的决策、它依赖的任务，以及一个完成检查，用于执行其新增或更改的行为。将行为及其测试放在同一个任务中；永远不要将验证推迟到后续任务。使用 testing.md 规划红-绿-重构切片、它们的公共测试边界、结果和命令。一个不变的绿色测试套件本身并不能证明新的行为。
• 风险。 命名可观察到的失败及其影响的证据。展示执行顺序的引用并不表明该顺序是必需的；如果顺序重要，请解释相关副作用。
• 故事。 每个故事都作为独立的工单和合并请求，具有目标和验收标准。保持骨架为最小的端到端路径，而不是所有基础能力。在工单存在之前，故事 id 为 <id>.<n>。永远不要重复使用编号。
• 使用词汇表中的词汇，不使用它明确禁止使用的词汇。
• 呈现。 遵循 presentation.md：对可比较的记录使用表格，对故事/任务使用依赖关系树，在解释流程或关系时使用 Mermaid。
• 只写别人会再次阅读的内容。 没有哪个部分是为了完整而存在；对于不适用的部分，写 n/a: <原因> 而不是填充它。

展示前检查。 对于倡议/项目，还需阅读 review.md 并检查跨故事的一致性和假设。在收到反馈后及批准前重新检查。修复失败：

• 每个验收标准都已覆盖，或列为范围外
• 变更映射中的每个文件都有对应的任务，并且每个任务的文件都在变更映射中
• 每个决策都有有意义的替代方案、一个推荐意见和一个后果
• 关于现有代码的每个声明都有 path:line 或 assumption: 标签
• 每个选定的约定都有验证，包括允许的默认值或回退
• 每个行为任务都包含其测试、公共测试边界和红-绿-重构检查；每个故事都有目标和验收标准
• 决策、故事/任务、上下文和范围外声明在可观察行为上保持一致
• 上下文中的任何词汇表术语、约定或规则都没有被矛盾
• base_commit 是当前的 HEAD；如果没有可用的提交，则省略并说明原因

6. 展示和审阅

展示：

• 始终完整展示： 摘要和待定决策，因为这是用户将据以行动的内容
• 变更，功能： 完整的计划正文，包括实际的代码草稿、变更映射、任务和完成检查。摘要、形态描述或指向保存文件的链接不能替代
• 倡议，项目： 带有依赖关系和依赖关系树的故事概览表，然后是其余内容的计划文件路径
• 已规划的故事审阅： 摘要、验收、待定决策、形态、完整的变更映射、任务表和依赖关系树。展示每个任务的文件、边界、结果和检查命令；共享的套件命令或散文式任务列表不能替代

以你需要用户提供的内容结束：

选择 D1a 或 D1b，提供反馈，或者说 已批准。

使用实际的待定决策 id；如果没有待定决策，则只要求反馈或批准。

收到反馈时：

• 修订计划，更新 version，并将 Changed since 行替换为更改内容
• 将已回答的决策标记为 decided
• 当用户声明了持久性偏好（“永远不要在类名中放置版本号”）或项目范围内的真理时，将其添加到上下文变更中；它将在批准时被应用

7. 批准

1. 将显式选择记录为 decided，未被选择的推荐记录为 assumed。重新检查计划的一致性，然后设置 status: approved 和 approved: <date>，如果存在提交则刷新 base_commit。当选择改变了计划内容时，更新版本号。
2. 应用上下文变更 到 .specshape/context.md，如果需要则创建它。如果仓库已有词汇表，则链接到它，仅添加缺失的内容；规划故事时使用父计划的规范词汇表。不要同时也在项目文档中安排重复的定义。然后清空计划的上下文变更部分。
3. 倡议或项目：提供工单。 列出你将创建的工单：每个故事一个，作为输入工单（史诗）的子工单，或者对于新项目，在一个新的史诗下创建。每个工单包含标题、目标、验收标准和一个指向计划的链接，而不是任务。仅在用户同意后，使用你拥有的任何工单追踪器访问权限创建它们。用计划中每个故事的工单键替换本地故事 id。检查可用的工单追踪器集成和输入工单来源；缺少 Git 远程并不证明缺少工单追踪器访问权限。如果访问权限不可用，请说明并保留本地 id。如果只有目的地未知，询问使用哪个追踪器/项目。
4. 此仓库中的第一个计划： 提供向 AGENTS.md 添加一行的选项，并仅在收到肯定答复后添加：“在处理此代码之前，如果存在 .specshape/context.md，请先阅读它。规划存放在 .specshape/ 中。”仅在 /specshape-build 技能可用时追加“对于已规划的工作，请使用 /specshape-build。”使用相同的可用性调查结果来处理此提议和下一步；在展示拟议行之前检查它。
5. 说明下一步：
   • 变更或功能：如果 /specshape-build 技能可用，则执行 /specshape-build <id> T1。否则说明计划已准备好实施，但 /specshape-build 不可用。停止，不编写代码。
   • 倡议或项目：/specshape-plan <第一个故事 id>。在建议另一个故事之前，检查其先决条件；如果尚未构建，请说明提前规划将依赖于假设，并且必须在构建前根据已实现的接口进行重新验证。 保持交接与实际保存的任务定义和完成检查一致。不要添加新的手动检查或要求；如果需要另一个检查，首先修订和审阅计划。

规划故事

输入：来自已批准计划的一个故事 id。

1. 如果父计划未被批准，请说明并停止。
2. 完整阅读该故事的依赖关系，并按现状调查其受影响的代码。如果先决代码缺失，请标记假设的接口，并说明在构建前必须重新验证的内容。对于项目的行走骨架，将其建立在父计划的决策和形态基础上。不要根据状态或文件列表推断未更改的代码。对新的边界选择应用 review.md。
3. 如果故事引发了只有用户才能回答的问题，则询问（遵循功能相关规则）。
4. 填充故事的“形状”：代码草稿、完整的变更映射、任务和完成检查。在故事的计划中记录 base_commit 和 parent_plan: <父计划 id>。
5. （……因翻译目的截断）