task

任务 — 系统化实现工作流

Codex 兼容性

在 Codex 中运行此技能时，执行前将 Claude Code 专属原语转换为对应工具：AskUserQuestion -> chat/request_user_input，TodoWrite -> update_plan，在可用且允许的情况下，Task/TaskCreate/TeamCreate/SendMessage -> spawn_agent/send_input/wait_agent，EnterPlanMode/ExitPlanMode -> 简洁的聊天计划并明确征求批准。 将 Read/Write/Edit/Bash/WebSearch/WebFetch 转换为 Codex 文件/终端/网页工具；除非任务明确针对 Claude Code，否则将 ~/.claude/... 路径映射到 ~/.agents/... 或 ~/.codex/...。

Cursor 兼容性

在 Cursor Agent 中运行此技能时，执行前将 Claude Code 专属原语转换为对应工具：AskUserQuestion -> AskQuestion；TodoWrite -> Cursor TodoWrite 或等效清单；Task/TaskCreate/TeamCreate/SendMessage/多 Agent 工作流 -> 在允许的情况下使用 Cursor Task（子 Agent）、并行 Tasks 或 run_in_background（TeamCreate/SendMessage 可能没有完全对应的工具）；EnterPlanMode/ExitPlanMode -> Plan 模式（SwitchMode / CreatePlan）并明确征求用户批准。 通过 Cursor Composer 或 Agent 的对应工具使用 Read/Write/Edit/StrReplace/Bash/网页/搜索/MCP。通常将写作形式为 mcp__server__tool 的 MCP 名称映射到配置的服务标识符，并通过 call_mcp_tool 调用。除非任务明确针对 Claude Code，否则将 ~/.claude/... 映射到 ~/.cursor/skills/、.cursor/skills/ 和 .cursor/rules/。

适用于所有实现任务的标准 5 阶段工作流，内置质量关卡。

<essential_principles>

Serena 思考检查点（强制）

在指定时间点调用以下 Serena 工具。不得跳过。

检查点	工具	时间	目的
遵循性关卡	mcp__serena__think_about_task_adherence	第 3 阶段每次编辑代码之前	确认工作仍与原始任务一致
完成关卡	mcp__serena__think_about_whether_you_are_done	退出第 4 阶段（验证）之前	确认所有工作确已完成

第 1 阶段之后以及第 2 阶段之后，都要用文字进行简短的信息充分性自检（已理解需求、已找到相关代码、计划涵盖验收标准和验证方式）。如果仍有缺口，应先收集更多上下文再继续，不要依赖已移除的 Serena 工具。

内省标记（始终启用）

在所有阶段中使用以下标记，让推理过程可见：

• 🤔 推理 — “🤔 该错误表明缺少依赖项”
• 🎯 决策 — “🎯 选择方案 A 而非 B，因为……”
• ⚡ 性能 — “⚡ 此查询可能导致 N+1 问题”
• 📊 质量 — “📊 正在检查与现有模式的一致性”
• 💡 洞察 — “💡 此模式可以复用……”

安全规则

• 执行破坏性操作之前（删除、覆盖、重置）：始终先向用户确认
• 编辑代码之前：调用 think_about_task_adherence
• 绝不自动提交：第 5 阶段等待用户指示后再提交/推送
• 必须通过质量关卡：第 4 阶段通过后才能进入第 5 阶段

</essential_principles>

第 1 阶段：调查

理解任务并收集上下文。

1. 从用户输入中解析任务要求
2. 阅读相关代码文件（Grep、Read、Serena 符号工具）
3. 必要时使用 Context7 检查外部库
4. 找出现有模式和约定
5. 信息充分性自检 — 确认你理解任务、已查看相关代码路径，并充分了解项目约定以制定计划。如果还不充分，请继续阅读，或在进入第 2 阶段前询问用户。

工具：Grep、Read、Glob、mcp__serena__find_symbol、mcp__serena__get_symbols_overview、mcp__context7__query-docs

阶段 2：规划

拆解任务并设计解决方案。

1. 使用 TodoWrite 创建任务拆解
2. 确定可并行的步骤：Plan: 1) Parallel [Read A, B] → 2) Edit → 3) Parallel [Test, Lint]
3. 将计划保存到 Serena Memory：mcp__serena__write_memory("plan_<topic>", content)
4. 计划完整性自检 — 确认计划和待办事项涵盖验收标准、边缘情况以及验证变更的方式。如有重要遗漏，请修订计划。

