implementation-workflow

实施工作流

• 遵循本地项目说明和约定。相关时结合可用的领域技能；即使没有这些技能，本工作流也适用。
• 对于小型任务，直接处理：阅读相关上下文和当前差异，完成修改，运行必要的检查，检查最终差异，并报告结果。若任务复杂、风险较高或用户提出要求，则另行制定计划、划分阶段或使用子 Agent。

选择模式

• 仅规划：检查并提出方案，不修改项目文件。
• 规划并实施：制定足以降低风险的计划，然后继续编写代码。
• 继续或恢复：还原当前状态，然后采取最小且安全的步骤。
• 当用户要求拆分工作时，将每项任务拆分为可独立产生价值且可验证的部分。说明拆分仅用于规划，还是会实际执行。
• 当用户要求实施时，继续完成验证并交付结果。只有在缺少答复、遇到实际阻碍或用户要求暂停时，才暂停相关工作。

选择下一项任务

• 当用户要求选择或规划下一项任务，但未指定具体任务时，首先检查仓库声明的主要任务跟踪器。对于没有其他既定事实来源的 GitHub 仓库，使用 GitHub Issues 及其关联的 GitHub Project。
• 根据优先级、影响、准备情况、依赖关系和当前仓库状态等证据，对可执行的候选任务排序。选出最合适的一项并继续按要求规划。如果有多个候选任务的可行性相近，则按顺序列出排名前两到三项，简要说明各自为何适合现在开展，并请用户选择。
• 如果排名第一的候选项是尚无子任务的 Epic，则停止选择，并说明需要先规划并拆分为可执行任务。如果无法从可访问的任务跟踪器中找到任务，则检查明确的本地路线图、TODO 或待办文档，然后请用户指示。
• 任务选择授权你执行用户所要求的选择或规划。如果用户的请求也涵盖实施，则实施所选任务。
• 开始处理已跟踪的任务时，如果任务跟踪器中尚未将用户指派为负责人，则将其指派给用户。要替换其他人的指派时，先征求用户同意。

明确范围

在规划或编辑之前：

1. 阅读本地说明、项目约定，以及任何可用且相关的领域技能。
2. 检查工作树、相邻代码模式、测试和可用证据，包括相关的项目决策记录和实验记录。
3. 明确预期结果、约束、非目标、影响范围和验证需求。

• 提问前先检查仓库和对话，确认是否已有答案。只要任务仍存在不确定性，就提出明确的澄清问题；在所有模式及任务执行的各个阶段都应如此，即使只是不重要的细节。
• 等待答复后，再做受影响的决定。可以继续处理当前任务中符合所选模式、且不依赖该答复的部分。将明确给出的默认值、既定约定，以及用户已提供的信息或授权视为已确认的答复。
• 区分事实、有条件的估计和未知项。根据请求和仓库证据推导需求、集成方式、支持场景和兼容性要求。

研究并测试方案

• 将必需结果和硬性约束与建议的实现方法区分开来。将建议的方法视为候选方案，包括你自己的建议。
• 选择方案前，先明确任务中的重要决策，并针对这些决策调研当前的在线证据。调研应涵盖相关架构、算法、用户和开发者体验、可靠性、安全性、验证方式及资源成本，而不只是 API 用法或代码语法。根据决策的影响和不确定性调整调研范围。对于已由仓库证据完全确定的机械性本地修正（例如拼写错误），应仅在本地准备。
• 对于 API 行为和版本支持，使用官方文档和发行说明。同时查阅一手工程报告、研究论文、实测对比，以及关于失败或经验教训的记录。利用这些资料了解相关领域中已确立的实践、可信的替代方案、权衡取舍和常见错误。
• 检查资料日期，以及其中的建议是否适用于项目的版本、平台、约束和工作负载。若硬件会影响决策，也要将其纳入考量。通过原始来源或本地检查验证关键主张，并区分已证实的结果、建议和缺乏依据的主张。
• 说明调研结果如何支持或改变方案。在计划或任务报告中附上重要决策所依据的来源链接，并说明仍未验证的重要主张及其局限。
• 结合调研和仓库证据，检查假设、缺口及可信的替代方案。在相关情况下，比较正确性、简洁性、可读性、可维护性、风险、性能、内存使用和可验证性。如果某项尚未解决的主张可能影响选择，就进行有针对性的检查或测量。遵循项目对实验和记录的要求。
• 实施过程中出现新的重要问题时，应先调研，再作出相关决策。
• 如果建议的方案经验证仍然合理，就予以认可并继续执行。如果不合理，则说明具体问题，并在最终确定计划或修改前解决该决策。

询问前先解释决策

在请用户选择方案前：

1. 将当前情况和目标与待决策事项联系起来。说明该事项在工作流中的位置、还有哪些问题尚未确定，以及哪些先前决策仍然有效。复用相关上下文，不要重复整段讨论。
2. 说明每个选项的工作方式，以及它会对用户或项目带来什么变化。解释不熟悉的术语；如果仅凭选项名称无法清楚说明其行为，就给出具体示例。
3. 比较每个选项在实际中的优势、缺点，以及具体后果或风险。在相关情况下，说明额外的用户操作、维护成本或受支持环境范围的限制。只有当后续变更与当前决策相关时，才解释其影响。
4. 根据已确认的任务事实和用户需求，推荐一个选项。说明它相关的成本或限制，以及为何这种权衡适合当前任务。明确区分未知事项和已知事实。
5. 先在聊天中给出上述说明，再提出问题。一次说明一批中的所有决策，然后按相同的选项名称和顺序提问。说明应能独立理解，不依赖选项选择器的描述。

