Git was made for humans

⏱️ 10 min read

In the previous chapter, The most expensive token is the one of an AI waiting (chapter 5), I told the story of the most expensive run of the project, which delivered nothing, and the rule that came out of it: waiting is a job for code.

In chapter 1, 6x1? Here it's 24/7, I left a night half told. It was a Tuesday, and I put five tasks to run at the same time. Four got stuck at the last step. I wrote that the night had taught me a lesson, parallelism is cheap to start and expensive to finish, and that I would tell the story here.

This chapter is about that night and about what came after: why a tool designed for people gets in the way when the ones writing are several AIs, and why, with agents in parallel, even the format of a file becomes an architecture decision.

8:33 pm: five agents, one file

At 8:33 pm that Tuesday, September 29, the first of the five runs started. Each agent had its own isolated copy of the project and didn't see the others' work. They developed, tested and reviewed without bumping into anyone.

The problem showed up at the end. Back then, each task ended by opening a merge request on GitHub, the PR: a request to merge the new code into main, the official version of the project. At 10:11 pm, the score was four failures out of five. All at the same step, because of conflicts.

A conflict, in git, is when two changes touch the same part of a file and it doesn't know which one wins. A person has to look and decide. Or, in my case, an agent.

Before going on, a legend for the rest of the chapter:

• ⚙️ Engine: the factory's orchestrator, a regular program, with no AI, that always does the same thing the same way.
• 🤖 Agent: an AI doing the work.

Solving those conflicts one by one would have turned into a cascade. Picture five finished tasks, waiting to get into main:

• ⚙️ Merge the first one: the first task gets in, and main changes.
• 🤖 Redo the others: the four left no longer fit the new main. The developer is called again for each one, and then testing and review.
• ⚙️ Merge the second one: one of the four gets in, and the remaining three conflict again. And so on.

Every turn of the cascade pays again for development, testing and review of work that was already done. And, with GitHub in the middle, every turn also ran continuous integration again.

Cheap to start, expensive to finish

The first answer came that same night. At 11 pm, a workflow was born that merges the code on my own computer, without going through GitHub for every task. Continuous integration left the short cycle, and the success rate of the runs jumped from about half to nine in ten. Sending to GitHub became a decision of mine, in batches.

But the conflict didn't go away. It changed shape.

Before, a run with a conflict failed, and the rework became a new run. With the local merge, it no longer failed: it called a step to resolve the conflict, with the developer and the reviewer back on stage. The failure became an expensive resolution. In that period, the runs with conflicts took almost a third of the cost of all the runs.

What changed the game was the AI Product Owner, the PO I introduced in chapter 2. It reads the code, puts the tasks that touch the same files in a single run and places the groups that would fight in different stages. Conflict resolution moved from the moment the code is merged to the moment the plan is made.

Comparing the three ways of working:

• Parallel PRs on GitHub: about one run in five with a conflict, and all of those failed.
• Local merge, without the PO: the same share of conflicts, no failures, and almost a third of the cost going to the runs with conflicts.
• Local merge, with the PO: about one run in ten with a conflict, and less than a fifth of the cost going to them.

Something I had never seen in a human team: a flesh-and-blood PO knows the product, but doesn't know which files each task will change. The AI in the PO role does, because it can read the code before planning.

Git compares lines

Even with the PO, one question was left: why did tasks that had nothing to do with each other conflict? Because git compares lines of text and was made for people, who change a few lines at a time and talk before touching the same file, while five agents in parallel each add their own screen, their own route and their own style, all in the same place.

The morning after the night of the five runs, the fixes were all about format, without changing how the app behaves: the same way of marking the end of a line in every file, lists with one entry per line and in alphabetical order, and the documentation tables generated automatically. The slides show the case that sums it all up, a line that loaded several modules, and the ways out, from the simplest to the one the factory adopted later:

With several agents in parallel, the format of the files becomes an architecture decision.

Where the conflicts live

The format solved the silliest conflicts. But they kept showing up, and always in the same files.

When the AI counted, among the factory's 35 runs that had delivered code, how many had touched each file, the picture became clear. Half of the files had been touched by a single run. The main file of the screens, index.html, had been touched by 23 of the 35.

