ce:work

工作执行命令

高效执行工作，同时保证质量并完成各项功能。

简介

此命令接收一份工作文档（计划、规范或待办文件）或一段描述工作的简单提示词，并系统地执行其中的工作。重点是通过快速理解需求、遵循现有模式并始终保持质量，交付完整功能。

输入文档

<input_document> #$ARGUMENTS </input_document>

执行工作流

阶段 0：输入分类

根据 <input_document> 中提供的内容，确定后续步骤。

计划文档（输入是现有计划、规范或待办文件的文件路径）→ 跳至阶段 1。

简单提示词（输入是工作描述，而非文件路径）：

1. 扫描工作区域

   • 根据提示词，找出可能需要修改的文件
   • 查找这些区域现有的测试文件（搜索导入、引用实现文件或与其名称相同的测试／规格文件）
   • 记录受影响区域的本地模式和惯例

2. 评估复杂度并选择处理方式

   复杂度	判断依据	操作
   简单	1–2 个文件，没有行为变更（拼写错误、配置、重命名）	继续执行阶段 1 的第 2 步（环境设置），然后直接实现——无需任务列表或执行循环。如果变更涉及会影响行为的代码，则应用测试发现流程
   小型／中型	范围明确，少于约 10 个文件	根据发现结果创建任务列表。继续执行阶段 1 的第 2 步
   大型	涉及多个方面、需要架构决策、涉及 10 个以上文件，或涉及身份验证／支付／迁移	告知用户，此项工作适合使用 /ce:brainstorm 或 /ce:plan 来梳理边缘情况和范围边界。尊重用户的选择。如果继续，则创建任务列表并继续执行阶段 1 的第 2 步

---

阶段 1：快速开始

1. 阅读计划并澄清问题 （若从阶段 0 的简单提示词进入，则跳过）

   • 完整阅读工作文档
   • 将计划视为决策依据，而非执行脚本
   • 如果计划包含 Implementation Units、Work Breakdown、Requirements Trace、Files、Test Scenarios 或 Verification 等章节，请将其作为执行工作的主要依据
   • 检查每个实现单元是否包含 Execution note——这些内容体现了计划中该单元的执行方式（例如，测试优先或特征分析优先）。创建任务时请记录这些信息。
   • 检查是否有 Deferred to Implementation 或 Implementation-Time Unknowns 章节——这些章节列出规划者有意留待执行期间解决的问题。开始前请先记录，以便在处理过程中参考，避免临时遇到时措手不及
   • 检查是否有 Scope Boundaries 章节——这些内容明确列出了不在目标范围内的事项。如果实现过程中涉及相邻工作，请回头参考这些边界
   • 检查计划中提供的所有参考资料或链接
   • 如果用户在本次会话中明确要求采用 TDD、测试优先或特征分析优先的方式执行，即使计划中没有 Execution note，也要遵从
   • 如果有任何不清楚或含糊之处，现在就提出澄清问题
   • 征得用户同意后再继续
   • 不要跳过这一步——现在提问总比做错东西好

