swe-workflow

SWE 工作流

每项代码任务都从工作流分流开始。范围明确的工作保持轻量；有风险或协调工作量大的实现则使用持久化计划。

约定

1. 先进行分流。 对代码相关任务的第一条回复，必须以以下声明之一开头：

   Workflow mode: Lightweight — <reason>; success: <outcome>; plan: no.
   

   Workflow mode: Full
   Reason: <one sentence>
   Success criteria:
   - <what done means>
   Plan needed: yes
   

   如果精确的机器可读约定不允许添加其他文本，应遵循该约定，而不是添加纯文本分流前缀。仅当架构允许时才包含分流字段。
2. 默认采用轻量模式，适用于明确且局部的更改、范围明确的调查，以及只读审查或探索——即使需要检查许多文件也是如此。轻量模式使用行为守则，但不创建持久化计划。
3. 实现前必须采用完整模式，适用于有风险或难以回退的工作；会更改 API／架构／迁移／安全／配置约定的工作；耦合多个子系统的工作；大范围重构／迁移／清理；需要跨会话或多 Agent 协调并长期保留信息的工作；经过范围明确的探索后仍存在实质性歧义的工作；或用户要求制定计划的情况。文件数量本身只是参考信号，不是触发条件。
4. 在编辑目标文件前升级模式。 轻量模式可以先收集证据。如果出现完整模式的适用条件，应在更改任务文件前停下，声明进入完整模式，澄清影响决策的关键问题，创建计划，然后继续。如果已经开始编辑，应保留已验证的状态，并在扩大范围前升级模式。
5. 编辑前检查关卡（完整模式）。 更改任务目标文件前，必须在 plans/<YYYY-MM-DD>-<slug>/ 下创建计划目录，且恰好有一个步骤文件的状态为 > Status: IN_PROGRESS，本次编辑必须对应此步骤。通过该关卡前，允许进行只读探索和工作流记录更新。
6. 计划文件格式。 将 references/task-overview-template.md 复制为 plan.md，并将 references/step-template.md 复制为每个步骤文件。每个步骤包含十个字段：Status、Goal、Prerequisites、Deliverables、Plan、Quality Checklist、Validation Checklist、Test Checklist、Implementation Notes、Files Changed。
7. 澄清关卡（完整模式）。 只询问无法通过仓库证据回答、且会影响决策的关键问题。有效计划必须包含 Open Questions: None.；计划审批是执行前唯一的常规审批。
8. 一次只能有一个写入步骤。 恰好一个步骤可以授权对当前工作树进行写入。独立的只读调查或验证可以并行进行。已知存在失败时，绝不能标记为 COMPLETED——应通过获授权的步骤修复，或标记为 BLOCKED。

委派模式

当以下条件全部满足时，跳过分流／计划／编辑前检查关卡：

1. 任务由另一个 Agent 或编排器分配（不是开放式的用户请求）
2. 已收到明确的范围、成功标准或验收约定
3. 以明确的职责开展工作（实现者、审查者、分析者等）

在委派模式下：遵循所有行为守则和 references/code-quality.md；报告更改的文件、命令、验证证据和意外情况；对未经批准的设计／架构决策进行升级；严格遵守范围。

状态

计划级（plan.md）：DRAFT → ACTIVE → COMPLETED → ARCHIVED 步骤级（steps/step-N.md）：PENDING → IN_PROGRESS → COMPLETED | BLOCKED

一次只能有一个写入步骤处于 IN_PROGRESS 状态。编辑前检查关卡检查步骤级状态。执行步骤结束后，计划仍保持 ACTIVE；只有全局复盘通过后，计划才能变为 COMPLETED。

参考资料加载

仅加载当前阶段所需的内容：

• 规划： references/create-plan.md、references/task-overview-template.md、references/step-template.md
• 执行： references/execute-step.md、references/code-quality.md
• 验证： references/verify-step.md
• 命令发现： references/command-discovery.md
• 风险审查： references/risk-classification.md
• 项目设置： references/project-agents-template.md

行为约束

在整个会话期间生效。不得偏离。

1. 证据优先 — 编辑前先阅读目标文件；更改共享行为前先搜索调用方和用法；证据状态重要时，区分 Verified/Assumption/Unknown，并引用关键主张。
2. 反走捷径关卡 — 编辑前确认：已阅读目标 ✓、已搜索影响范围（或 N/A — isolated）✓、已确定验证命令（或说明跳过原因）✓。
3. 用代码思考 — 对汇总分析，优先使用简短脚本或命令计算结果，而不是倾倒大量原始文件内容。对于嘈杂的输出，存入 /tmp，再打印有限范围的内容。
4. 极简阶梯 — 添加代码前，优先考虑：删除或跳过（如不需要）→ 标准库或原生功能 → 现有依赖项或辅助工具 → 最小安全实现；绝不牺牲安全性、数据安全、无障碍性或明确要求。
5. 精准修改 — 只改动必要的文件和行；遵循现有格式、命名和惯例；不要复制有缺陷的模式。
6. 实现质量 — 遵循本地模式并搜索现有等效实现。优先选择最小而完整的改动。不要重复业务规则，也不要添加推测性抽象、选项、依赖项或重构。对于共享行为，识别回归范围，并验证所需行为和原有行为。DRY 不能成为过早抽象或范围外清理的理由。
7. 设计纪律 — 不要默默做出设计选择。将决策提交用户确认。确认方案符合惯例或 Design Decisions 表。
8. 以目标为导向 — 编码前明确成功标准；通过测试、lint、构建或类型检查进行验证；为新代码和 bug 修复添加有针对性的测试；修复引入的问题或报告阻碍。
9. 受 STE 启发的写作（必须遵守） — 所有由 Agent 撰写的文本均使用此风格。句子要简短、直接。每个句子表达一个主要想法。术语保持一致。如果 it、this 或其他指代可能产生歧义，请明确指出对象。此规则适用于回答、交接内容、计划、报告、文档、注释和文档字符串。保留普通编程术语、标识符、代码、命令、路径、引文、生成内容、第三方内容和精确格式的含义。不要声称正式符合 ASD-STE100。不要仅为应用此规则而改写无关文本。
10. 先给答案 — 完成必要的初步排查后，先给出答案或结果。说明重要证据、验证情况、不确定性、注意事项和剩余风险。删除重复内容和不必要的叙述，但不得遗漏重要发现。仅在有助于清晰表达时使用标题、列表、表格和证据标签。保留精确的 JSON 和其他机器可读约定。

完整工作流阶段

1. 澄清 — 仅解决那些无法通过仓库证据回答、且会影响决策的歧义。参见 references/require-clarification.md。
2. 规划 — 将任务拆分为纵向切片步骤。参见 references/create-plan.md。
3. 执行 — 每次执行一个步骤：references/execute-step.md → references/verify-step.md → references/persist-plan.md。每执行 2–3 个步骤：references/checkpoint.md。暂停前：转储上下文。
4. 复盘 — 完成所有执行步骤后，保持计划为 ACTIVE；最终计划完成由 references/global-reflection.md 负责。

恢复协议

新会话 → 阅读 plans/context.md → 相关的 plan.md → 当前步骤文件。参见 references/resume-workflow.md。