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

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

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.
- Run a linter on all code changes.
- A task is not complete until documentation is updated.
- Reuse code where possible. Don't invent new patterns when you could
  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

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

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

My agents files contain info about where to find documentation for the app. Let the agents write their own documentation. Tell them that they are writing it for themselves, so while it needs to be human-readable, it doesn't need to be human-friendly, but instead optimized for consumption by agents.

Every time the agent modifies the app, it shouldn't consider the task complete until it updates any relevant docs with information about the changes. Instructions to do this are, of course, in AGENTS.md, but I sometimes have to remind the agent to do this before closing out a task.

I put all of my documentation in a docs directory in the root. Unlike the agents files, I don't split it into frontend and backend docs because the split is not always that clean. Many systems have cross-cutting concerns. I usually let the agents decide how to organize the docs, since that's who they are for.

I drop a README.md into the docs directory that functions as an index to tell the agents what docs to reference. Rather than try to explain exactly what I mean, I encourage you to look at the file. As with the other docs, the agent is responsible for updating this top-level README any time it makes changes that would impact it.

Skills: Tell the Agent How to Do It

Skills are bundles of instructions (a markdown file, and possibly other scripts and reference files) that tell an LLM how you want it to perform a specific task. It's a broad topic that I'm not going to go too deep on in this article. There are a wealth of existing resources for skills, far more comprehensive than I could hope to be here.

If you find you're frequently repeating yourself when giving instructions to the agent, that's a sign that you might need a skill. You can try writing one yourself, but it's frequently easier to ask the agent to write the skill (which you, of course, review and validate).

For example, in Luxury Yacht, I have a skill that gives the agent information about how to make changes to the refresh subsystem, the part of the app that makes sure the Kubernetes data being displayed is fresh. This is a complex system, so it's important to give the agent as much help as possible when it has to interact with the refresh system.

You might have noticed that there's some crossover between skills and docs. The way I think about it is that the docs are the what and the why, and the skills are the how.

Tests and Linters: The Safety Gates

A very effective step you should take early on is to enforce tests and linters. Never allow the agent to consider a task to be complete until it has written tests and run a linter.

I find Red/Green TDD (or Red/Green/Refactor) to be particularly effective for LLMs, as it makes them think a little harder about how to properly implement something. If you're unfamiliar with Red/Green tests, it boils down to this:

1. Red step - write a test that describes what you want. Verify that the test fails.
2. Green step - write the simplest code to make the test pass.
3. Refactor - improve the code while ensuring the test keeps passing.

After the tests, you should make sure the LLM runs a linter on the code it generated to catch the easy things that a linter is for. Good tests and a good linter will save you a lot of trouble.

Git: The Escape Hatch

Make sure you're working in a branch, and your branch is clean before you set an agent on a complex task. I cannot count the number of times I've had an agent go off the deep end, and I was saved by being able to revert the changes, then have it start over after discussing what went wrong.

I don't personally use worktrees, and I tell the agents not to use them, either. I don't need worktrees because I don't run agents in parallel. One agent, one branch, one task at a time. Git is archaic and difficult enough to reason about without adding complexity.

I also don't allow the agent to perform any commits, PRs, or other operations that modify git state. My instructions say that the agents are allowed to perform read-only git commands, and that's it. Leave the other stuff to me. It's a level of control that I'm not yet ready to hand over to agents. YMMV.

Hooks: Do X Before You Do Y

One of the newer things I've tried (and I'm not sure about its effectiveness yet) is using hooks to require the agent to perform a task at a certain point in its lifecycle.

The idea to use hooks came after a very frustrating Claude session where I just could not get it to behave. It kept making the same mistakes over and over, ignoring explicit instructions, and I asked it how to get it to stop doing that. It suggested creating a PreToolUse hook to force it to "map the blast radius" before making any changes.

The hook that I use consists of a few parts:

• The settings file that tells Claude about the hook
• The script that the hook runs
• The file that the script writes to, which is meant to be transient so it's in .gitignore.

The reason I say that I'm not sure about the hook's effectiveness is that I currently only have the hook set up for Claude, and not GPT. But I haven't seen proof that Claude does a better job with the hook than GPT does without it. It really depends on the specific task.

We've talked about a lot of strategies. And yet... even with all of these safeguards in place, I still don't trust one single agent to do it right. Which leads me to...

Adversarial Reviews: Robot vs. Robot!

This is maybe the most effective strategy I've found to generate higher-quality results. For any even moderately-complex task, I'll use a second agent to challenge the other. Typically I use a different model as the reviewer. For example, if Claude is the author, then I'll use GPT as the reviewer, but even using the same model for both roles (in different sessions) can be effective.

Reviewing the Plan

I'll start by asking an agent (the author) to write a plan, then I'll point the other agent (the reviewer) at that plan and ask it for a review. LLMs seem to hate coming up empty-handed when you ask for a review, so it'll nearly always find something wrong.

I'll feed the output of the review back to the author, saying something like:

Another reviewer has provided feedback. Do not assume these assertions
are correct. Validate all findings.

[pasted contents of the review]

After the author agent has fixed (or not) the reviewer's findings, I'll go back to the reviewer and say:

changes made, review again

Typically it'll find something else, and I'll repeat the process until both agents agree that everything is fixed, or we can at least get to a point where the disagreements aren't significant enough to continue. Depending on the complexity of the task, this can take a while.

If it's a particularly difficult or risky task, I might start a new session and repeat the process. With a clean slate, it might follow other code paths that turn up something new.

Reviewing the Code

After the plan has been approved, and the agent's completed the implementation, I'll usually follow up with a code review. The agent may have had a well-designed plan, but that doesn't necessarily mean it did a good job of implementing it.

The process is very similar. Only the prompt is different. The gist is "review the code" instead of "review the plan". The exact language I use depends on the task. The back-and-forth is the same. Author vs. reviewer, until both are satisfied with the results.

The Wrap-Up

Building complex software with agents requires discipline. Every step you can take to reduce the amount of handholding and babysitting you have to do is worth it, but figuring out which of those steps are effective can feel like a mystery.

If I had to distill it down, I'd recommend this:

• Put important, project-wide rules in agents files.
• Put architecture info in documentation.
• Put repeatable procedures into skills.
• Make tests and linters mandatory from the start.
• Leverage git commits as a safety net.
• Use adversarial reviews for higher-quality results.
• Keep yourself in the loop by reviewing the code.

If you're an experienced software developer, you might notice that there really isn't anything new or groundbreaking here, and these principles aren't AI-specific. What I'm talking about is just good, solid engineering practice, viewed through an agentic lens. None of it eliminates the supervision required from you, but it should help to make agent-assisted development in complex projects more... manageable.

We're all managers now.

#ai #development