Do not index
Do not index
It’s no secret that AI has had a massive impact on code generation. But the newest shift is in background agents. These aren’t autocomplete tools. They’re autonomous workers. They take tasks, go off on their own, and write real code. And for the first time, they’re actually accessible. When Devin launched, it was something like $500 a month. That was cool, but out of reach for most teams. Today, tools like Cursor have background agents baked in and Codegen is ten bucks a month. If tech is part of your product, you can now afford to have AI teammates who make updates, fix bugs, and push real work without you watching every step.
When I first started using background agents, they weren’t very useful. They generated technically correct code that broke everything. The style was off. They ignored conventions. They missed test coverage. It felt like automation, but caused more cleanup than help. I thought the models were the problem. But what I eventually realized was that they just didn’t have the context. Just like onboarding any other team member, you need to give agents enough information to understand how the repo works and what’s expected. That’s where the
swarm.notes.md file comes in.The Unlock: Treat Your Agents Like Real Teammates
At Lunch Pail Labs, our homegrown AI swarm is called PailSwarm. Each project that the swarm touches includes a
swarm.notes.md file. It’s a short markdown file that explains how the project works. You can call it whatever you want. agent_instructions.md. AI_README.md. README-for-robots.md. The name doesn’t matter. The point is that your background agents need instructions, just like any team member joining the project. They need to understand the folder structure, naming conventions, which scripts to run, and what not to touch. They need to know what success looks like. That’s what Swarm Notes provides.What’s in My Swarm Notes File
I keep it short. Think of it as a cheat sheet, not a spec doc. Mine usually includes file naming rules, a map of the repo, any special scripts or build steps, and known issues or tech debt areas to avoid. I also document testing instructions and how to run things locally. It’s not comprehensive. It’s just enough to make an agent productive without guessing.
How I Actually Use It Day-to-Day
I use Cursor’s background agents as my agents of choice. When they pick up a task, the task itself includes a reference to the
swarm.notes.md file. That way, before they generate code or make changes, they already have the context about how the project works and what standards to follow. That one addition has helped make the outputs much more usable, with fewer mistakes and less rework.TLDR
If your background agents aren’t delivering value, it’s probably not the model. It’s the missing context. Onboard them like you would any teammate. Give them clear instructions. Start every repo with a
swarm.notes.md file. You’ll spend less time rewriting their output and more time letting them ship real work.And that’s it! What do you think? I would love to hear your thoughts. For more insights like this, subscribe to my newsletter: https://thebuildingblocks.substack.com/
.png?table=block&id=9ba33ac6-8e12-48f6-b980-4333b612ec56&cache=v2)