CodeWhale v4-best-practices：V4 thinking 模式多步 Agent 工作流

一句话结论

一份社区 Agent skill：为 V4 thinking 模式的多步任务定义了 3 条可执行规则——引用前先验证、多文件执行前派 flash 子代理核查、计划输出必须带 path:line——每条对应一个可观察的失败类。

适用场景

• 适合的任务：用 V4-Pro 做多文件、多步编码规划/执行；防止编辑不存在的路径、幻觉符号、计划模糊导致执行落空；有 grep/read 工具的 Agent 环境。

• 不适合的任务：单文件小改、无需计划的简单问答；没有文件搜索/读取工具的环境（规则 1、3 依赖 grep_files/read_file）；thinking 关闭的纯生成场景。

• 适用的模型版本：deepseek-v4-pro（主模型）、deepseek-v4-flash（核查子代理，thinking 关闭）。

• 适用的客户端、Agent 或 API：支持子代理（sub-agent）与工具调用的 Agent 框架；原文示例为类 Claude Code/CodeWhale 的 agent 语法。

• 推荐的推理档位和参数：主模型 thinking 开启；子代理用 flash 且 thinking 关闭，以低成本做核查。

可直接使用的内容

完整规则正文（原文，采集时逐字核对）：

## 1. Verify references before writing
Before referencing a file path, function, or type in code or plan output,
call `grep_files` or `read_file` to confirm it exists in the workspace.

# Bad:  edit_file path="src/config/loader.rs" (assumed from memory)
# Good: grep_files pattern="pub fn load_config" → confirms src/config/mod.rs:42
#        then reference src/config/mod.rs:42

Failure avoided: `edit_file` errors on non-existent paths; LSP diagnostics
on hallucinated symbols.

## 2. Spawn a verifier sub-agent before multi-file execution
Before executing a plan that touches 3+ files, spawn a `deepseek-v4-flash`
sub-agent (thinking off) to read the target files and confirm path/symbol
assumptions still hold.

agent type="verifier" model="deepseek-v4-flash"
  prompt: "Read these files and confirm: [list assumptions]. Report mismatches."

Failure avoided: multi-step edits fail partway because file structure
changed since the plan was drafted.

## 3. Plan output must use confirmed path:line references
In plan-mode output, replace vague location pointers with `path:line`
references drawn from a prior `grep_files` result.

# Bad:  "Update the retry logic in the client module"
# Good: "Update retry loop at crates/tui/src/client.rs:187"

Failure avoided: agent-mode execution cannot locate the intended edit
target when plan directions are imprecise.

测试/工作流步骤

1. 触发条件：模型处于 thinking 模式、任务为多步或计划驱动时启用本 skill。

2. 写代码或计划前，凡引用路径/函数/类型，先 grep_files 或 read_file 核实（规则 1）。

3. 计划涉及 3 个以上文件时，先派一个 deepseek-v4-flash、thinking 关闭的 verifier 子代理，逐条确认假设并回报不一致（规则 2）。

4. 计划输出一律使用核实过的 path:line 引用，禁止模糊位置描述（规则 3）。

5. 执行后再核对：编辑是否落在目标文件/行、是否有幻觉符号，若有失败按规则定位失败类并修正。

原始证据与数据

• SKILL.md 完整内容约 1.7KB，仅含上述 3 条规则；每条自带 Bad/Good 示例和“Failure avoided”说明。

• 文件 frontmatter 声明适用条件：“Use when working with deepseek-v4-pro or deepseek-v4-flash in thinking mode on multi-step or plan-driven tasks”。

• 项目为开源仓库，本文件为仓库内内置 skill 资产；未附 benchmark 或实测结果，规则效果需自行验证。

适用边界

• 社区项目内嵌 skill，非 DeepSeek 官方；grep_files/edit_file/agent type= 等语法是项目自身约定，迁移到其它 Agent 需改写。

• 规则针对“多步、计划驱动”失败类设计，不覆盖对话质量、创意或单文件任务。

• 未公开这些规则在真实项目上的成功率数据；3 条规则是经验性约束，不是经过统计验证的评测结论。

来源摘录或观察（仅做合规短引）

文件自述：“Rules for multi-step V4 thinking-mode workflows. Each rule prevents a specific, observable failure class.”