Close the laptop: the documentation got better and the understanding got worse

Every new engineer on our team (hi Kadir and Swarup) learns our system through our agents, going through our documentation and completing their own onboarding. For most of my career that sentence was the dream. Now it is the thing that worries me most about how we work. They learned from the same teacher, and nobody, including me, can tell you whether they got the same lesson. The teacher is a model, the lessons were private conversations, and the teacher has never once said “I am not sure”.

So the question I ask about an engineer has changed. It used to be whether they understand the system. Now it is whether they understand the same system as the person at the next desk, and no document can answer that, because the documents are where the two versions came from. The only way I know to find out is to put both of them in front of a whiteboard, hand them a marker, and listen for the place where the drawings disagree. That is one of the main reasons we work on-site at Integral. It limits who will join us, and I accept that.

The problem used to be the opposite. A couple of senior people held the whole system in their heads and could not, or would not, write it down. Everybody hated that model, and nobody should want it back. The fix was never to get the system out of people’s heads, though. You cannot reason about a system that exists only in a document, and you still have to hold at least the part you are working on in your head to think about it at all. Then agents arrived and fixed the wrong half. Today everything is written down, every engineer works across the whole system, and there is more text about it than at any point I can remember. The overall picture is harder to hold than before, not easier, and an agent can now produce something that compiles, passes the checks, and looks finished before lunch.

Five private models of one system

A big part of our code is generated, and a reasonable part of it gets fixed without anyone asking¹. That changes what a senior engineer’s day is made of. The typing is gone. What is left is deciding what to build, choosing between approaches, and checking that what the agent produced is correct for tax, payroll and accounting, where “almost right” is a wrong number on a real payslip.

It also changes how people learn the system. Every engineer now builds their mental model of it in a private conversation with their agents, using their favorite harness. Our workflows have states, in plain English: open, ready, in progress, in review, blocked, paused, sent, done. Ask an agent which of those needs a human to do something and you get a confident answer. Ask again tomorrow, with different context in the window, and you get a different one, just as confident. Ask which role is allowed to move an item from in review to sent and it gets worse. Nobody notices until two pieces of work meet and disagree.

That is how a team of five ends up with five private models of one system². Each one is consistent on its own, and each came from a source that never says “I am not sure”. More documentation does not fix it, because the documentation is where the drift came from. AI made every stupid idea very presentable, and it made every private model look like the official one.

Karpathy’s line, which I borrowed for the ladder, still holds: we can offboard the thinking, we do not offboard the understanding. The thinking is the working out, the draft, the code, the first version of the plan, and the agent does it well. The understanding is knowing why the result is right, and that stays with the person who signs for it. What I underestimated is that understanding is not only something each person has to have. It has to be the same understanding, or the system is only whole inside a context window. I said in August that it is scary when the only thing that sees the whole system is the AI. It is just as scary when five people see five different systems.

Close the laptop

The drift is in the pull requests, but it is not easy to read there, because each PR looks right on its own³. At the whiteboard it shows up without anyone looking for it. Someone draws the flow, and somebody else stops them in the middle: what happens if this document arrives twice, why does this rule live in the service and not in the domain API, what did you reject and why. If you understand the problem, you answer in a sentence. If you have only read the output, you reach for the laptop. I stand there too, and my boxes get the same questions.

That is why our sessions start with the laptops closed. It is not a ritual, it is the only way to keep the conversation on the problem: with a screen open, everybody drifts back to what the agent wrote, and we end up reading instead of arguing.

The whiteboard is where the private models meet. One person draws the flow, another says “that is not how I understood it”, and we find the gap in two minutes instead of in an incident. We leave the room with one set of assumptions and the same words for the same things. That is what I mean by a shared reality, and I have not found a way to build it over a video call. I would rather have ten minutes of two people arguing about one arrow than a well-formatted page that nobody can defend.

There is a simpler reason too. A day of talking to agents is exhausting. Every answer is confident and every idea is a great one, so the praise stops meaning anything. When a colleague who knows the system looks at your drawing and says it is a good solution, it counts, because they share the picture you drew it from. It also gets you out of the chat window, and that is how a group of people working on the same problem starts to feel like one team.

What five days means

I talk to a lot of engineers in first interviews, and the office question comes up in almost every one. When people hear “five days”, many of them hear micromanagement and a mindless commute: someone counting hours, watching who arrives at nine, treating presence as a substitute for trust. That is a real thing, and it is not what we do.

The default is the office, every day, and in reality it is less rigid than it sounds. We do not track when people arrive or leave, and the hours in a day are flexible. Engineers take a day or two at home when they need to get one thing finished, and the parents leave early to pick up their kids, because this is Berlin after all. What matters is that you tell the team and plan around it, like adults.

What does not work is the other thing: coming in, putting your headphones on at ten and taking them off at six without talking to anyone. You were in the building all day, and you were not on-site. The whiteboard is our answer to cheap async, and it only works if people get up and walk to it. For the record, I do ask people to put their headphones on, but only when I can hear their music.

The trade-off

I believe fully remote and fully on-site companies will both do better than hybrid ones, because hybrid keeps the costs of both and gets the benefits of neither. We chose on-site.

It limits who will join us, and some very good engineers will say no because of it. I accept that trade-off, and I would rather say it here than hide it in a job post. When an agent writes so much of the code, we want to work with people who can close the laptop and explain why. Come argue with me in person.

Footnotes

1. The housekeeping agents. As of the ladder post, about 500 PRs merged without a human touching them in three months. ↩

2. Five is a round number, not a measurement. The point survives at three and at twelve. ↩

3. To catch it in the PRs you would have to lay every PR, plan and agent session from the same piece of work side by side and reconstruct what the goal was. Nobody does that, so we are working on one. ↩