Coding agents need guidance, not faith

Summary

• The most effective agents are written by people, not generated, and the information given to them must be selected and concise
• Making good use of different effort levels and plan mode stops you from wasting tokens and time
• This is probably the most impactful change you can make to improve your workflow, especially if you work with a large codebase. AI agents often behave like someone who forgets everything about the codebase, each session. 
• Make sure to compact conversation history to the most salient points, or start a fresh session, to avoid overloading the agent
• Experimenting is the best way to find out what works best for you and your organisation

Start by building a goo foundation. An instruction file, like AGENTS.md or CLAUDE.md, is the first step to guiding agents working with your codebase.

Effective AGENTS.md files are written by humans (not autogenerated), with concise guidance on how your codebase is unique. Agents know a JavaScript codebase likely has a package.json, but it doesn’t know your code style, security concerns or application architecture. Tell it what it can’t figure out.

If you already have good machine-readable documentation, don’t repeat it. Well-maintained documentation in a format like Markdown is an excellent way to help guide agents (and humans) to write better code.

Concision and maintainability are paramount. Agents get distracted by irrelevant or outdated information. Be selective. Commit to a small set of agent-specific guidance, and point it towards specific information, if needed. If writing frontend unit tests, it probably doesn’t need your database design principles.

If you have guidelines for specific file types, you can add path-specific ‘rules’, a great place for specific code style.

Work smarter, not harder

Many agents will allow you to set their effort level. This concerns how efficiently it consumes tokens. Higher effort will try to deeply understand your instruction, the structure of the codebase, and will ‘think’ hard to determine the best solution. It often locates or creates unit tests to verify successful completion.

That’s perfect for a complex new feature. It’s not ideal for a quick change. For that, you may wish to use lower effort. You will likely find that medium effort is great for most feature work, but sometimes lowering this further still produces good results.

Best laid plans

Plan Mode explores your codebase and figures out what it should do, presenting this information as a plan that you can approve, alter, or outright reject. This prevents agents from digging a hole you have to get them out of half an hour later. Instead, they explain their approach, what it will touch, and how it will verify the change is correct.

For you

Be part of something bigger, join BCS, The Chartered Institute for IT.

Add guidance in your user-level AGENTS.md, encouraging agents to favour concision when writing plans. This makes them easier to skim before approving. 

Tighten the blast radius

AI agents can behave more reliably if you scope work to concrete files, directories, or a set of changes. We’re not always good at communicating requirements, but being specific guides the agent to produce reliable output.

Make sure you mention any manual fixes you’ve made before moving on. Agents know what they’ve done, what they’re told, and what they read in the code. If you touch up its changes, it may think they were ‘removed by the linter/build’ or similar, and revert. Tell it when it makes a mistake, and steer it in the right direction. It may even be easier to get it to fix it for you.

What’s the context?

AI agents behave quite similarly to humans — they lose focus, miss details and get distracted by contradictory information. ‘Context’ refers to everything your agent is currently thinking about.

Imagine it like a conversation. You probably remember why you’re talking, and what was just said, but you’d struggle to recall details from a few minutes ago. Agents have a similar ‘context window’ so providing too much detail not only leads to wasted time, more token consumption, and therefore a larger bill, but it can fail to complete the task. Called ‘context rot’, this is where important information becomes buried amongst many tokens.

To fix this, ensure you ‘compact” the conversation history so important details can surface. For a new feature, you may need a fresh session.

Experiment!

AI models are non-deterministic so behave very differently to other programming tools. But they are still a tool. 

The best way to get better results is to simply work with agents, use them badly, iterate and improve! You may find manual corrections speed things up sometimes, but steering the agent instead may mean it is more productive in the long term.

Coding agents aren’t magic. With consistent practice, clear requirements and effective review, they can take your workflow to the next level.