How to Direct AI Coding Agents Like a Pro

How to Direct AI Coding Agents Like a Pro

For about six months I had the wrong job title in my own head. I thought I was a developer who used Claude Code. Then I broke a production build at 11 PM, traced it back to a single line the agent wrote that I'd never actually read, and realized the truth: I'd been a passenger. Sitting in the driver's seat, hands near the wheel, but mostly just hoping the car stayed on the road.

The fix wasn't a better model. Opus 4.8 was already running. The fix was a different role. I stopped trying to write code through the agent and started trying to direct the agent — the way a film director doesn't operate the camera but is responsible for every frame. That shift, more than any prompt template or plugin, is what doubled the amount of real, shippable work I get out of a day.

This is the part nobody puts in the slick demo videos. To direct AI coding agents well, you spend more time planning than building. You manage the agent's attention like it's a scarce resource, because it is. You build scaffolding around it so it can check its own work. And you treat every failure as a chance to permanently upgrade the system instead of a one-off annoyance.

A lot of what reorganized my thinking came from a podcast interview I kept rewinding — Cole Medin, a software engineer who turned into an AI builder and one of the sharper voices on agentic coding. He frames Claude Code not as a code generator but as an "AIOS," an AI operating system you wire into how you actually run a business. That framing sounded grandiose until I started applying it. Then it just sounded correct.

Here's everything I've changed about how I run my agents — what worked, what burned me, and the exact habits I now refuse to skip.

Why directing AI coding agents beats prompting them

Directing an AI coding agent means owning the intent, the plan, the success criteria, and the verification — and letting the agent own the typing. The prompt is the smallest part of the job. The thinking around the prompt is where the leverage lives.

Most people who say Claude Code "doesn't work for real projects" are stuck in prompt mode. They open a session, type a paragraph, watch it generate, and judge the tool by the first thing it spits out. When that first pass is wrong — and it usually is on anything non-trivial — they conclude the agent is dumb. I did exactly this for months.

The reframe is brutal but freeing: the agent is not your peer engineer. It's an extraordinarily fast, extraordinarily literal junior who has read everything and remembers nothing about your project unless you tell it. Your job isn't to chat with it. Your job is to be its product manager. You feed it the why behind every task, set the boundaries, define what "done" looks like, and inspect the output against a standard you decided in advance.

Cole calls the core skill here something I now use constantly: treating the AI like a mentor while you act as its product manager. You're not asking it to figure out what to build. You're handing it a spec so clear that a literal-minded junior couldn't misread it, then checking the result like a PM checks a feature against the ticket.

Once I internalized that, the question stopped being "what's the perfect prompt?" and became "what does this agent need to succeed, and how will I know if it did?" Those two questions reorganize your entire workflow. The first one is about context. The second is about verification. We'll spend most of this post on exactly those.

But before either of those matters, you have to understand the single constraint that governs everything an agent does: how much it can actually pay attention to at once.

The "dumb zone": why a 1M context window lies to you

Here's the most expensive misconception in agentic coding, and I held it for longer than I'd like to admit: a bigger context window means you can dump more in and the model handles it fine.

It doesn't. Opus 4.8 ships with a 1-million-token context window — that's the same window Anthropic kept across the 4.x line, confirmed on the 4.8 release on May 28, 2026. A million tokens sounds like infinite headroom. But the number you can fit and the number the model can reason over accurately are not the same number, and the gap is where projects quietly fall apart.

What Cole names the dumb zone matches exactly what I see in practice: somewhere past roughly 250,000 tokens of accumulated context, accuracy starts degrading. Not catastrophically — that's the trap. The model doesn't error out. It just gets subtly worse. It starts forgetting a constraint you set forty messages ago. It misreads a file it read correctly an hour earlier. It "helpfully" edits something you explicitly told it to leave alone. The window isn't full, so you assume you're fine. You're not. You're in the dumb zone.

I learned this the hard way on a Laravel refactor across my brand sites. I kept one long session running for most of an afternoon, feeding it file after file, trusting the giant window. Around hour three the agent started reintroducing a bug I'd had it fix two hours prior — because that fix was now buried under 300K tokens of subsequent noise, and it had effectively "forgotten" the lesson while the conversation technically still contained it.

The rule I follow now is blunt: keep context lean, on purpose. Treat the usable working window as far smaller than the advertised one. Three habits enforce this:

