← back to the section

A configured agent is a tool you have to know how to use. Three tasks repeat almost every day: make sense of unfamiliar code, build something new, find the cause of a bug.

All three share one way to fail — asking for the finished result straight away. "Explain the whole project," "write the feature," "fix this." The agent will answer any of those confidently and at length, and sorting through what comes back costs more than doing it yourself.

What works instead is an order of steps, where each one builds on a verified previous one.

Understanding someone else's code

The first thing you hit on a new project is hundreds of files, other people's decisions, zero context. This used to take weeks; an agent that reads the repository cuts it to hours. But only if you go top-down instead of diving straight into details.

Three layers, in this order:

  1. The map. "Describe the structure: what modules exist, what each is responsible for, where the entry points are." That is the skeleton.
  2. The routes. "Trace an order-creation request from the controller to the database, and name the classes involved." Now you can see how the parts connect.
  3. The room. "Explain what this method does and who calls it." Now you know where your own change goes.

The reverse order leaves you with fragments and no picture.

From there the agent is more useful answering specific questions than narrating: where is order cancellation handled; what happens if an empty list arrives here; who changes the status and in how many places; why are there two different ways of doing the same thing. These are exactly the questions you would ask a colleague who knows the project — except the agent answers in seconds and never tires of the "dumb" ones.

The key caveat: an agent can be confidently wrong — describing logic that does not exist, or skipping a branch. So ask for file and line references: an answer with nothing to anchor it to is a warning sign. Check anything important yourself by opening the file it names. And do not take architectural verdicts on faith: "this design is bad, it should be rewritten" is sometimes true and sometimes invented.

Building something new

The most common way to lose a task is to say "write it" immediately and get a pile of code that is easier to throw away than to review. What works is "think first, write second," with the agent involved in both stages — in different roles.

Conversation before code. Here the agent is an interlocutor: which user problem are we closing; what edge cases and forks exist ("what if the payment goes through twice?", "what about cancellation after shipping?"); what two or three approaches are there, with their trade-offs. Agents are good at surfacing options that are easy to miss. This stage has one rule: do not let it write code until the task is clear — early code freezes half-thought decisions.

Then the plan. Before the code. A good plan cuts the work into vertical slices: not "all the models first, then all the controllers," but "slice one — a single operation end to end, from entry point to database and test; slice two — the next one." Every slice can be built and checked. The plan names concrete files, steps, and how to verify each, and you see it whole — you can fix it before a single line is written.

This is the cheap place to catch mistakes of intent: changing a line in a plan takes minutes, rewriting working code takes hours.

And only now the code, slice by slice: build it — compile — run the test — lock it in — next. The plan keeps the agent from sprawling and keeps you from losing the thread on a long task. If the plan turns out wrong, that is fine: go back, fix it, continue. The bad state is not "the plan was off," it is "there is already a pile of code and it is not the right one."

Conversation and planning look like extra stages that delay the start. Over any distance the opposite is true: they remove the most expensive rework — discovering at the end that the wrong thing was built.

Finding and fixing a bug

The temptation when something breaks is to paste the exception into the agent and ask it to "fix it." Sometimes that works; more often the agent plausibly fixes the wrong thing, masks the symptom, or breaks something next to it.

Reproduce first. You cannot reliably fix what you cannot reliably trigger. Collect the exact steps and data that make the bug appear — better still, a failing test. That is gold: you get an objective criterion for "fixed" that does not depend on how it feels. If the bug is intermittent, say so — "it reproduces about one time in three" changes the whole approach.

Then the cause, not the patch. Ask not "fix it" but "find out why": where is this value produced and why is it wrong here; trace the data from the entry point to the failure; what hypotheses are there and how do we test each. Insist on references to specific places in the code — a confident hypothesis can be invented too.

Then a minimal fix of the cause. Not a workaround that hides the symptom. A good fix is explainable: it is clear why it fixes the bug.

And a check with two questions: is the bug gone — run the reproducing test; did anything nearby break — run the rest. A fix can touch its neighbours, and the agent will not remember to check.

What all three have in common

The order is the same: understanding first, then action, then verification. Only the subject changes — someone else's code, a new feature, or the cause of a bug.

The roles are distributed the same way too. Judgement about what to do and whether the result is right stays with the human; volume — reading, enumerating options, writing, running — goes to the agent. The moment those roles swap, speed turns into a pile of plausible code that solves the wrong problem.

In short

  • The shared failure in all three tasks is asking for the finished result: "explain everything," "write the feature," "fix it."
  • Unfamiliar code is read top-down: map → routes → specific method; answers must come with file and line references.
  • Features are built in the order conversation → plan → code in slices; early code freezes half-thought decisions.
  • Plans are cut into vertical slices, each of which can be built and verified.
  • A bug is reproduced first (ideally with a failing test), then traced to its cause in code, then fixed minimally, then checked for collateral damage.
  • Judgement belongs to the human, volume to the agent. The other way round does not work.
  • Configuring an agent for your project — the rules, skills, memory, and tools all of this stands on.
  • Hallucinations — why confident and correct are not the same thing.
  • Reviewing AI-written code — what to check before merging.
  • Accepting AI output — how to be sure the right thing was built.