V4 Best Practices
Agent Buildingv4-best-practicesV4 Best Practices is an Agent Skill for agent building published in the Hmbown/CodeWhale repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
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.
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/Hmbown/CodeWhale/blob/HEAD/crates/tui/assets/skills/v4-best-practices/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/v4-best-practices, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
V4 Best Practices
Rules for multi-step V4 thinking-mode workflows. Each rule prevents a specific, observable failure class.
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.