cook-hard

[IMPORTANT] 开始之前，请使用 TaskCreate 将所有工作拆分为小任务——包括为每个文件的读取创建任务。这样可以避免因长文件导致上下文丢失。对于简单任务，AI 必须主动询问用户是否要跳过。

批判性思维 — 运用批判性思维和顺序思维。每项断言都必须有可追溯的证据，置信度超过 80% 才能采取行动。 防止幻觉： 切勿把猜测当作事实陈述——为每项断言注明来源，坦然承认不确定性，自查输出是否有误，独立交叉验证，对自己的判断保持怀疑——没有证据的确信是所有幻觉的根源。

防止 AI 出错 — 每项任务都要避免以下失误：

• 删除前检查下游引用。 删除组件会导致文档和代码连锁过时。移除前应梳理所有引用该组件的文件。
• 根据实际代码核验 AI 生成的内容。 AI 会凭空编造 API、类名和方法签名。记录或引用之前，务必使用 grep 确认其确实存在。
• 编辑后追踪完整的依赖链。 修改定义时，容易遗漏由此派生的下游变量和使用方。务必追踪完整链路。
• 验证正确性时追踪所有代码路径。 确认代码存在，不代表确认代码会执行。务必追踪提前退出、错误分支和条件跳过的情况，而不只是顺利路径。
• 调试时，先问“问题该由哪一方负责？”。 追踪问题是出在调用方（数据错误）还是被调用方（处理错误）。在应负责的层级修复——切勿只修补症状出现的位置。
• 假定现有值是有意设定的——修改前先问“为什么？”。 修改任何常量、限制、标志或模式前：阅读注释、查看 git blame、检查周边代码。
• 核验所有受影响的输出，而不只是第一个。 涉及多个技术栈的改动需要核验每一项输出。一个检查通过不代表所有检查都通过。
• 先整体、后局部地调试——避免只关注最近注意到的问题。 调查任何故障时，先列出所有前置条件（配置、环境变量、数据库名称、端点、DI 注册、数据前置条件），再逐项根据证据核验，之后才能对代码层面的问题作出假设。
• 精准修改——执行差异检查。 修复错误时，每一处改动都必须能直接对应到该错误。不要顺便调整或改进相邻代码。增强任务：实现改进，并明确说明改进内容。
• 编码前先指出歧义——不要默默自行选择。 如果请求有多种解释，应列出每种解释及其工作量估算并询问用户。切勿擅自假设应处理所有记录、采用基于文件的方案或选择更复杂的路径。

先理解代码 — 严格门槛：在阅读现有代码之前，不得编写、规划或修复。

1. 搜索至少 3 个相似模式（grep/glob）——引用 file:line 作为证据
2. 阅读目标区域中的现有文件——理解其结构、基类和约定
3. 如果 .code-graph/graph.db 存在，则运行 python .claude/scripts/code_graph trace <file> --direction both --json
4. 通过 connections 或 callers_of 梳理依赖关系——了解哪些内容依赖目标
5. 对于非简单任务（涉及 3 个以上文件），将调查结果写入 .ai/workspace/analysis/
6. 实现前重新阅读分析文件——切勿只凭记忆开展工作
7. 现有模式可用时，绝不要另创模式——应严格遵循，或说明偏离的原因

解除阻塞条件： - [ ] 已阅读目标文件 - [ ] 已 grep 至少 3 个模式 - [ ] 已追踪代码图（如果存在 graph.db） - [ ] 已用证据核实假设

• docs/project-reference/domain-entities-reference.md — 领域实体目录、关系和跨服务同步（任务涉及业务实体/模型时阅读）（内容由钩子自动注入——阅读前检查是否有 [Injected: ...] 标头）
• docs/specs/ — 按模块划分的测试规范（阅读现有 TC；实现后通过 /tdd-spec 生成/更新测试规范）

计划质量 — 每个计划阶段都必须注意包含测试规范。

1. 在每个阶段文件中添加 ## Test Specifications 部分，并使用 TC-{FEAT}-{NNN} ID
2. 将每项功能需求映射到至少 1 个 TC（或明确标记为 TBD 并说明理由）
3. TC ID 遵循 TC-{FEATURE}-{NNN} 格式 — 按 ID 引用，绝不嵌入完整内容
4. 执行任何新的工作流步骤之前：调用 TaskList 并重新读取阶段文件
5. 上下文压缩时：首先调用 TaskList — 绝不创建重复任务
6. 标记阶段完成之前，验证 TC 是否满足（证据必须为 file:line，不能是 TBD）

