shape-idea

构思方案

此技能需要 project-knowledge、add-stack-context、 explain-visually 和 build-prototype。在提出第一个问题前，确认 这些技能均已安装。若缺少某个技能，请停止并报告其安装命令 npx skills@latest add toy-crane/skills --skill <name>；如果项目固定了包管理器运行器，请使用该运行器。

将决策对齐与交付分开

方案设计用于敲定决策；实现用于落实决策。不要更改产品源代码、 配置或依赖，即使你计划撤销编辑也不行。更改一行代码会混淆决策对齐与交付，还会留下未经审查的代码。

仅写入 spec 文件夹、术语表、决策契约、根目录的 DESIGN.md 及其读取路由（记录屏幕决策时会更新），以及供应商的 Agent 上下文。所有实验、基准测试和预览都在工作树之外的临时目录中运行。如果实验无法回答某个问题，请记录假设及其风险。如果代码与用户要求或某项决策相矛盾，请指出冲突；不要修复代码。

开始时以及写入 spec.md 前，再次检查工作树。撤销本次会话在允许路径之外所做的更改，仅保留你了解到的信息。对于会话开始前已有的未提交工作，不要动它。

以项目事实为决策依据

在提出第一个问题前，针对正在制定方案的问题和方向，以及其中涉及的术语和选项，调用 project-knowledge。它会返回这些术语已确认的定义、适用的决策契约，以及它写入的每个 GLOSSARY.md 条目或 docs/decisions/<subject>.md 文件的路径。在整个会话中应用这些内容，并以相同方式将每个已厘清的术语和每项已敲定的决策交由它处理。

如果根目录存在 PRODUCT.md，请在敲定工作单元前阅读。将其视为当前的应用层前提，仅使用与所选工作相关的产品约束，并指出任何需要更改该前提的不一致之处。不要创建、编辑或将整个文件复制到工作单元 spec 中。缺少 PRODUCT.md 不会阻碍方案设计。

在询问用户之前，先解决现有证据能够解答的问题。

关于第三方软件包或工具行为的任何结论，都必须以其实际行为的证据为依据，例如其源代码、文档、发行记录和维护者声明；在基于这些结论进行构建或规避问题之前，还需在临时副本中根据本项目使用的版本进行确认。记录检查了什么、有哪些不足，以及上游的什么更改会使该决策需要重新审视。

如果某项决策选择了框架或托管服务，请针对这一项技术调用 add-stack-context，并提供选择该技术的决策及项目证据，使其只审查该技术，而不是整个技术栈。该技能负责对此进行发现、来源验收、安装和实时供应商文档路由，并返回该技术的核算结果，以及其安装的技能路径和新增或更改的 Agent 指令行；收到这些内容后，方案设计方可继续，并在 spec 中记录结果。

一次只提出一个决策

用最轻量、足以判断的方式，向用户提出一个具体方案供其修正。

• 如果不太可能出现偏差，或偏差容易发现，就自行决定成本低、可逆的选择；将其表述为可覆盖的假设，绝不能将其作为项目决策契约。
• 如果选错某个分支的代价很高，就只针对一个事实、数值或选择提出一个问题。附上推荐答案和简短理由，然后等待。
• 如果某项拟议决策依赖只有用户才知道的信息，就说明该信息，并询问是否适用。可以自行核实的条件应自行核实。
• 如果某项选择需要通过查看或试用来评判，就检查当前界面作为依据；只有决策需要基线对比时才展示。呈现一个候选方案，或两个到三个受控变体，核实相关状态，然后等待用户反馈。对于完整界面的审查，调用 build-prototype；对于用户的具体情况，则进行临时对比。将该决策层独立于产品屏幕数量来确定范围：只传入评判所需的问题和上下文；如果已有原型，就将选定结果整合进去，并丢弃对比内容，然后继续塑造方案。如果没有足够的渲染工具，就暂缓决策并记录由此产生的风险。
• 如果流程、状态模型或关系包含多个分支、转换或关联，就在做下游决策前先绘制一张图。对其中尚未解决的部分至多提出一个问题，然后等待。对于适合用一个句子表达的线性结构，直接用文字说明。
• 如果用户要的是解释，而不是做决策，就调用 explain-visually，并提供问题及其涉及的来源；该工具会返回渲染后的解释，之后继续塑造方案。

