The hard part of building with agents isn't the code

A confession first. For most of my years shipping software, project management lived in my head. No tool, no system. I just remembered what I was doing. That works fine when you are alone. It sort of works with a small team. Once I started building with agents it stopped working almost overnight.

Building with agents brings its own kind of chaos. At first it feels like magic. You describe a bug, the agent reads the code, changes a few files, runs a test, and comes back with something that looks like progress. Sometimes it is progress. Sometimes it just looks like it. I have been burned enough times that I no longer trust the look of it.

The funny thing is that writing code was never the hard part. That gets easier every month. The hard part is making sure the work is attached to the right problem, that the agent had the right context, that someone reviews the change at the right point, and that nothing slips through between "I fixed it" and "this actually shipped".

I have been building a small tool for this called Aruvi. It is a place where humans and agents coordinate work. The only honest way to test it was to use it to run its own development. When it gets in the way I feel it right away. When it removes friction I feel that too. Here is what a few days of that taught me.

1.The unit of work has to be explicit.

The biggest trap with agents is that the chat becomes the unit of work. Someone says "fix this". The agent goes off and changes some files. Maybe a PR shows up. Maybe the reason for the change is buried somewhere in chat history, if you know where to look.

That works for toy projects. It breaks the moment you have more than one thing running. I wanted the unit of work to be a real thing the agent can operate on. An issue it can pick from a queue, read, comment on, and move when the work is actually done.

The difference shows up later. Instead of "there was a chat about this bug somewhere", you get a trail. The issue was picked up, a finding was posted, the fix went into a PR, the checks passed, and it moved to Done. Sounds boring. When ten things are moving at once it is everything.

2.Structure isn't bureaucracy if it's just memory you don't have to hold.

I am suspicious of process. A lot of it exists so people can feel in control from a distance. But some process is really just memory written down, and I have come around to that kind.

The flow that worked was plain. Pick up the issue. Read it before touching code. Leave a comment when you learn something. Make the smallest fix that holds together. Verify it. Open the PR. Link the result. Then move it to Done. Nothing clever about any of this. The point is that the work stops depending on anyone's short term memory.

This matters more with agents, not less. Humans forget things. Agents forget more, since their memory is whatever fits in the current session. If the chat transcript is your source of truth, things will drift. Push the truth back into the tool.

3.Agents need a brief, not a vibe.

The most useful thing an agent layer does is not writing code. It is gathering context. When an agent starts a task, the expensive part is figuring out the shape of the work. Which project is this in? Who owns it? What has already been decided? Is this even a code fix, or is it a docs task?

Without structure the agent wastes its budget piecing all that together from scraps. With structure it pulls the issue, gets the context, and comments back into the same place I am already looking. That last part mattered more than I expected. The agent is not off in its own world. It works in the same workspace as the rest of us. You hand it a clear task and you get back something you can review.

4."Done" has to mean something.

One small habit helped more than anything else. Never move an issue to Done before the real output exists. Sounds obvious, but this is exactly where most workflow tools quietly lie. An issue gets marked done because the code changed locally, or because the agent said it finished. Later you find there is no PR, no deploy, no document. The status says done. The work isn't.

So Done comes after the artifact, always. For code that means a pushed PR with passing checks. For docs it means the document actually lives where the team expects it. Done should be a claim backed by evidence.

5.The output has a correct destination.

A code fix belongs in a PR. A decision belongs in an issue comment. A long explanation belongs in the docs. Durable knowledge belongs in the knowledge base. These are not interchangeable. If you write a doc as a stray markdown file in the repo when the team expects it in the docs, you wrote the words but you didn't finish the job. If your findings only live in a chat reply, you helped this one conversation and nobody after it.

6.Reliability comes from boring constraints.

The most reliable parts of all this were not the clever parts. They were the constraints. Start from the queue. Read before coding. Comment when you learn something. Keep the PR small. Verify. Link the result. Close only when the result exists.

None of this slows things down. It removes guessing. The reviewer doesn't have to guess why a change exists. I don't have to ask whether the PR got created. The next agent doesn't have to reconstruct the last run from scraps. It pays off most on small fixes, the ones that feel too small for ceremony and too important to lose the trail on.

7.Faster agents make this more necessary, not less.

There is an argument that better agents will make project management obsolete. I think the opposite happens. As agents get faster, the bottleneck moves from writing code to coordinating it. What should be worked on? What does done mean? Which changes belong together?

If a human misunderstands a task you lose an afternoon. If a fleet of agents misunderstands a queue you get a big pile of convincing garbage very fast. The faster the workers, the more expensive ambiguity gets. So the coordination layer has to get better.

8.The product and the protocol are the same thing.

The part I find most interesting is that the human product and the agent protocol are not two separate things bolted together. The same issue is a card on a board for me and a unit of context for the agent. The same comment is a note for a teammate and a record for the next agent run. If you build only for humans, agents have to scrape and guess. If you build only for agents, humans get a weird automation backend. The thing worth building is readable to both.

After a few days of working this way, the thing that stays with me is that reliability comes from small honest loops. The issue says what needs doing. The agent reads it and reports what it finds. The code lands in the right place. The checks run. The result gets linked. The issue moves only when reality has caught up with the status.

That is not a grand vision of software development. It is just a better loop. Most teams I know don't need more theater around their work. They need better loops.

If you want the mechanics underneath, how the issues, queues, comments and agent tools fit together, it is all in the Aruvi docs.