task

/task

工具选择

开始前，请为任务选择合适的工具：

活动	工具	原因
架构规划	Claude Code /plan	Opus，1M 上下文
功能实现	Claude Code	Hooks、子 Agent、工作树
快速修复单个文件	VS Code Claude ext	适用于小范围任务，速度更快
DevOps / 终端	Codex CLI	擅长终端任务
后台重构	Codex Cloud	自动创建 PR，无需等待
代码审查	GitHub Actions	异步执行，不占用会话
编写测试	子 Agent：test-writer（CC）/ 内联（Codex）	独立上下文
编写文档	子 Agent：doc-writer（CC）/ 内联（Codex）	成本低，专注高
调研	Claude.ai Projects	持久化，支持网络搜索

跨工具说明

此技能使用 Claude Code 功能。Codex/Cursor 的可移植替代方案：

Claude Code	Codex / Cursor
TaskCreate / TaskUpdate	在 .branch-context.md 中使用 Markdown 检查清单
EnterWorktree	使用绝对路径，并通过 git -C 执行所有操作
/orient、/brainstorming 等	阅读 .agents/skills/<name>/SKILL.md 并手动遵循
调度子 Agent（implementer、test-writer）	在主会话中按顺序执行
Agent Teams	不支持 — 按顺序执行工作
/review、/plan-review	阅读 .agents/skills/review/SKILL.md 并手动遵循

参数

调用方式	行为
/task <description>	开始新任务
/task #<issue>	根据 GitHub issue 开始任务
/task	开始新任务 — 询问要处理什么

Copilot 模式

在 Copilot 模式（operating-mode.md）下，工作流是菜单，而非流水线：

• 展示可用步骤。按人的要求执行。不要强制规定顺序。
• 放宽优先使用工作树的要求 — 允许直接在主工作树中写入。
• 除 operating-mode.md 明确覆盖的情况外，以下不变规则仍然适用。
• 如果人说“遵循工作流”，则按步骤执行，但每次转换时都要暂停并等待批准。

不变规则

这些规则是由 Agent 解读的指导原则，并非由机器强制执行。无论任务类型或范围如何，除非另有说明，否则都不能跳过。未提及不代表允许跳过 — 未明确列为可跳过的步骤都必须执行。

REQUIRE task_list.all_steps_populated BEFORE step_1
REQUIRE worktree BEFORE code
REQUIRE orient.complete BEFORE plan
REQUIRE tests BEFORE implementation  # TDD: RED → GREEN → REFACTOR
REQUIRE review(plan).pass BEFORE build UNLESS scope == one_sentence OR task_type IN [fix, hotfix]
REQUIRE validate.pass BEFORE review(build)
REQUIRE review(build).pass BEFORE archive
REQUIRE task_list.no_pending_steps BEFORE ship
REQUIRE branch.base IS CURRENT(origin/main) UNLESS stacking
REQUIRE plan.commit BEFORE review(plan)
REQUIRE batch.commit BEFORE batch.next

WHEN ci.down:
  USE local_merge AT step_8
WHEN files_touched MATCH [AGENTS.md, config.toml, sync.sh, skills]:
  REQUIRE codex_specialist IN review_panel

步骤

在步骤 3-5 期间，将重要决策保存到 .branch-context.md — 不要等到反思或退出时才保存。

步骤 0 — 初始化

为检测到的路径创建包含所有步骤的任务列表。每个步骤都必须列为任务 — 无一例外。任务列表是强制执行机制：待处理任务是尚未完成的必需工作的可见证据。

• Claude Code：每个步骤使用一次 TaskCreate 创建任务。预先填入所有步骤（在 orient 检测到路径后进行调整）。开始前将任务标记为 in_progress，完成后标记为 completed。
• Codex/Cursor：在 .branch-context.md 中添加包含所有步骤的 Markdown 检查清单。

步骤 1 — 了解情况

使用参数调用 /orient（Codex：阅读 .agents/skills/orient/SKILL.md）。它会生成：

• task_type：feat / fix / chore / docs / test / refactor
• scope：能否用一句话描述整个 diff？能 → 短路径（跳过步骤 3-4）。不能 → 完整路径。注意：描述简短 ≠ 改动小 — “更新所有依赖”听起来简短，但可能会涉及几十个文件。

orient 完成后，根据检测到的路径，在任务列表中填入剩余步骤：