The conflicts didn't spread across the code. They piled up in a few central files, the ones that register screens, channels, routes and styles. Every new feature had to go through them. The first six on the list added up to about 11,600 lines and worked as mandatory meeting points.

An architecture organized for people does exactly that. A central file that registers everything is great for whoever reads it: it's all in one place. For five agents writing at the same time, it's a narrow door.

October 1: the architecture rewritten not to conflict

In the late afternoon of Thursday, October 1, the factory ran an epic, a set of tasks with a single goal: reorganize its own code so it would not conflict. No change in behavior, only in format. It was the reorganization I mentioned in passing in chapter 1, before the second night.

The principle was simple: a new feature adds files, it doesn't edit shared files. In practice:

• One folder per screen: ten screens left the central file and got files of their own.
• Generated lists: the list of what index.html loads started being built automatically, from the files that exist.
• A minimal structure at the center: the main file of the interface kept only the skeleton of the app.

The files everyone touched shrank:

• The main file of the interface (app.js): from 3,932 lines to 953.
• The index.html: from 1,383 to 334.
• The central file of the service: from 1,767 to 115.
• The giant test file of the service: split by area.

The result is an architecture that isn't common. For a person, it's worse to read: what used to be in one file is now spread across dozens. But the goal was something else. It was to let several AIs work at the same time without bumping into each other. The epic itself ran in six runs, without a single conflict.

The second night, measured

The second night, the one I told in chapter 1, was the first one after the reorganization. With the door wider, the PO put up to five runs at the same time, against two on the first night. There were about 25 tasks. There were four conflicts, and all four were resolved without me, with no failure when merging the code.

The numbers per file showed the reorganization had worked. Before, one commit in three touched app.js or the central file of the service. That night, it was one in eight on app.js and almost none on the service.

More tasks per hour, though, didn't mean cheaper tasks. The factory delivered almost half again as many tasks per hour of clock time, and every thousand lines started consuming almost half again as many tokens. The reorganization took the bottleneck out of merging the code, and the extra cost came from somewhere else, from the turns of the test agent. That math is in chapter 4, The bottleneck isn't the code, it's the tests.

And new meeting points were already showing up: the project's main documentation and the script that takes the screenshots. That's why the conflict map was born. It is computed by the engine ⚙️, without calling any AI, from the history of the runs: which files and which lines the most runs touch. The PO checks the map to build the stages and proposes breaking up the hot spots before they become conflicts.

What the format doesn't solve

Not every conflict is about format. When two tasks change the same behavior, for example two different rules for what happens to an overdue task, the conflict is real. No tool is going to decide which rule wins.

When I went looking for ways out beyond git, I found three levels:

• Repository format: one file per thing, lists with one entry per line and generated tables. It removes most text conflicts, and it's where I started.
• Merging that understands code: tools like Mergiraf compare the structure of the code, not the lines, and work inside git itself.
• Another version control model: Jujutsu, compatible with git, and Pijul treat a conflict as a state that can be saved and resolved later, without blocking the workflow. It fits better with many agents in parallel.

None of the three solves the behavior conflict. For that one, the answer is still to plan ahead. The PO predicts the files each group will touch, points out where there may be a conflict and separates the groups into stages, the way a database lock manager decides who writes first. Even so, conflicts didn't get to zero: with the PO, 3 of 27 runs still had to resolve one.

When I wrote that, the AI agreed with the core and adjusted the edge. Maybe the boundary isn't the person, but the area of the code: if each person owns a module, with their own PO and their own roadmap, several can still fit in the same repository, as long as the areas don't overlap. One repository per person would be the extreme case of that same idea.

One thing didn't change with any of this. The code is merged on my computer, but sending it to GitHub is still a decision of mine, and the automation doesn't go past a human approval.

The next step

Planning ahead solved the conflict. The PO predicts the files, separates the stages, and the night runs without bumping. But not everything is worth predicting. On the morning after the first night, I woke up to finished screens that nobody had designed before, and I realized it was easier to judge a finished screen than to describe one that didn't exist.

In the next chapter, chapter 7, Refine first or react later?, I tell when it pays to plan every detail and when it's cheaper to let the factory deliver and react to what's done.