• Clear aggressively between unrelated tasks. The moment one logical chunk of work is done, I reset rather than carrying its baggage into the next. I wrote the whole case for this in my breakdown of the Claude Code slash commands I actually use daily — /clear is the one I'd keep if I could only keep one.
• Don't make the agent read what it doesn't need. Every file it opens to "understand the codebase" is tokens spent and attention diluted. Point it at the three files that matter, not the whole repo.
• Put durable knowledge in CLAUDE.md, not in the chat. Architecture, conventions, schema — that stuff belongs in project memory where it survives a clear and doesn't rot inside a drifting conversation.

The dumb zone is why every advanced technique in this post exists. Harnesses, sub-agents, the Ralph loop — strip away the jargon and they're all the same move: keep any single agent's context small enough to stay sharp. Once you see that, the rest of the architecture makes sense.

So if context is the constraint, where does the work actually go? Into planning — long before a single line gets written.

Plan more than you build: the spec is the real work

The most counterintuitive lesson: the better I get at directing agents, the less of my time goes to watching them code and the more goes to planning before they start. On a meaningful feature I'll now spend the majority of my active time on the spec and almost none babysitting the build.

This feels wrong if you came up writing code by hand, where planning was a tax you paid before the "real" work. With agents it inverts. The agent does the typing in minutes. The plan is what determines whether those minutes produce something you ship or something you throw away. The plan is the real work.

A spec that actually controls an agent has four parts, and I've started writing all four explicitly:

1. Intent — the why. Not just "build a billing page" but "build a billing page so existing customers can upgrade tiers without contacting support, because support tickets for upgrades are eating two hours a day." When the agent knows the why, it makes better micro-decisions on the thousand things you didn't specify. Cole calls this intent engineering, and it's the highest-leverage sentence in any prompt. The agent fills gaps in the direction of your stated intent instead of guessing.
2. The plan — the how. The files involved, the order of operations, the approach you've chosen and the ones you've rejected. I'd rather over-specify here than discover mid-build that the agent invented an architecture I'd never have approved.
3. Success criteria — the definition of done. Concrete, checkable conditions. "Tier upgrade updates the subscription in Stripe, reflects immediately in the dashboard, and sends no duplicate webhook." If I can't write the success criteria, I don't understand the task well enough to delegate it yet.
4. Validation strategy — how it gets checked. Decided before the build, not after. Which unit tests, which browser flow, which manual check. We'll get deep into this in a moment because it's where the real reliability comes from.

A note on tooling, because Cole flagged this and I've come around to it: he prefers writing his own controlled planning prompts over leaning entirely on built-in plan modes, for the flexibility. I use Claude Code's plan mode constantly — it's genuinely good, and the planning phase now gets its own dedicated agent so research doesn't pollute the main context. But for anything gnarly, I'll hand-write a spec as a markdown file and have the agent execute against that, because I control every word of it. The built-in mode is the fast path; the custom spec is the precise one. Use the fast path until precision matters, then switch.

Here's the part that surprised me. Writing the spec this thoroughly didn't slow me down overall. It moved my thinking earlier, where it's cheap, instead of later, where a wrong assumption means tearing out finished code. If you've ever felt like Claude Code "almost" got it but kept missing the point, the missing piece is almost always a thin spec.

Now — even a perfect spec produces a first draft that's wrong more often than it's right. That's not a failure of planning. It's just the floor. The question is how you get from that floor to something trustworthy.

How do you verify AI-generated code is actually correct?

You verify AI-generated code by building automated checks the agent runs against its own output — unit tests, browser automation, and custom harnesses — so it catches and fixes its own mistakes before you ever review it. First-pass agent output lands around 65–70% correct on real tasks; a solid self-verification layer pushes that past 92%. That jump is the whole game.

Sit with those numbers, because they reframe everything. If you trust the first pass, you're shipping work that's right two-thirds of the time. If you make the agent check itself, you're shipping work that's right nine times out of ten — without spending more of your attention. The agent does the rework. You just have to give it a mirror.

The verification layer has three tiers I now build in roughly this order:

Unit tests. The baseline. I have the agent write tests against the success criteria, then run them, then fix what fails — in a loop, without me. The key is that the tests encode the spec, not whatever the agent happened to implement. Tests written after the fact just confirm the agent's bugs. Tests written from the success criteria catch them.