2. 设置环境

   首先，检查当前分支：

   current_branch=$(git branch --show-current)
   default_branch=$(git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's@^refs/remotes/origin/@@')
   
   # Fallback if remote HEAD isn't set
   if [ -z "$default_branch" ]; then
     default_branch=$(git rev-parse --verify origin/main >/dev/null 2>&1 && echo "main" || echo "master")
   fi
   

   如果当前已位于功能分支（而非默认分支）：

   首先，检查分支名称是否有意义——例如 feat/crowd-sniff 或 fix/email-validation 这样的名称能让后续读者了解工作内容。自动生成的工作树名称（例如 worktree-jolly-beaming-raven）或其他含义不明的名称则不符合要求。

   如果分支名称没有意义或由系统自动生成，请建议在继续前重命名：

   git branch -m <meaningful-name>
   

   根据计划标题或工作描述推导新名称（例如 feat/crowd-sniff）。将重命名作为推荐选项，与按当前名称继续并列提供。 然后询问：“继续在 [current_branch] 上工作，还是创建新分支？”

   • 如果继续（无论是否重命名），继续执行第 3 步
   • 如果创建新分支，请按以下选项 A 或 B 操作

   如果当前位于默认分支，请选择后续操作方式：

   选项 A：创建新分支

   git pull origin [default_branch]
   git checkout -b feature-branch-name
   

   根据工作内容取一个有意义的名称（例如，feat/user-authentication、fix/email-validation）。

   选项 B：使用 worktree（并行开发时推荐）

   skill: git-worktree
   # The skill will create a new branch from the default branch in an isolated worktree
   

   选项 C：继续在默认分支上工作

   • 需要获得用户的明确确认
   • 只有在用户明确表示“是，提交到 [default_branch]”后才能继续
   • 未经明确许可，绝不直接向默认分支提交

   建议：以下情况适合使用 worktree：

   • 需要同时处理多个功能
   • 希望在试验时保持默认分支干净
   • 计划频繁切换分支

3. 创建待办列表 (如果阶段 0 已创建待办列表，或阶段 0 将任务判定为琐碎任务，则跳过)

   • 使用可用的任务跟踪工具（例如 TodoWrite、任务列表）将计划拆分为可执行的任务
   • 根据计划中的实现单元、依赖关系、文件、测试目标和验证标准推导任务
   • 如果某个单元包含 Execution note，请将其纳入对应任务
   • 实现每个单元前，先阅读其 Patterns to follow 字段；这些内容指出了需要遵循的具体文件或约定
   • 将每个单元的 Verification 字段作为该任务的主要“完成”信号
   • 不要期待计划包含实现代码、微步骤 TDD 指令或确切的 shell 命令
   • 列出任务之间的依赖关系
   • 按优先顺序安排任务
   • 纳入测试和质量检查任务
   • 确保任务具体且可完成

