tasks

任务

任务存储在项目根目录下的 .agents/tasks/<task name>/ 文件夹中。

如果此文件夹不存在，请创建它。

<task name> 指用户指定的任务名称。例如，如果用户说 Begin task: update-pull-request-workflow，那么 <task name> 就是 update-pull-request-workflow。

<task name> 文件夹中可能包含以下文件：

• CURRENT_DESIGN.md - 对当前任务涉及的代码库相关部分的详细描述。它包含任务描述中涉及的所有文件和重要函数及／或选择器。如果此文件不存在，你的首要任务就是创建它。如果文件已存在，除非它与当前 TODO 相关，否则无需阅读。开始处理第一个 TODO 时，请务必确保已阅读此文件。

• PLAN.md - 对需要进行的更改所制定的详细计划。此文件会根据项目 AGENTS.md 文件（如果存在）和 CURRENT_DESIGN.md 所确立的代码库理解，提供完成任务所需更改的高层详细计划。如果此文件不存在，请根据用户提供的任务描述创建，然后根据此计划创建 TODOs.md（见下一条）。如果文件已存在且你尚未阅读，请阅读。

• TODOs.md - 按顺序排列的非层级编号步骤大纲。此文件中的每个 TODO 都对应一个 STEP-<N>.md 文件，子步骤记录在对应文件中。开始任何任务前，请务必阅读此文件，以了解接下来要处理的具体步骤。TODO 应简明描述待完成的高层任务（详情写在 STEP 文件中）。例如：

  1. [x] 分析所有与创建用户相关的现有代码
  2. [ ] 重构代码库，让所有用户创建后都加入 `#general` 频道
  

• STEP-<N>.md - 这些文件对应 TODOs.md 中的编号步骤。文件中包含当前步骤的状态、一系列编号子步骤，以及用于记录步骤进度的最终章节。你可以将此文件用作记忆库，以便在会话结束或上下文清除后，在新上下文中继续处理。示例如下：

  # 分析所有与创建用户相关的现有代码
  
  状态：已完成
  
  ## 子任务
  
  1. [x] 查看 `backend/` 中所有用户创建代码
  2. [x] 查看 `frontend/` 中所有用户创建代码
  
  ## 备注
  
  我已完成调查，找到了以下与创建用户相关的函数，首先是后端部分：
  
  ### 后端用户创建代码
  
  - `createUser()` - `backend/userManagement.ts:78-190`
  - ...
  

• KNOWLEDGE.md - 如果此文件存在，开始处理任何 TODO 前都必须阅读。此文件记录项目中的注意事项，以及应做和不应做的事。请根据用户提供的有用反馈以及你在处理代码库时的发现，酌情创建或更新此文件（以便下次无需重复相同的排查步骤）。内容应简洁，不要太长。重要： 此文件保证在每次会话开始时都会被阅读，因此任何后续 TODO 会用到的发现——例如注意事项、约束或与后续步骤相关的意外行为——都必须记录在此文件中，不能只写在当前步骤的备注里。请在条目开头标明相关的 TODO（例如：对于 TODO-3 的测试：...）。

备注

除非另有说明，否则每次只处理一个 TODO。完成某个 TODO 后，向用户简要报告你完成的工作。其他详细信息留在对应 STEP-<N>.md 文件的 NOTES 部分。如果其中任何信息是未来 TODO 所依赖的发现，也要将其记录到 KNOWLEDGE.md 中（见上文），因为之后可能不会再读取旧的步骤文件。

为避免占用不必要的上下文，除非完成当前步骤确有需要，否则不要读取之前的步骤文件。

应在你正在处理的 STEP-<N>.md 文件中跟踪进度。不过，如果有助于完成当前步骤，也可以更新任务文件夹中的其他文件。

如果在处理子任务时发现必须调整 PLAN.md 或 TODOs.md，请立即更新，然后再继续实施。如果要向现有任务添加 TODO，请改为遵循“向现有任务添加 TODO”一节中的规则。

