Skip to content
build-3000
fundamentals

Working With AI Coding Agents

What agents can do, how they fail, and how to direct them instead of hoping.

Before this: Projects, Files and Structure

Objective

Direct an AI coding agent with structured instructions, understand context windows and failure modes, and build the review habit that keeps you in charge.

Vocabulary

The words to use when directing your agent.

prompt
The instruction text you give an AI model or agent.
context
Everything the agent can currently see - your messages, files, prior replies.
context window
The finite amount of context an agent can hold at once.
tool call
An agent's action on the world: reading a file, editing code, running a command.
hallucination
When an AI states something false with complete confidence.

Understand it

The delegation loop

Directing an agent is a loop: state the task, let it work, inspect the diff, test the result, correct with specifics. The loop never skips inspection - that is what separates directing from gambling.

Failure modes you will meet

Hallucinated APIs (functions that do not exist), silent scope creep (changing files you did not ask about), and overconfident claims ('all tests pass' when none ran). Each has the same antidote: verify against reality, not against the agent's confidence.

Core concepts

Specify, do not wish

'Make it better' forces the agent to guess what better means. Goal, constraints and definition of done turn wishes into work orders. Vague input produces confident nonsense; specific input produces reviewable output.

Context is finite and precious

Agents forget what falls out of their context window. Long sessions drift. Re-stating key facts, pointing at specific files, and starting fresh sessions per task are professional habits, not quirks.

Examples

Weak prompt vs strong prompt

'Add login to my app' versus 'Add email-and-password login: form validates non-empty, wrong credentials show a generic error, successful login redirects to /home. Do not touch other pages.' Same agent, completely different outcomes.

Asking for the diff

'Show me exactly which files you changed and summarize each change in one line' turns a black box into a reviewable change set.

Common mistakes

Common mistake

Accepting large changes without reading them.

Fix

Require a per-file summary for anything over a couple of files, and skim each file once before approving.

Common mistake

Pasting passwords, keys or personal data into prompts.

Fix

Treat prompt text as semi-public. Reference secrets indirectly ('read from .env.local') and never paste their values.

Working with your AI agent

Adopt a standing instruction template for real tasks: goal, constraints, definition of done, and 'summarize changed files when finished'. Save it somewhere and reuse it every time.

Build it

The module’s real project. Your agent builds; you direct and inspect.

Project: The Briefing Document

Write a one-page spec for a small app idea of yours - written so well that an agent (or a person) could build it without asking you a single clarifying question.

Requirements

  • States the app's purpose in two sentences
  • Lists concrete features with acceptance criteria for each (what proves it works)
  • Lists explicit non-goals (what it should NOT include)
  • Names its constraints: single user, no payment, no accounts

Context for your agent

Do not write any code. Act as a demanding technical editor for my spec document: challenge every vague phrase, mark each feature missing an acceptance criterion, and return the improved outline as a list of gaps - not a rewrite. I will fix the gaps myself.

Verify it - twice

Check every item yourself first. Then hand your agent the prompt and compare verdicts.

Self-verified0/6
Functional
Architecture
Security
Testing

Verification prompt - paste into your AI agent

You are auditing my Briefing Document for build-readiness. Read it as if you were the developer receiving it. Answer PASS or FAIL with evidence: (1) purpose understandable in two sentences, (2) every feature has a testable acceptance criterion, (3) non-goals explicitly fence the scope, (4) constraints section exists with no contradictions elsewhere in the doc. Then list any question you would still need to ask me before building from it - if you have none, say so explicitly.

Run this against “Working With AI Coding Agents” after your own checklist pass. Where the agent and you disagree, investigate before moving on.

Review questions

Answer out loud. If you cannot, revisit before moving on.

  1. Rewrite 'make it look nicer' as a strong prompt for your agent.

  2. Name two failure modes of AI agents and the antidote for each.

  3. Why is context described as 'finite and precious'?

You can now

  • Write structured briefs that remove agent guesswork
  • Recognize hallucinations, scope creep and unverified claims
  • Keep secrets out of conversations with agents

Up next

Git Through Your Agent