根据用户作出决策所需的信息调整详细程度。对于事实性澄清，应直接提问；必要时说明该事实为何重要，无需编造替代方案或权衡取舍。

计划

• 对于非简单工作，保留一份计划。说明预期结果、边界、步骤、影响范围、验证方式和剩余风险。根据复杂度调整细节，并保留所有重要决策。
• 在有助于明确变更或避免错误时，写明文件、模块和接口。无需列出完整的文件清单。
• 在进度清单中区分已完成工作、当前范围和设想。随着工作推进及时更新。

1. 将完整计划与进度清单分开存放。使用可重新读取且能保留完整计划的原生存储，或存放在系统临时目录中的任务专用 plan.md。如果当前指令禁止写入文件，则在聊天中提供完整计划，并在允许写入后、开始实现前再存储。
2. 保留完整的已批准文本、语言、决策、接口、边界、示例、验证方式、假设和非目标。Plan Mode 结束后，复制最新的 <proposed_plan> 正文，不含标签。这是任务状态，不是仓库内容。
3. 说明计划的存放位置，并在首次修改项目之前以及上下文压缩之后重新阅读计划。
4. 决策发生变化时，用完整的更新后计划替换原计划。
5. 保留作为成果交付或为继续工作、交接所需的计划。只有在其支持的工作完成或取消后，才删除其他为任务创建的临时计划文件。

• 对于大规模迁移或重构，编辑前梳理公共入口、内部辅助项、移除的旧路径以及共享行为的归属。
• 在敲定计划前，于商定范围内解决重要决策。只有任务要求或证据支持时才添加需求。
• 将变量名称、具体编辑位置和导入项等常规细节留给实施者。只有当这些细节会影响既定方案或行为时，才明确指定。

实施

• 为已知任务创建分支时，将其跟踪 ID 纳入分支名，以便其他会话恢复任务。遵循项目的分支命名规范，并保留 ID 中的大小写，例如 feat/gh-42-session-cache 或 fix/APP-123-token-refresh。使用项目的跟踪信息确定仓库或项目；如果仅凭 ID 无法明确，则在名称中加入相关上下文。
• 按最小的有效工作切片推进。
• 沿用本地模式。只有在确认有需要时才添加抽象。
• 在高风险边界之后进行验证，例如架构、共享实用工具、公共 API、有状态 UI、迁移和身份验证。
• 当范围发生变化、风险得到解决或出现阻碍时，及时告知用户。对于警告，说明具体的失败条件或恢复措施。
• 保留用户的更改及其暂存状态。无关更改不影响正常工作。
• 修改与用户更改重叠的文件之前，先检查该文件当前的差异。如果修改可能覆盖用户的工作，且正确结果不明确，则展示冲突并在编辑前询问。
• 如果某个工作切片揭示了更大的设计选择，则停止扩展范围。只有请求的结果确实需要该选择时才继续。
• 如果评审反馈反复涉及命名、类型、包装器或连接逻辑，应先修复共同原因，再逐一修补。
• 只有在有证据、检查失败或用户明确决策支持时，才记录后续工作。

有选择地并行工作

• 只有在不同工作可并发进行且收益大于协调成本时，才使用子 Agent。优先并行开展只读调研、风险分析、测试发现和架构对比。
• 为每个子 Agent 指定明确且范围狭窄的目标、要检查的确切证据、工作边界、编辑权限和所需产出。避免编辑范围重叠。由主 Agent 整合决策并执行最终验证。

验证并完成

• 遵循代码库的验证矩阵。否则，根据可能影响的范围选择检查：
  • 文档变更需要进行相关的 lint 或格式检查。
  • 类型或 UI 变更需要进行类型检查、lint、针对性测试；如果流程发生变化，还需要进行浏览器覆盖测试。
  • 共享实用工具、架构、数据模型、身份验证、持久化和公共契约需要进行更广泛的测试。
  • 新的浏览器流程应先运行针对性场景，再运行完整测试套件。
• 不要因为微小变更就不加判断地运行完整测试套件。对于高风险变更，也不要验证不足。
• 如果检查失败，请判断是否由本次变更导致。修复由变更导致的失败。如果相关检查仍有失败，不要将任务标记为完成；请提供证据，说明无关或既有的失败。
• 对于文档，请假设读者熟悉标准工具和可见的 UI 控件。围绕不明显的设置、契约和操作限制重写受影响的章节；将常规命令和设置作为链接。一般性的清理不会免除项目说明要求的参考文档。除非必须保留记录，否则请在回复中保留任务历史。

完成前：

1. 检查最终工作区和差异。移除不再需要的任务临时文件。保留必需的输出，包括生成的文件，以及变更前已有的修改。
2. 确认结果符合已商定的任务和用户最新的澄清。
3. 报告变更涉及的内容、运行过的验证、未运行的检查，以及具体的剩余风险。