4. 选择执行策略

   创建任务列表后，根据计划的规模和依赖结构决定如何执行：

   策略	适用情况
   就地执行	1–2 个小任务，或执行过程中需要与用户交互的任务。对于未附带计划的提示，默认采用此策略——这类提示很少能提供足够的结构化上下文来证明应调度子 Agent
   串行子 Agent	3 个或更多存在依赖关系的任务。每个子 Agent 都会获得一个全新的上下文窗口，专注于一个单元，从而避免处理多个任务时上下文质量下降。需要提供计划单元元数据（目标、文件、方法、测试场景）
   并行子 Agent	3 个或更多通过并行安全检查（如下）的任务。同时调度互不依赖的单元，并在其前置任务完成后运行有依赖关系的单元。需要提供计划单元元数据

   并行安全检查——选择并行调度前必须执行：

   1. 根据每个候选单元的 Files: 部分（创建、修改和测试路径）建立文件到单元的映射
   2. 检查是否有交集——同一路径出现在 2 个或更多单元中即表示存在重叠
   3. 如果发现任何重叠，改用串行子 Agent。记录原因（例如，“单元 2 和 4 共用 config/routes.rb——改用串行调度”）。串行子 Agent 仍可隔离上下文窗口，并避免共享目录带来的风险

   即使文件没有重叠，共享工作目录的并行子 Agent 也会面临 Git 索引争用（并发暂存或提交会损坏索引）以及测试干扰（并发测试运行会读取彼此尚未完成的更改）。以下并行子 Agent 约束旨在降低这些风险。 子 Agent 派发使用你可用的子 Agent 或任务生成机制。对于每个单元，向子 Agent 提供：

   • 完整的计划文件路径（用于了解整体上下文）
   • 该单元具体的 Goal、Files、Approach、Execution note、Patterns、Test scenarios 和 Verification
   • 与该单元相关的任何已解决的待定问题
   • 指示其检查该单元的测试场景是否覆盖所有适用类别（正常路径、边缘情况、错误路径、集成），并在编写测试前补齐遗漏

   并行子 Agent 的限制——并行派发单元时（非串行或内联）：

   • 指示每个子 Agent：“不要暂存文件（git add）、创建提交或运行项目测试套件。所有并行单元完成后，由协调器负责测试、暂存和提交。”
   • 这些限制可避免并发子 Agent 之间发生 Git 索引冲突和测试干扰

   **权限模式：**派发子 Agent 时省略 mode 参数，以便应用用户配置的权限设置。不要传递 mode: "auto"——它会覆盖 bypassPermissions 等用户级设置。

   每个子 Agent 完成后（串行模式）：

   1. 检查子 Agent 的差异——确认更改符合该单元的范围和 Files: 列表
   2. 运行相关测试套件，确认工作树状态正常
   3. 如果测试失败，先诊断并修复，再继续——不要在工作树有问题时派发依赖单元
   4. 更新计划复选框和任务列表
   5. 派发下一个单元

   一个并行批次中的所有子 Agent 完成后：

   1. 等待当前并行批次中的每个子 Agent 都完成，再处理任何结果
   2. 交叉检查发现的文件冲突：比较批次中所有子 Agent 实际修改的文件（不只是它们声明的 Files: 列表）。子 Agent 可能会创建或修改计划中未预料到的文件——这是预期情况，因为计划描述的是做什么，而不是怎么做。只有同一批次中有 2 个或更多子 Agent 修改了同一个文件，才算发生冲突。在共享工作目录中，只有最后写入的版本会保留——该文件上其他单元的更改会丢失。如果发现冲突：先提交所有单元中不冲突的文件，然后针对共享文件串行重新运行受影响的单元，使每个单元都基于其他单元已提交的工作继续修改
   3. 对每个已完成的单元，按依赖顺序执行：检查差异、运行相关测试套件、仅暂存该单元的文件，并根据该单元的 Goal 编写符合 Conventional Commits 规范的提交信息
   4. 如果某个单元的更改提交后测试失败，先诊断并修复，再提交下一个单元
   5. 更新计划复选框和任务列表
   6. 派发下一批相互独立的单元，或下一个依赖单元

阶段 2：执行