Browser automation. For anything with a UI, unit tests aren't enough. I wire in Playwright so the agent can actually drive the page — click the upgrade button, confirm the dashboard updates, check no duplicate webhook fired. The agent sees the real behavior instead of reasoning about it abstractly. This single addition fixed a whole category of "it passed tests but the button did nothing" failures.

Custom harnesses. This is the advanced move and the one that made me grin when I first heard Cole describe it. Sometimes the thing you're building can't be checked by a normal test — it's interactive, real-time, or visual. His example stuck with me: to let an agent debug a video game, he slowed the game's frame rate down so the agent had time to observe each frame and react. That's a harness — a custom rig that simulates the user and lets the agent perceive and respond to what's actually happening. The principle generalizes: if the agent can't verify something, build it a way to perceive that thing, and now it can.

This is also exactly the kind of judgment that separates directing an agent from babysitting one. I went deep on the surrounding tooling in my piece on the tools that fix Claude Code's AI slop — most "slop" isn't a model problem, it's a missing verification layer.

If you'd rather not build this scaffolding yourself, this is precisely the kind of agentic infrastructure my team sets up for clients — designing the spec, verification, and harness layer so the agents stay reliable in production. You can see the kind of builds I take on at fiverr.com/s/EgxYmWD.

Once one agent can reliably verify itself, a bigger idea opens up: what if you chain several of them, each staying in its own lean context, handing off clean work down the line?

Harness engineering and the Ralph loop

A harness, in this world, is the orchestration layer around your agents — how you run them, in what order, with what handoffs, and what checks run between them. Cole frames it as the foundation you build first, with an "AI layer" of skills, hooks, and MCP servers stacked on top. Get the harness right and everything above it gets more reliable.

The reason harnesses matter comes straight back to the dumb zone. A single agent grinding through a big task accumulates context until it degrades. But if you split the work into phases and give each phase its own agent with its own fresh context, no single agent ever drifts into the dumb zone. Each one does one job sharply, then hands off.

The cleanest version of this is what the community calls the Ralph loop — a technique originally popularized by Geoffrey Huntley in 2025, now baked into Claude Code patterns. Picture an assembly line. One agent plans. It hands a clean spec to a second agent that implements. That hands off to a third that tests and fixes. Each station owns one phase, receives clean input, produces clean output, and crucially starts fresh — so the context bloat of the planning phase never weighs down the testing phase.

I run a manual version of this constantly now. Even without fancy orchestration, the discipline of "plan in one session, clear, implement in the next, clear, verify in a third" keeps every step sharp. Opus 4.8's dynamic workflows took this further — a single session can now spin up many parallel sub-agents, each with its own context window, then aggregate the results. I broke down what that unlocks in my walkthrough of Claude Code's dynamic workflows.

Sequential vs. parallel is the choice you're making with a harness:

• Sequential (the Ralph loop) when each phase depends on the last — plan, then build, then test. Clean handoffs, no drift, runs for a long time autonomously.
• Parallel when the work splits into independent chunks — three sub-agents researching three different libraries at once, then reporting back. Faster, but they can't easily talk to each other, so they're best for fan-out-then-gather work.

Honest caveat: harness engineering is the point where this stops being casual. You're now writing orchestration, managing handoff formats, debugging which station broke. It's real engineering. The payoff is agents that run reliably for hours instead of needing you every five minutes — but you don't reach for it on a quick fix. You reach for it when the task is big enough that babysitting it would cost more than building the rig.

There's one more mindset shift that compounds with all of this, and it's the one that quietly made my whole setup better over time.

Treat every failure as a permanent upgrade

Here's the habit that changed the trajectory of my system more than any single feature: every time an agent screws up, I don't just fix the output — I fix the system so that exact mistake can never happen again.

The agent generated code that violated my naming convention? I don't just rename it. I add the convention to CLAUDE.md. The agent keeps forgetting to run migrations after a schema change? I add a hook that blocks the commit until migrations run. The agent misunderstood a domain term? I write a one-paragraph glossary entry. Each fix is a brick. Over months, the bricks become a wall that catches problems before I ever see them.