• Hotfix（fix/*、hotfix/*）：无论范围如何，始终跳过步骤 3-4。不做计划，也不审查计划 — 直接进入步骤 5。
• 一句话即可描述范围（任何任务类型）：跳过步骤 3-4。
• 其他所有情况：完整路径（步骤 0-9）。

步骤 2 — 隔离

使用步骤 1 中的分支名称调用 /isolate（Codex：读取 .agents/skills/isolate/SKILL.md）。该工具会处理代码新鲜度检查（获取 origin main）、从 origin/main 创建 worktree、选择目录、确保 gitignore 安全、安装依赖，以及验证基线测试。如果当前已位于 worktree 中，则会更新分支，而不是创建新分支。

路径规范： 在 Claude Code 的 Bash 调用之间，cd 不会持久生效。创建 worktree 后，所有文件操作都使用绝对路径，git 命令使用 git -C <absolute-path>。切勿假设 cd 会持续生效。

步骤 3 — 规划

热修复（fix/*、hotfix/*）： 跳过 — 继续执行步骤 5。不使用架构师 Agent，不创建计划文件。改为在提交信息中添加一段诊断说明。记录：“步骤 3 — 规划：已跳过（热修复快速路径）。”

一句话范围： 跳过 — 继续执行步骤 5。记录：“步骤 3 — 规划：已跳过（一句话范围）。”

完整范围：

3a. 头脑风暴。 使用任务描述调用 /brainstorming。进行一轮——完善想法、确认约束，并探索 2-3 种方案。

3b. 编写计划。 使用 ai-workspace/plans/TEMPLATE.md 中的模板，将计划写入 ai-workspace/plans/<name>.md。填写模板中的所有字段，包括：

• 分支、创建日期、状态
• 威胁模型（建议性或对抗性）
• 范围上限
• 任务描述和范围
• 带复选框的步骤（包括要创建/修改的文件和测试策略）
• 信心支架（建议用于对抗性威胁模型）

此处不要审查计划——那是步骤 4 的内容。

步骤 4 — 审查计划

无计划（热修复或一句话范围）： 跳过 — 继续执行步骤 5。

有计划：

对计划文件运行 /review（Codex：读取 .agents/skills/review/SKILL.md 并手动遵循）。

• 自动组建计划审查小组：
  • 始终包含：technical-editor
  • 代码架构：添加 architect-reviewer
  • AGENTS.md / config.toml / sync.sh / skills：添加 codex-specialist
  • 身份验证 / 凭据 / 权限：添加 security-auditor
  • UI / 组件 / CSS：添加 ui-designer
• 门槛：P2（修复 P0-P2，记录 P3 及更高等级问题）
• 最多：3 轮

通过审核后：继续执行步骤 5。 3 轮后升级处理：停止并向人工呈现未解决的问题。

步骤 5 — 构建

调用 /build（Codex：读取 .agents/skills/build/SKILL.md）。该工具会处理计划解析、批次顺序执行/任务并行的子 Agent 调度、TDD、批次间回归检查，以及 validate 硬性门槛。对于热修复或一句话范围，直接使用 TDD 实现。在 /build 报告 validate 通过之前，不能开始步骤 6。

热修复流程（适用于 task_type 为 fix 或 hotfix 的情况）：

• 必须只修复缺陷，不做其他更改（最小变更原则）。
• 热修复期间不得重构；应另建分支进行清理。
• 必须先测试具体的失败用例（RED），再修复（GREEN）。
• 必须在提交信息正文中记录根本原因。
• 未经明确批准，不得修改 Agent 配置文件。

步骤 6 — 审查构建结果

对更改的文件运行 /review（git diff main...HEAD）（Codex：读取 .agents/skills/review/SKILL.md 并手动遵循）。

• 自动组建代码审查小组（与步骤 4 的计划审查小组不同）：
  • 始终包含：code-reviewer
  • 代码架构：添加 architect-reviewer
  • AGENTS.md / config.toml / sync.sh / skills：添加 codex-specialist
  • 身份验证 / 凭据 / 权限：添加 security-auditor
  • UI / 组件 / CSS：添加 design-reviewer
• 门槛：P2
• 最多：3 轮

通过审核后：继续执行步骤 7。 升级处理：停止并向人工呈现未解决的问题。

步骤 7 — 归档

有计划：

调用 /archive（Codex：在计划文件中填写 Outcomes & Learnings，并重命名为 .done.md）。该工具会在计划文件中填写 Outcomes & Learnings，并将其重命名为 .done.md。

无计划（热修复 / 一句话范围）：

确保在提交信息正文中记录根本原因或变更理由。没有需要归档的计划文件。

第 8 步 — 交付

调用 /ship（Codex：读取 .agents/skills/ship/SKILL.md）。它会处理验证、方案呈现（PR + 自动合并、本地合并、保留或丢弃）、CI 状态正常/异常时的处理方式、本地路径的浅克隆合并，以及工作树清理。CI 状态取自对话上下文——如果用户表示 CI 不可用，/ship 会使用本地合并路径。

如果修改的文件包含 AGENTS.md、config.toml、sync.sh 或 skills，则评审组中必须有 codex-specialist（在第 6 步强制执行）。

第 9 步 — 复盘

调用 /reflect（Codex：读取 .agents/skills/reflect/SKILL.md）。它会处理：

• 读取 .branch-context.md 中的会话经验
• 在 main 上写入 MEMORY.md
• 按需提交后续问题
• 清理分支产物

完成定义

• 已安装依赖（pnpm install）
• 所有测试均通过（pnpm test:all）
• 类型检查通过（pnpm typecheck）
• Biome 检查通过（pnpm lint）
• 格式检查通过（pnpm format:check）
• 代码已评审（PR：由另一位 Agent 评审；本地合并：通过 /review 评审组）
• 计划文件已填写 Outcomes & Learnings
• 已编写 PR/提交说明，为评审者提供上下文
• 分支已合并到 primary（通过 PR 或 /local-merge）
• 已通过 /reflect 整理关键经验并推送到 primary

中止

可在任意步骤调用 /bail，以干净地中止。它会处理：将经验记录到 .branch-context.md、更新问题、关闭尚未关闭的 PR，以及清理工作树。/bail 会取代第 9 步（复盘），因为它会自行记录经验。清理所有尚未完成的任务列表项。