用户确认某项选择，或用户明确授权你对该类决策自行决定后，该选择即告确定。只有当后续工作应复用该选择、其理由足以避免合理的反复讨论，且该选择源自真实权衡时，它才会成为项目决策契约；局部于功能的选择留在规范中。

只有在模式已获确认、属于常规呈现细节，或用户明确授权时，才跳过审查。记录跳过原因，并且仅将由 Agent 判断的原因视为假设。

编写产品契约

当所有与实现相关的决策都已解决或明确延期时，就停止提问；不要等用户宣布完成。 将已确认的产品变更请求转化为必要行为。将成本低且由 Agent 选择的默认值保留为可覆盖的假设；对于尚未确定且影响重大的行为，进行询问或明确延期，并将其可能造成的影响记录为剩余风险。切勿将延期的分支记录为已确定的约束。产品在决策未定期间所需的临时行为，写在对应的延期事项下，并注明将取代该行为的决策；如果契约在其他位置再次写明该行为以便实现和测试，也要在那里标记为临时行为。

准备好实施时，将 docs/specs/<slug>/spec.md 写为稳定的产品契约；必要时创建 kebab-case 文件夹。包括用户可见的结果、获批范围、可观察的验收标准、已确定的约束及其理由、假设、不可触及的范围及原因、延期事项、剩余风险，以及实施前准备事项。记录行为和决策，不要预测文件、函数、代码结构、技术层级或实施步骤。仅纳入 PRODUCT.md 中适用的应用级约束；将该文件保留为这些约束的权威产品上下文，而不是完整重复其内容。

当这项工作依赖另一个规范文件夹先完成时，在关联来源旁添加 Blocked by: docs/specs/<other>/ 一行，每个文件夹一行，无论规范使用何种语言，都必须使用该英文标签。这是后续协调会读取的仓库信息，因此无论是否已设置问题跟踪器，都要写入。

始终使用完全一致的英文标题 ## Setup before implementation 编写一个章节。将实施所需的每项仓库外工作各列一行，例如供应商账户、已签发的密钥，或控制台、DNS 设置：说明所需内容、其服务的结果，以及一个无需依赖本规范所交付的工作即可观察到的完成条件，例如控制台状态、在应用外发出的直接 API 调用，或 DNS 查询。无需准备时写 None.，绝不写入密钥值。将由谁负责以及如何实施留待后续处理；梳理需求期间不要执行这些工作。

当仓库的 AGENTS.md 或 CLAUDE.md 包含 ## Issue tracker 章节，且用户指出这项工作来自一个现有问题时，在关联来源旁添加 Issue: <tracker>:<id> 行，并按其中记录的惯例填写 ID 格式。只能使用用户提供的 ID；绝不要按标题搜索跟踪器来查找 ID，也不要在梳理需求期间创建问题。没有该章节或没有已知 ID 时，不要写此类行。

如果获批的 prototype.html 存在，则链接该文件；并链接本工作所依赖的每个决策契约，使实施时必须加载这些来源，而非将它们视为可选内容。保留先前 build-prototype 收尾工作已写入的链接。说明每个链接来源在此处的约束范围，并将其自身的规则、阈值和屏幕构成保留在对应来源中，不要再将其复制到规范所述的约束中；在契约对应字段旁保留这些链接，而不是将它们集中到一处。

让经过塑造的改动变得可评判

最后，总结完整的产品约定，并从用户的角度说明获批的产品改动，让用户能够理解并评判。用户不应需要查阅规范，或另行询问最终体验会是什么样子。

选择最能体现预期改动及其重要后续影响的说明和获批的视觉证据。特别关注那些只查看改动涉及的表面时容易忽略的影响。

在收尾说明中列出规范中的准备事项，以便用户在开始实施前完成这些事项。

区分预期体验与已实现的证据，确保收尾说明与产品约定一致，也不要提示用户采取其他行动。