Cole frames this as a system-evolution mindset, and it's the difference between a setup that stays mediocre and one that compounds. Most people fix the same class of bug fifty times because they treat each instance as isolated. The compounding move is to spend two extra minutes turning each failure into a rule, a doc, or a validation step. The fiftieth time, the problem simply doesn't occur — the system absorbed the lesson permanently.

This is why I keep harping on CLAUDE.md and verification. They're not setup chores. They're the memory of every mistake your agents have made, encoded so they don't repeat. A self-improving setup isn't magic — it's just this habit, applied relentlessly. I went further down this rabbit hole in my post on building self-improving Claude Code systems, but the core is this paragraph.

There's one category of failure, though, where "fix it next time" isn't good enough — because the cost of the first time is catastrophic. Security.

Security: why "don't delete the database" isn't a permission

This is the lesson I most want people to take seriously, because it's the one with teeth. Telling an agent in a prompt "don't delete the production database" is not a security control. It's a suggestion. And an agent that's been instructed to accomplish a goal can, and sometimes will, find a creative path right around your suggestion.

Think about what an agent actually is: a system that writes and runs code to achieve an objective. If deleting and recreating a table is the path of least resistance to making a test pass, a sufficiently determined agent can script its way there — even after you typed "don't touch the database." The instruction lives in the prompt, which is just text the model can reason against, reinterpret, or quietly deprioritize under pressure. Prompt-based guardrails are made of the same material as the thing you're trying to constrain.

Real controls live below the prompt, in the harness:

• Hooks. A hook is a small program that runs at a specific point in the agent's lifecycle — think git hooks, but for AI. A pre-execution hook can inspect a command before it runs and hard-block anything matching a dangerous pattern (a DROP, a rm -rf, a write to a protected path). The agent doesn't get to talk its way past a hook. The hook is code, and code doesn't negotiate. This is structurally different from a prompt instruction, and it's why hooks are non-negotiable for anything near production.
• Strict permission scopes. Don't give the agent broad access and trust it to behave. Scope it down to exactly what the task needs — this directory, these commands, no more. The narrowest viable permission set is your real safety net.

I treat this with the same seriousness I'd treat any production access. If you're running agents anywhere near real systems and real data, the security posture of those agents is a genuine attack surface — and it's exactly the kind of thing xCyberSecurity assesses for businesses adopting AI tooling. An agent with database access and prompt-only guardrails is a breach waiting for a bad day.

Security handled, there's a quieter risk that creeps in over months: not knowing what your own codebase actually does.

The "dark code" problem: understand what the agent writes

The seductive failure mode of agentic coding is shipping code you've never read. It works, the tests pass, you move on. Multiply that by a few hundred merges and you've got a codebase that's a black box to its own owner — what some people call dark code. The day something breaks, you're debugging a system you don't understand, written by an agent that doesn't remember writing it.

I draw a line now: I at least try to understand what the agent produces. Not every line of boilerplate, but the architecture, the non-obvious decisions, anything touching data or money or auth. The trick I lean on is side conversations — a sidecar or separate session where I ask the agent to explain a chunk of code without dumping that explanation into my main working context. I get understanding without polluting the context window that's busy building. It keeps the main agent lean while my own mental model stays current.

A candid note for the non-coders reading this — and there are more of you in agentic coding every month: if you genuinely can't read the code, your safety net has to be rigorous validation, not vibes. Lean harder on the verification layer than a developer would. If you can't inspect the engine, you'd better have excellent instruments on the dashboard. The validation isn't optional for you; it's load-bearing.

Understanding is one job. Sometimes, though, the job is harder thinking — a real decision with trade-offs, where a single agent's confident answer is exactly what you shouldn't trust. That's where agent teams earn their keep.

Agent teams and sub-agents: when to spawn a crowd

Two tools in the kit get confused constantly, so let me draw the line clearly, because they solve different problems.

Sub-agents are lightweight agents you spawn for focused, isolated work — usually research or context-gathering. You send one off to investigate three competing libraries and report back the trade-offs. Each runs in its own context window, which is the whole point: it does the heavy reading so your main agent stays lean. They're token-heavy and their communication back is limited, but for fan-out research they're excellent. Opus 4.8 can run hundreds of these in parallel in a single session now.

