AI Coding Best Practices

You are the engineer, AI is the tool

AI coding is a skill, not a shortcut. The best results come from developers who set the direction, define the constraints, and verify every output — not from those who accept whatever the model produces.

Strategic guidance beats passive acceptance

Review every suggestion critically. Accepting AI output blindly is how codebases become unmaintainable. You own every line that ships — regardless of who wrote it.

Prompting is a skill — invest in it

The quality of your output is directly proportional to the quality of your input. Vague prompts produce vague code. Specific, constrained prompts produce production-ready output.

Be specific about constraints

Tell the AI the language, framework, patterns you're using, and what you don't want — not just what you do. Constraints reduce hallucination and scope creep.

Give context, not just tasks

Explain the surrounding system, not just the isolated function. AI needs the why, not just the what. The more context, the more consistent the output.

Refine with diffs, not rewrites

When output is close but not right, reply with a targeted correction rather than asking for a full rewrite. Full rewrites discard working code; targeted diffs preserve it.

Use custom instructions / rules files

Set your coding standards, preferred stack, and project context once in AGENTS.md (or CLAUDE.md / .cursorrules) so you never re-explain them every session.

Create reusable prompt templates

For recurring tasks — write a test, review a PR, scaffold a component — keep a library of proven prompts. Stop solving the same problem twice.

Plan before you prompt

Define the architecture and data model yourself first. Hand the AI a clear spec, not an open-ended problem. The Architect Prompt methodology does this in three structured steps.

Treat AI like a pair programmer

Talk through the problem before asking for code, just as you would with a colleague. Pair programmers don't silently implement — they discuss first.

Break work into small, reviewable chunks

Large one-shot generations are harder to verify and course-correct than small incremental steps. One task only. Stop when complete. Confirm it works before moving on.

Commit to git before and after every AI task

AI-generated changes are the hardest to untangle without a clean rollback point. A commit before each task is the cheapest insurance you can buy.

Run parallel agents for parallel tasks

Use multiple AI agents simultaneously on independent parts of the codebase to multiply output. Assign each agent a clearly bounded, non-overlapping scope.

Use git worktree to isolate agents

Each agent gets its own working directory from the same repository — same codebase, different working trees — so parallel sessions never conflict or overwrite each other.

Assign agents specific scopes

Give each agent a clearly bounded task. Agents that wander produce unpredictable results. Scope boundaries should be as explicit as the task itself.

Pull the plug when the AI is looping

If the AI produces the same broken output twice — stop. Revert to the last commit, shrink the task scope, and re-prompt. A looping AI digs deeper into the wrong direction with every attempt.

Don't let AI dig the hole deeper

The longer you let a failing AI session run, the more tangled the output becomes. Cut early — it's always cheaper to revert a small change than to untangle a large one.

Some problems need human thinking first

Complex bugs, architectural decisions, and security-sensitive code should start with your brain, not the AI's. Use AI to implement a solution you've already reasoned through.

AI excels at tests, docs, and code review

Leverage AI most heavily for the work developers avoid: writing tests, generating documentation, and reviewing diffs. The Critique Loop after every build step uses exactly this.

You are responsible for the output

Every line of AI-generated code that ships is your code. You own it, you maintain it, you explain it. Sign off on it with the same rigour you'd apply to code you wrote yourself.