1. 任务执行循环

   按优先级顺序处理每项任务：

   while (tasks remain):
     - Mark task as in-progress
     - Read any referenced files from the plan or discovered during Phase 0
     - Look for similar patterns in codebase
     - Find existing test files for implementation files being changed (Test Discovery — see below)
     - Implement following existing conventions
     - Add, update, or remove tests to match implementation changes (see Test Discovery below)
     - Run System-Wide Test Check (see below)
     - Run tests after changes
     - Assess testing coverage: did this task change behavior? If yes, were tests written or updated? If no tests were added, is the justification deliberate (e.g., pure config, no behavioral change)?
     - Mark task as completed
     - Evaluate for incremental commit (see below)
   

   如果某个单元包含 Execution note，请遵循其中的要求。对于测试优先的单元，先编写失败的测试，再实现该单元。对于行为刻画优先的单元，在更改前记录现有行为。对于没有 Execution note 的单元，灵活处理。

   执行准则：

   • 采用测试优先方式时，不要在同一步中编写测试和实现
   • 不要跳过验证新测试在实现修复或功能前会失败这一步
   • 采用测试优先方式时，不要超出当前行为范围进行过度实现
   • 对于简单重命名、纯配置和纯样式工作，可跳过测试优先流程 测试发现 — 在实现文件更改之前，先找出其现有测试文件（搜索导入、引用实现文件或命名模式与其相同的测试/规范文件）。如果计划指定了测试场景或测试文件，请从这些内容入手，然后检查计划可能未列出的其他测试覆盖。实现文件的更改应配有相应的测试更新——新行为添加新测试，行为变更修改测试，行为删除则删除或更新测试。

   测试场景完整性 — 在为具有功能的单元编写测试之前，检查计划的 Test scenarios 是否涵盖适用于该单元的所有类别。如果缺少某个类别，或场景描述含糊（例如，“验证正确”却未说明输入和预期结果），请在编写测试前根据该单元自身的上下文补充：

   类别	适用情况	缺少时的推导方法
   正常路径	始终适用于具有功能的单元	阅读单元的 Goal 和 Approach，了解核心输入/输出组合
   边缘情况	单元存在有意义的边界时（输入、状态、并发）	找出边界值、空值/nil 输入和并发访问模式
   错误/失败路径	单元存在失败模式时（验证、外部调用、权限）	列举单元应拒绝的无效输入、应执行的权限/身份验证拒绝，以及应处理的下游故障
   集成	单元跨越多个层时（回调、中间件、多服务）	找出跨层调用链，并编写一个不使用 mock 的场景来覆盖它

   系统级测试检查 — 在将任务标记为完成之前，暂停并自问：

   问题	应采取的措施
   运行时会触发什么？ 回调、中间件、观察者、事件处理器——从你的更改向外追踪两层。	阅读实际代码（而非文档），检查你接触到的模型上的回调、请求链中的中间件，以及 after_* 钩子。
   我的测试是否覆盖真实调用链？ 如果每个依赖都被 mock，测试只能证明你的逻辑单独运行时有效——无法说明交互情况。	至少编写一个使用真实对象并贯穿完整回调/中间件调用链的集成测试。交互涉及的层不要使用 mock。
   失败会留下孤立状态吗？ 如果代码在调用外部服务之前持久化了状态（数据库行、缓存、文件），服务失败时会发生什么？重试会创建重复项吗？	使用真实对象追踪失败路径。如果在高风险调用前创建了状态，就测试失败时是否会清理，或重试是否具备幂等性。
   还有哪些接口会暴露此功能？ Mixins、DSL、替代入口（Agent、Chat、ChatMethods）。	在相关类中搜索该方法/行为。如果需要保持一致性，现在就补上，而不是留待后续。
   各层的错误处理策略是否一致？ 重试中间件 + 应用层回退 + 框架错误处理——它们是否会冲突或造成重复执行？	列出各层的具体错误类。确认 rescue 列表与底层实际抛出的错误相符。

   何时跳过： 叶节点更改，没有回调、状态持久化或并行接口。如果更改纯属增量（新增辅助方法、新增视图 partial），这项检查只需 10 秒，结论就是“没有触发项，跳过”。

   最需要关注的情况： 涉及带回调的模型、带回退/重试的错误处理，或通过多个接口暴露的功能的任何更改。

2. 增量提交

   完成每项任务后，评估是否创建增量提交：

   提交时机……	不要提交的时机……
   一个逻辑单元已完成（模型、服务、组件）	只是更大单元的一小部分
   测试通过且有实质进展	测试失败
   即将切换上下文（后端 → 前端）	纯脚手架，没有实际行为
   即将尝试有风险或不确定的更改	需要使用“WIP”提交消息

   判断原则：“我能写出一条描述完整且有价值的更改的提交消息吗？如果可以，就提交。如果消息只能写成‘WIP’或‘部分 X’，就先等等。”

   如果计划中有 Implementation Units，可以将它们作为划分提交边界的起点，但要根据实现过程中发现的情况灵活调整。如果某个单元比预期更大，可能需要拆成多个提交；如果几个相关的小单元，也可以合并提交。使用各单元的 Goal 来构思提交消息。

   提交工作流：

   # 1. Verify tests pass (use project's test command)
   # Examples: bin/rails test, npm test, pytest, go test, etc.
   
   # 2. Stage only files related to this logical unit (not `git add .`)
   git add <files related to this logical unit>
   
   # 3. Commit with conventional message
   git commit -m "feat(scope): description of this unit"
   

   **处理合并冲突：**如果在变基或合并期间出现冲突，请立即解决。增量提交能让冲突更容易解决，因为每个提交都小而集中。

   **注意：**增量提交使用简洁规范的消息，不带署名页脚。最终的 Phase 4 提交/PR 会包含完整署名信息。

   **并行子 Agent 模式：**当各单元由并行子 Agent 执行时，子 Agent 不提交；整个并行批次完成后，由协调器负责暂存和提交（参见 Phase 1 Step 4 中的并行子 Agent 约束）。本节的提交指导适用于内联和串行执行，也适用于并行批次完成后协调器的提交决策。