Agent teams are a different animal. Here you spawn multiple persona-based agents and have them deliberate — debate a decision, argue edge cases, challenge each other. This is the antidote to one of the most dangerous traits of a single agent: sycophancy. Ask one agent if your plan is good and it tends to agree with you. Stand up an adversarial team — one arguing for the approach, one hunting for everything wrong with it — and the disagreement surfaces edge cases and failure modes a single agreeable agent would have smiled past.

I use agent teams for genuinely consequential decisions — an architecture choice I'll live with for a year, a security model, a migration plan. The adversarial debate is where I've caught my worst assumptions. But I'm honest about the cost: this is very token-heavy. Several agents arguing in parallel burns through usage fast. It's a precision instrument for high-stakes calls, not a default. For routine work it's overkill. I went deeper on multi-agent orchestration in my breakdown of Claude Code agent swarm architecture if you want the structural details.

So which features actually carry the load day to day? After months of this, three rise above the rest.

The three Claude Code features that matter most

Cole named his top three Claude Code features, and after running my own brands on this setup, I land in the same place. These are the ones doing the real work:

1. Skills. Reusable, parameterized prompts you invoke by name. Instead of re-typing a complex instruction every time, you save it once and call it like a function. This is how a workflow stops being something you remember and becomes something the system knows. I've built skills for everything from SEO drafts to deployment checks across my sites.
2. Hooks. Event-triggered code that runs at defined points in the agent's lifecycle. We covered their security role, but they're equally powerful for quality — auto-formatting on save, running tests before a commit, blocking a merge that fails a check. Mechanical guarantees, not hopeful instructions.
3. Sub-agents. Focused research and context-gathering in isolated windows, keeping your main agent sharp. The dumb-zone defense, operationalized.

Notice the through-line. Skills make your workflows repeatable. Hooks make your guarantees mechanical. Sub-agents keep your context lean. None of them are about making the model "smarter" — they're about building a system around the model that stays reliable. That's the entire philosophy in three features.

So here's how I'd put all of it into practice, starting tomorrow.

The director's checklist I actually run

Pin this. It's the operating procedure I run on any non-trivial task now:

• Plan more than you build. Write intent, plan, success criteria, and validation strategy before the agent writes a line. If you can't write the success criteria, you're not ready to delegate.
• Keep context lean. Treat the usable window as a fraction of the 1M advertised. Clear between tasks. Don't make the agent read what it doesn't need. Stay out of the dumb zone.
• Build automated verification. Unit tests from the spec, Playwright for UI, custom harnesses for anything interactive. Move first-pass correctness from ~65% to 92%+ without spending your own attention.
• Engineer harnesses with clean handoffs. Ralph loop for sequential phases, parallel sub-agents for independent fan-out. Each agent stays lean.
• Treat every failure as a permanent upgrade. Each bug becomes a rule, a doc, or a hook. The system compounds.
• Lock down security below the prompt. Hooks for hard blocks, strict permission scopes. "Don't delete the database" is not a control.
• Understand the code. Use sidecar conversations to learn without polluting context. Non-coders: lean harder on validation.
• Use agent teams for high-stakes decisions. Adversarial debate kills sycophancy and surfaces edge cases. Token-heavy — save it for calls that matter.
• Feed the why. Intent engineering. Every task carries its purpose. The agent fills gaps in the direction of your intent.

The thread tying all nine together is the one idea I opened with: you're the director. The product manager. The mentor handing a brilliant, literal, forgetful junior exactly what it needs to succeed — and checking the result against a standard you set in advance.

Remember that production build I broke at 11 PM? The one with the line I never read? I still think about it, but not with regret anymore. It was the night I stopped being a passenger. The next morning I wrote my first real spec, added my first hook, and started treating the agent like what it actually is — not a magic coder, but a system I'm responsible for directing well.

So here's the one thing to do in the next 24 hours: take the most repetitive task you currently prompt your way through, and write it a real spec — intent, plan, success criteria, validation. Just one. Then watch how differently the agent behaves when you stop chatting with it and start directing it. That single rep is where the role change begins.

Let's Work Together

Looking to build AI systems, automate workflows, or scale your tech infrastructure? I'd love to help.

• Fiverr (custom builds & integrations): fiverr.com/s/EgxYmWD
• Portfolio: mejba.me
• Ramlit Limited (enterprise solutions): ramlit.com
• ColorPark (design & branding): colorpark.io
• xCyberSecurity (security services): xcybersecurity.io