模式： TDD 优先 → 使用 Evidence: TBD 引用现有 TC。实现优先 → 使用 TBD → /tdd-spec 完成后续补充。

技能变体： /cook 的变体 — 彻底实施并进行最高级别的验证。

快速摘要

目标： 通过深入研究、全面规划和最高质量的验证来实现功能。

工作流：

1. 研究 — 使用多个研究员子 Agent 进行深入调查
2. 规划 — 使用 /plan-hard 制定详细计划，并要求用户批准
3. 实施 — 执行并进行完整的代码审查和 SRE 审查
4. 验证 — 运行所有测试、审查变更并更新文档

关键规则：

• 力求最全面：研究 → 规划 → 实施 → 审查 → 测试 → 文档
• 规划阶段必须获得用户批准
• 将工作拆分为待办任务；添加最终自我审查任务

前端/UI 上下文（如适用）

当此任务涉及前端或 UI 变更时，

UI 系统上下文 — 对于涉及 .ts、.html、.scss 或 .css 文件的任何任务：

实施之前必须阅读：

1. docs/project-reference/frontend-patterns-reference.md — 组件基类、存储、表单
2. docs/project-reference/scss-styling-guide.md — BEM 方法、SCSS 变量、混入、响应式设计
3. docs/project-reference/design-system/README.md — 设计令牌、组件清单、图标

项目专属路径请参考 docs/project-config.json。

• 组件模式：docs/project-reference/frontend-patterns-reference.md
• 样式/BEM 指南：docs/project-reference/scss-styling-guide.md
• 设计系统令牌：docs/project-reference/design-system/README.md

深入思考，以最高级别的验证来规划和实施这些任务：

保持质疑。运用批判性思维和顺序思维。每项主张都必须有可追溯的证据和置信度百分比（想法的置信度应高于 80%）。

$ARGUMENTS

模式： HARD — 加强研究、详细规划、强制审查。

工作流

1. 深度研究阶段

• 并行启动 2-3 个 researcher 子 Agent，分别涵盖：
  • 技术方案验证
  • 边缘情况和故障模式
  • 安全影响
  • 性能考量
• 使用 /scout-ext 全面分析代码库
• 生成研究报告（每份最多 150 行）
• 外部记忆：将所有研究内容写入 .ai/workspace/analysis/{task-name}.analysis.md。规划前重新阅读整个文件。

图谱辅助调查 — 当 .code-graph/graph.db 存在时，必须执行。

**硬性门槛：**在结束任何调查前，必须至少对关键文件运行一条图谱命令。

**模式：**Grep 查找文件 → trace --direction both 揭示完整系统流程 → Grep 验证详情

任务	最低图谱操作
调查/侦察	对 2-3 个入口文件运行 trace --direction both
修复/调试	对有问题的函数运行 callers_of + tests_for
功能/增强	对要修改的文件运行 connections
代码审查	对已更改的函数运行 tests_for
影响范围	运行 trace --direction downstream

CLI：python .claude/scripts/code_graph {command} --json。先使用 --node-mode file（噪声减少 10-30 倍），再使用 --node-mode function 查看详情。

实现完成后，对已修改的文件运行 python .claude/scripts/code_graph connections <file> --json，确认无需更新相关文件。

实施前进行图谱追踪

当图谱数据库可用时，在编写代码前进行追踪，以了解影响范围：

• python .claude/scripts/code_graph trace <file-to-modify> --direction both --json — 查看哪些代码会调用此代码，以及它会触发什么
• python .claude/scripts/code_graph trace <file-to-modify> --direction downstream --json — 查看所有下游使用方
• 这可以防止破坏隐式依赖（总线消息使用方、事件处理程序）

2. 全面规划

• 使用 planner 子 Agent，提供所有研究报告
• 创建完整的计划目录，其中包含：
  • plan.md - 概述及风险评估
  • phase-XX-*.md - 详细的阶段文件
  • 每个阶段的成功标准
  • 回滚策略

