ai-tool-directive

AI Tool Directive

AI coding tools default to adding code, not removing it. A directive that does not explicitly forbid layering will get layering. Write the prompt as a contract with evidence, scope walls, and a checklist you will personally verify.

The 7 patterns

Every directive uses all seven. Order matters: the anti-layering line comes first because it is the instruction most often violated.

1. Anti-layering declaration. Open with: DO NOT ADD NEW CODE ON TOP OF OLD CODE. REMOVE THE OLD CODE.
2. Evidence-first problem statement. Lead with counts, line numbers, error text. Evidence anchors the fix to reality.
3. Numbered discrete tasks. Each task carries: file path, current behavior, required change, implementation guidance.
4. Scope boundary in ALL CAPS. Example: THIS IS A DATABASE-SIDE FIX. DO NOT TOUCH FRONTEND CODE.
5. Anti-instruction section. A WHAT NOT TO DO: block listing the specific wrong moves this tool has made or will make: new caching layers, wrappers around existing code, swapping webhooks for polling.
6. Recurrence signal. If this was diagnosed before: THIS HAS BEEN DIAGNOSED BEFORE AND NEVER FIXED. FIX IT THIS TIME.
7. Human-verified checklist. End with VERIFICATION CHECKLIST (I will check all of these): and concrete boxes: old code deleted (not commented out), build passes with zero errors, no new files created.

Templates

Read references/templates.md when you know the failure shape. Four skeletons, each combining patterns 1-7 tuned to the failure mode:

• fix-broken-system: active breakage (failing cron, auth bypass)
• dedup-and-cleanup: duplication and dead code removal
• performance-fix: unnecessary compute or network
• database-cleanup: triggers, cron, migrations

Good vs bad

Bad problem statement: "The polling system is broken."

Good problem statement: "265 runs in 48 hours, 265 failures. TypeError at src/services/sync.ts:142."

The bad version invites the tool to guess the problem and invent a solution. The good version pins the fix to one line and one error.

Verification

Do this after the tool reports done: search the repo for the old symbol or code path named in the directive. Expect zero hits outside tests and changelogs. If the old code is still present, commented out, or renamed but alive, the directive failed. Re-issue with pattern 1 escalated: name the exact lines to delete and add "commented-out code counts as not deleted" to the checklist.

Then run the build. Expect zero errors and zero new files beyond those the directive authorized. If new files appeared, add them to the WHAT NOT TO DO block and re-run.

Completion checklist

• [ ] Directive opens with the anti-layering declaration
• [ ] Problem statement contains at least one count, path, or error message
• [ ] Every task names a file path and the current behavior
• [ ] Scope boundary states what must not be touched
• [ ] WHAT NOT TO DO block lists the plausible wrong moves
• [ ] Verification checklist has only observable checks (grep, build, file count)
• [ ] You personally ran the checklist after the tool finished

Any box unchecked: not done. Fix or say so.

Footguns

• Vague evidence produces invented fixes. "It's slow" gets a caching layer. Fix: measure first, put the number in the directive.
• Missing scope wall invites drive-by refactors. Fix: pattern 4, and list untouchable directories by path.
• Checklist items the tool self-certifies. "Code is clean" is not checkable. Fix: only checks you can run yourself: grep output, exit codes, file diffs.
• Reusing a directive without updating evidence. Stale line numbers send the tool to the wrong place. Fix: refresh paths and counts every issue.