3. 遵循现有模式

   • 计划应引用相似代码——先阅读这些文件
   • 严格遵循命名约定
   • 尽可能复用现有组件
   • 遵循项目编码规范（参见 AGENTS.md；仅当代码库仍保留兼容性垫片时才使用 CLAUDE.md）
   • 不确定时，搜索相似实现

4. 持续测试

   • 每次重大更改后运行相关测试
   • 不要等到最后才测试
   • 立即修复失败
   • 为新行为添加测试，为行为变更更新测试，为已删除行为移除测试
   • **使用模拟对象的单元测试可以验证逻辑是否独立成立。使用真实对象的集成测试可以验证各层是否协同工作。**如果更改涉及回调、中间件或错误处理，则两种测试都需要。

5. 边做边简化

   完成一组相关的实施单元（或每完成 2–3 个单元）后，检查最近修改的文件，寻找简化机会——合并重复模式、提取共享辅助函数，并提高代码复用率和效率。使用子 Agent 时，这尤其有价值，因为每个 Agent 都在隔离的上下文中工作，无法发现各单元之间逐渐显现的模式。

   不要在每个单元完成后都进行简化——早期看似重复的模式，之后可能会有意分化。等到自然的阶段边界，或发现复杂性累积时再简化。

   如果有 /simplify 技能或同等工具，请使用。否则，请自行检查已修改的文件，寻找复用和整合机会。

6. Figma 设计同步（如适用）

   对于采用 Figma 设计的 UI 工作：

   • 按照设计规范实现组件
   • 迭代使用 figma-design-sync Agent 进行对比
   • 修复发现的视觉差异
   • 重复以上步骤，直至实现与设计一致

7. 跟踪进度

   • 随任务完成及时更新任务列表
   • 记录阻碍因素或意外发现
   • 如果范围扩大，创建新任务
   • 及时向用户通报重大里程碑

Phase 3-4：质量检查与交付

Phase 2 的所有任务完成并进入质量检查阶段后，请阅读 references/shipping-workflow.md，了解完整的交付工作流：质量检查、代码审查、最终验证、PR 创建和通知。

核心原则

快速启动，更快执行

• 开始时澄清一次，然后立即执行
• 不要等到完全理解后才行动——提出问题并继续推进
• 目标是完成这个功能，而不是打造完美的流程

计划是你的指南

• 工作文档应引用类似的代码和模式
• 查看这些参考内容并遵循它们
• 不要另起炉灶——与现有实现保持一致

边做边测试

• 每次更改后都运行测试，不要等到最后
• 立即修复失败
• 持续测试，避免出现重大意外

质量融入整个过程

• 遵循现有模式
• 为新代码编写测试
• 推送前运行 lint
• 审查每项更改——简单的增量工作可进行行内审查，其他情况都进行全面审查

交付完整功能

• 完成所有任务后再继续
• 不要留下完成度只有 80% 的功能
• 能交付的已完成版本，胜过无法交付的完美版本

应避免的常见陷阱

• 分析瘫痪——不要过度思考，阅读计划并执行
• 跳过澄清问题——现在就问，不要等到做错了再问
• 忽略计划中的参考内容——计划中附上链接是有原因的
• 最后才测试——持续测试，否则之后就要吃苦头
• 忘记跟踪进度——边做边更新任务状态，否则就会忘记哪些已经完成
• 完成度只有 80% 综合征——完成这个功能，不要过早转向其他任务
• 跳过审查——每项更改都要审查，只是审查深度不同