输出：为每个步骤创建清晰列明验收标准的 TodoWrite 条目。

阶段 3：实施

执行计划，并持续检查是否遵循要求。

对每个实施步骤：

1. 将 TodoWrite 条目标记为进行中
2. 🔶 think_about_task_adherence — 是否仍在按计划推进？
3. 编辑代码（Edit、Write）
4. 使用内省标记（🤔🎯⚡📊💡）说明推理过程
5. 将 TodoWrite 条目标记为已完成

规则：

• 不要使用 // TODO: implement later——应编写可运行的代码
• 除测试外，不要使用模拟对象
• 遵循现有代码模式和约定
• 执行破坏性操作前，先征得用户确认

阶段 4：验证

运行质量检查并验证正确性。

标准验证（始终执行）

尽可能并行运行：

# Parallel execution
pnpm lint &
pnpm typecheck &
pnpm test &
pnpm build &
wait

如果任何检查失败 → 调查根本原因 → 在阶段 3 中修复 → 重新验证。

--frontend-verify（提供此标志时）

跨平台进行可视化验证。根据 package.json 自动检测平台：

依赖项	平台	预检	验证工具
(default)	Web	kill-port <port> && pnpm dev	playwright-cli（open --headed、snapshot、screenshot）
electron	Electron	pnpm electron:dev	/qa-electron 技能（连接到 Electron CDP 的 playwright-cli）
expo / react-native	Mobile	mcp__ios-simulator__open_simulator	iOS Simulator MCP（screenshot、ui_tap、ui_swipe）
commander / inquirer / oclif	CLI	shell session	Shellwright MCP（TUI/CLI 操作和输出验证）

前端验证工作流：

0. 预检知识：调用 /dnd 加载拖放坐标协议。在 dnd-kit 等类似库中，基于引用的 drag 会错误地报告成功——在进行任何 Web 或 Electron 交互前必须先执行此步骤。
1. 预检：运行 kill-port <port> && pnpm dev，确认 playwright-cli 可用（Web 直接使用；Electron 使用 playwright-cli attach --cdp=http://localhost:9222）
2. 创建场景：根据变更设计测试场景，并保存到 Serena Memory
3. 执行：通过 playwright-cli 运行每个场景，并在每个步骤后截图
4. 判断：全部通过 → 继续。任何失败 → 返回阶段 3

前端验证的身份验证

验证需要身份验证的应用（SaaS 仪表盘、管理面板、受 OAuth 保护的页面）时，使用 playwright-cli 的身份验证持久化功能：

策略	命令	适用场景
state-save / state-load	playwright-cli state-save auth.json	会话 Cookie + localStorage。适用于大多数 Web 应用
--profile <dir>	playwright-cli open <url> --profile ./browser-data	完整的 Chromium 用户数据目录。适用于复杂的 OAuth（Google、GitHub SSO）

OAuth 流程：

1. playwright-cli open <login-url> --headed（OAuth 重定向必须使用有头模式）
2. 手动完成 OAuth，或通过 snapshot + fill + click 完成
3. 运行 playwright-cli state-save auth.json 持久化会话
4. 后续运行：导航到应用前，先运行 playwright-cli state-load auth.json

安全性：

• 将 auth.json、browser-data/ 添加到 .gitignore
• 状态文件包含会话密钥——应按凭据处理
• 初次设置 OAuth 时使用 --headed（重定向需要可见浏览器）

完成关卡

🔶 think_about_whether_you_are_done — 是否确实已全部完成？

阶段 5：完成

报告结果并等待用户指示。

1. 向用户提供验证摘要：
   • 更改内容（文件、函数）
   • 测试结果
   • 截图（如果使用了 --frontend-verify）
2. 更新 TodoWrite — 将所有项目标记为已完成
3. ⏸️ 等待用户指示以提交/推送
4. 经用户确认后：git commit && git push

快速参考

/task fix the login button styling
/task add dark mode support --frontend-verify
/task refactor the API error handling

阶段流程图

[Investigate] → 🔶 info gate
     ↓
  [Plan] → 🔶 info gate
     ↓
[Implement] → 🔶 adherence gate (per edit)
     ↓
 [Verify] → 🔶 completion gate
     ↓
[Complete] → ⏸️ wait for user → commit/push