• 重要：除非已先为 TODO 创建对应的 STEP-<N>.md 文件、完成该步骤、更新其备注部分，并将其状态标记为 COMPLETED，否则绝不要将 TODOs.md 中的 TODO 标记为已完成。
• 重要：工作过程中，完成当前 STEP-<N>.md 文件中的某个子任务后，务必立即将其标记为已完成。不得例外！完成此操作前，不要开始下一个子任务！这样可以确保会话中断后能顺利继续。
• 重要：如果你的 Agent 环境中有 todos 类型的工具（UI 清单），使用此技能时绝不要使用它！
• 重要：为任务创建文件时，绝不要连续创建多个 STEP-<N>.md 文件！添加 TODO 到现有任务时除外；务必只为当前正在处理的 TODO 创建 STEP 文件，并且只有在查看完相关文件、准备开始工作后才能创建。

完成一个步骤并在 TODOs.md 中将其 TODO 标记为已完成后，请停下并让用户审核你的更改（除非另有指示要求继续）。

向现有任务添加 TODO

当用户要求向现有任务添加 TODO，且该任务已经有 CURRENT_DESIGN.md、PLAN.md 和 TODOs.md 文件时，请使用此流程。尚未开始的 TODO 不需要已有 STEP 文件。

此流程适用于可在现有 TODO 完成后执行的后续工作。

• 阅读 TODOs.md、PLAN.md、KNOWLEDGE.md 以及与所请求的新增内容相关的其他任务文件。
• 在 TODOs.md 末尾添加简短、概括性的 TODO。
• 除非新 TODO 与现有计划矛盾，否则不要修改 PLAN.md。如果矛盾，请在 PLAN.md 末尾添加简短的补充说明，解释方向调整并引用该 TODO 编号。此规则优先于上述一般的 PLAN 更新规则。
• 创建对应的 STEP-<N>.md 文件，并将所有实施细节写入其中。将其状态设为 NOT STARTED。
  • 这是在 TODO 成为当前任务之前创建 STEP 文件的明确例外。
• 最早尚未完成的 TODO 仍是当前 TODO。

然后停止，不要实施新 TODO，除非另有指示。

暂停，等待用户介入

如果遇到只能由用户解决的阻碍——例如需要你无权使用的权限（sudo / dnf / apt installs）的命令、缺少凭据，或你无法自行获取的资源——不要尝试绕过，不要继续重试，也不要悄悄跳过受影响的工作。请改为：

1. 在当前 STEP-<N>.md 中添加一个标题恰为 ## PAUSED: user intervention required 的章节，说明受阻事项、需要用户执行的具体操作（包括准确的命令），以及你可以建议的替代方案或解决方法。
2. 立即停止：不要将子任务或 TODO 标记为完成，并在最终输出中报告阻碍及你的建议。

收到回复后——无论用户立即回复，还是在之后的会话中回复（继续任务时，请检查当前步骤文件中是否有未解决的 ## PAUSED: 章节）——由你自行处理，在该章节下记录用户的回复以及阻碍的解决方式，将标题改为 ## RESOLVED: user intervention，然后从中断处继续执行步骤。如果回复后仍然受阻，请以相同方式再次暂停，并说明仍缺少什么。

仅审查指示

如果用户告知你对任务“仅审查”“仅验证”或“验证计划”（或表达类似意思），则表示他们不希望你实际完成任何 TODO。此时，只需审查现有的 CURRENT_DESIGN.md、PLAN.md、TODOs.md（以及任何相关的 STEP 文件），并将其与代码库进行比对，验证当前计划是否合理或是否需要调整。如果需要调整，请相应更新文档，然后停止并向用户简要总结更改。

管理有限上下文

Agent 环境可能具备以下两种有用的工具：

• (A) 知道剩余上下文量的能力
• (B) 通过向新会话工具传递上下文来启动新的会话上下文并继续工作的能力

如果 Agent 软件具备 (A) 但不具备 (B)，则在剩余上下文不多时停止，并向用户简要报告。

如果 Agent 软件同时具备 (A) 和 (B)，并且由于剩余上下文有限需要启动新的会话，请使用 (B) 启动新会话，以便继续当前工作。务必始终提醒自己在新的会话上下文中加载“tasks”技能，然后按照此处的说明，向其提供用户指定的 <task name>。

如果两者都不具备，也不必担心，希望系统能够自动压缩上下文。