How to Manage Your Robot – John Jeffers
{{ post_title }}<br>Working Effectively with Coding Agents
{{ post_title }}<br>Working Effectively with Coding Agents
{{ post_title }}<br>Working Effectively with Coding Agents
How to Manage Your Robot
23 Jul, 2026
As the maintainer of Luxury Yacht, I spend a lot of time talking to coding agents. A lot.
I enjoy building the app, but I wouldn't say conversations with agents are fun. Keeping the robots in line is a full-time job. Waiting a long time between prompts, making sure they don't do stupid things, ensuring that the code they spit out isn't garbage... it can be tedious.
No matter how much effort I put into documentation, agents files, skills, or whatever the hot thing is this month, LLMs only have so much context, they can't truly learn anything, and your carefully-designed, critical instructions are eventually going to get dropped from the context window to make room for who-knows-what. And that gets more likely the longer a session goes on.
Frontier agents have gotten better at retaining context after compaction, and agent memory helps some, but it's not perfect, and agents can still easily lose their way on complex tasks.
With all that in mind, I'd like to share some of the things I've done to help the agents to be more effective. I'm not pretending to be an expert here. This is knowledge won mostly through trial and error, and I have no doubt that there are things I could be doing better. We're all learning, and the AI landscape changes rapidly.
There Are No Silver Bullets<br>Let's just get this out of the way: for large, complex projects, you'll be wrangling the agents frequently. Keeping them on track can be difficult and requires vigilance. Agents love to be "clever", so you'll be busy making sure that they stick to established patterns, reuse existing code, and don't reinvent yet another wheel.
You'll be frequently reminding them to think holistically, and cleaning up unintended consequences. "You made a change in the widgets subsystem that broke the gizmos module. Go fix that, and update the docs to ensure you don't do that again."
The real promise of the AI era? We're all managers now, guiding a bunch of smart but impulsive and forgetful junior engineers. So let's get into some strategies you can use to ease some of that newfound managerial burden.
Agents Files: Lay Down the Law<br>An agents file is a markdown file named AGENTS.md that usually sits in the root of the repo or project. Agents files are the first place an agent looks for the lay of the land, so this is where you want to put your important rules about how you want the agent to behave, and tell it where it can find more information.
A very simple agents file would look something like this:
# Rules
- Always practice red/green TDD.<br>- Run a linter on all code changes.<br>- A task is not complete until documentation is updated.<br>- Reuse code where possible. Don't invent new patterns when you could<br>use something that already exists.
The agent won't always follow these instructions, and sometimes it'll forget the very important things you put in here, even if you scream in bold, uppercase letters **THIS IS VERY IMPORTANT!** but it's where to start.
If you take nothing else from this article, create an AGENTS.md file in your project.
What your agents file should contain depends on your project and your desires when working with agents. I can't tell you what you should have in yours. You might have luck just asking your agent to create an agents file. Or, see some examples here.
Claude has to be different<br>Unfortunately, Claude doesn't want an AGENTS.md file, it wants CLAUDE.md. If you only use Claude, you'll create a CLAUDE.md file instead of AGENTS.md. But, if you use a mix of LLMs including Claude, cover your bases by putting your instructions in the AGENTS.md file, then create a separate CLAUDE.md file with only this line:
@AGENTS.md
This tells Claude to look in AGENTS.md, so you don't have to repeat the same instructions in both files.
Using multiple agents files<br>For a large project, you might want multiple AGENTS.md files spread around the project. This can help if you're tasking an agent with working on a specific part of the app, and reduce the amount of instructions it has to read vs. dumping everything into a single agents file in the root.
For example, Luxury Yacht has an agents file in the root that defines overarching rules for the entire project, but then has additional agents files in the backend and frontend directories with more specific rules and info about those areas of the app.
Luxury Yacht is open-source, so you can go look at the GitHub repo to see the agents files I use. You're not going to want to use my exact files for your project, but they might give you some ideas of how to structure yours.
Documentation: Help the Agent Understand<br>My agents files contain info about where to find documentation for the app. Let the agents write their own documentation. Tell them...