3. 经验证的实施

• 每次只实施一个阶段
• 每个阶段完成后：
  • 运行类型检查和编译
  • 运行相关测试
  • 继续前进行自我审查

大型计划的批次检查点

对于包含 10 项或更多任务的计划，分批执行并接受人工审查：

1. 执行批次 — 完成接下来的 3 项任务（或用户指定的批次大小）
2. 报告 — 展示已实施的内容、验证输出以及任何顾虑
3. 等待 — 说“准备好接收反馈”，然后停止。不要自动继续。
4. 应用反馈 — 纳入修改，然后执行下一批次
5. 重复，直到所有任务完成

对于包含 10 项或更多任务的计划，不要不设检查点就连续执行所有任务。 每个批次完成后都要停止，等待人工审查。这样可以防止执行失控，避免早期错误在后续任务中不断累积。

4. 强制测试

• 使用 tester 子 Agent 完成全面测试覆盖
• 为以下场景编写测试：
  • 正常路径场景
  • 研究中发现的边缘情况
  • 错误处理路径
• 不允许使用 mock 或伪造数据
• 重复测试，直到所有测试通过

5. 强制代码审查

• 使用 code-reviewer 子 Agent
• 处理所有严重和主要问题
• 修复后重新运行测试
• 重复审查，直到获批

6. 更新文档

• 使用 docs-manager 更新相关文档
• 使用 project-manager 更新项目状态
• 记录所有架构决策

7. 最终报告

• 总结所有更改
• 测试覆盖率指标
• 已处理的安全考量
• 尚未解决的问题（如有）
• 请用户审查并批准

适用场景

• 关键生产功能
• 安全敏感变更
• 公共 API 修改
• 数据库架构变更
• 跨服务集成

质量门槛

门槛	标准
研究	至少 2 份研究报告
规划	完整的计划目录
测试	全部通过，不使用模拟对象
审查	没有严重或主要问题
文档	按需更新

---

后续步骤（独立运行：必须使用 AskUserQuestion 询问用户。如果处于工作流中则跳过。）

强制重要提醒 — 必须执行，无一例外： 如果此技能是在工作流之外调用的，你必须使用 AskUserQuestion 提供以下选项。不要因为任务看起来“简单”或“显而易见”而跳过——由用户决定：

• “继续完整工作流（推荐）” — 我会从此处（功能已实现）开始，判断最合适的后续工作流。这可确保不会跳过审查、测试和文档步骤。
• “/code-simplifier” — 简化并清理实现
• “/workflow-review-changes” — 在提交前审查变更
• “跳过，手动继续” — 由用户决定

如果已经处于工作流中，则跳过——工作流会处理步骤安排。

收尾提醒

• 强制重要提醒：开始前，使用 TaskCreate 将工作拆分为小型待办任务

• 强制重要提醒：编写新代码前，在代码库中搜索至少 3 个相似模式

• 强制重要提醒：每项主张都必须引用 file:line 作为依据（置信度 >80% 才可采取行动）

• 强制重要提醒：添加最终审查待办任务，以验证工作质量

• 强制重要提醒：使用 AskUserQuestion 与用户确认决策——绝不自行决定 强制重要提醒：开始前阅读以下文件：

• 强制重要提醒：任何修改前，搜索至少 3 个现有模式并阅读代码。如果存在 graph.db，则运行图追踪。

• 强制重要提醒：按阶段包含带 TC ID 的 ## Test Specifications。创建新任务前调用 TaskList。

• 强制重要提醒：进行任何 UI 变更前，阅读 frontend-patterns-reference、scss-styling-guide 和 design-system/README。

• 强制重要提醒：如果存在 graph.db，则对关键文件至少运行一条图命令。模式：grep → graph trace → grep 验证。

• 必须提醒：保持批判性思维——每项主张都需要可追溯的证据，置信度 >80% 才可采取行动。防止幻觉：绝不将猜测当作事实。

• 必须提醒：落实 AI 错误预防——优先整体排查，在责任层修复，在编码前明确歧义，压缩后重新阅读文件。

[TASK-PLANNING] 行动前，分析任务范围，并使用 TaskCreate 系统地将任务拆分为小型待办任务和子任务。