| 1 | --- |
| 2 | name: v4-best-practices |
| 3 | description: Use when working with deepseek-v4-pro or deepseek-v4-flash in thinking mode on multi-step or plan-driven tasks. Provides rules to prevent stale references, unverified plan assumptions, and vague plan output. |
| 4 | --- |
| 5 | |
| 6 | # V4 Best Practices |
| 7 | |
| 8 | Rules for multi-step V4 thinking-mode workflows. Each rule prevents a |
| 9 | specific, observable failure class. |
| 10 | |
| 11 | ## 1. Verify references before writing |
| 12 | |
| 13 | Before referencing a file path, function, or type in code or plan output, |
| 14 | call `grep_files` or `read_file` to confirm it exists in the workspace. |
| 15 | |
| 16 | ``` |
| 17 | # Bad: edit_file path="src/config/loader.rs" (assumed from memory) |
| 18 | # Good: grep_files pattern="pub fn load_config" → confirms src/config/mod.rs:42 |
| 19 | # then reference src/config/mod.rs:42 |
| 20 | ``` |
| 21 | |
| 22 | Failure avoided: `edit_file` errors on non-existent paths; LSP diagnostics |
| 23 | on hallucinated symbols. |
| 24 | |
| 25 | ## 2. Spawn a verifier sub-agent before multi-file execution |
| 26 | |
| 27 | Before executing a plan that touches 3+ files, spawn a `deepseek-v4-flash` |
| 28 | sub-agent (thinking off) to read the target files and confirm path/symbol |
| 29 | assumptions still hold. |
| 30 | |
| 31 | ``` |
| 32 | agent type="verifier" model="deepseek-v4-flash" |
| 33 | prompt: "Read these files and confirm: [list assumptions]. Report mismatches." |
| 34 | ``` |
| 35 | |
| 36 | Failure avoided: multi-step edits fail partway because file structure |
| 37 | changed since the plan was drafted. |
| 38 | |
| 39 | ## 3. Plan output must use confirmed path:line references |
| 40 | |
| 41 | In plan-mode output, replace vague location pointers with `path:line` |
| 42 | references drawn from a prior `grep_files` result. |
| 43 | |
| 44 | ``` |
| 45 | # Bad: "Update the retry logic in the client module" |
| 46 | # Good: "Update retry loop at crates/tui/src/client.rs:187" |
| 47 | ``` |
| 48 | |
| 49 | Failure avoided: agent-mode execution cannot locate the intended edit |
| 50 | target when plan directions are imprecise. |
| 51 |