Grab a coffee, this is a bit of a long story.

I recently realized that I haven't named a variable in a long time. Seriously. The me who used to spend five minutes deciding between userList and users has hardly written any lines of code in recent months. But my workload didn't shrink, it just moved somewhere else. If anything, it went the other way: since the amount of code being produced went up, the mental fatigue went up with it.

In this post I want to talk about that shift, what I went through while starting to use AI in our team, and the thing I least expected: how I started taking documentation seriously.

A very simple task, wrongly written code⌗

The first lesson came from a very simple task. I gave an agent a job, it wrote the code, and it looked clean and confident. But it was wrong.

When I looked into why, the problem wasn't the model, it was the document I had given it. What it described was actually simple, but the document was written in such a roundabout, corporate language that even a human would have needed a while to work out what was being asked. The model tried to work it out too, and produced something that looked perfectly reasonable with its own interpretation, but was wrong.

That was the moment I understood this: the model wasn't lying to me. It read whatever I gave it and believed it. When a human reads a badly written document, they fill in the gaps with their own experience, thinking "they probably meant this". The agent fills them in too, but with its own guess. Some people call this "confident fiction". I think it's a very fitting name.

Writing context, not code⌗

After a while, the way I work changed completely. My job became less about writing code and more about finding the right points inside the necessary documents and handing them to the agent.

My flow went roughly like this:

  1. I find the parts that really matter among the related documents, the Jira ticket and the relevant pieces of code.
  2. I write them in plain language the agent can understand into a TASK.md file: what will be done, where the boundaries are, what will not be touched.
  3. I have the agent do the task.
  4. Then I have another agent review the code that was written, and I take a look last.

What I noticed is this: when TASK.md is written well, the result is good. When it is written badly, or when the source document is lost in that corporate fog, the result is too. So what taxes my brain now is no longer the code itself, but describing correctly what is wanted.

At some point I caught myself working more like an analyst than a developer. But we shouldn't underestimate the load analysts carry. I was gathering context from ready-made documents. They are the ones running between teams, collecting the right context and the real needs when those documents don't exist yet. The hard part of what I do has usually already been done by them.

Speed went up, and so did the fatigue⌗

There is also a side of this that doesn't get talked about much. When production speed goes up, the work doesn't finish, it multiplies. When a task is done much faster than before, the next one arrives immediately, then the one after that. The number of tasks passing through my hands in a day has gone up, and each one means a separate context.

In the morning I'm looking at a service's bug, at noon I'm writing another project's TASK.md, and by late afternoon I'm reviewing a third piece of work. I'm not writing the code, but all of it has to sit correctly in my head. This constant context switching can be far more tiring than wrestling with a single function for hours, like I used to. The agent is fast, but the head behind it is the same head.

If agents can't see it, you have to show them⌗

Everything with us runs on VS Code, which is approved for use inside the team. We have GitHub Copilot access, and we use Claude too. But MCP was turned off. So the agent sees the code, but not the rest of the job: what broke in Jenkins, which error showed up locally, what the Jira ticket says.

So I sat down and wrote a few VS Code extensions so agents could reach those things:

  • Hawk: For tracking Jenkins. The agent can see for itself what happened in a build.
  • Falcon: While I'm working locally, it collects the VS Code output as a stream and exposes it as lmtools. That way the agent can reach error logs directly, and I don't have to copy and paste.
  • Owl: Gives access to the logs of pods deployed on active-active clusters in OpenShift.
  • Wildgoose: For access to the Data Center editions of Jira, Confluence, Graylog and Bitbucket.

All of them started from the same point: an agent knows whatever it can see. About what it can't see, it guesses, and where it guesses, it makes mistakes.

Rolling it out to the team: not everyone arrives at the same speed⌗

Writing the tools was half of the job. The other half was getting my teammates to actually use them.

I spent quite a lot of time on AI adoption inside the team. I sat at the computers of colleagues who came to me, we installed VS Code together, loaded the extensions, and I showed them one by one how to work with an agent, how to check Jenkins status through Hawk, how to look at pod logs through Owl. Some got it after seeing it once, some came back a few times. Both are normal. Getting used to a new way of working takes longer than learning a new tool.

An interesting picture came out of it. Developers adapted very quickly. That's not surprising, really: these tools are closer to our world, and on top of that we got access to Claude and Copilot earlier than the analysts did. The analysts got access later, so they came in a little behind.

But here is the part that really made me think: now that producing code costs so little, I believe a significant part of a developer's time should go to technical documentation. Because that is what the agent needs most. And when that change happens, analysts need to move closer to the developer side too. The two roles are drifting toward each other, and the place where they will meet is a well-written, up-to-date, plain document.

My dream documentation⌗

Let me be honest: we haven't moved to Docs-as-Code yet. But we are working on turning our direction that way. For me the most important part of it isn't the tools, it's the mindset. I'm trying to pass on the idea that "a document is also an input the agent reads" to my teammates, and to bring developers and analysts onto the same level. I don't want whoever got access first to start ahead. I want everyone to walk from the same place.

Docs-as-Code, briefly, is this: taking documentation out of Word and the forgotten corners of Confluence, and managing it in the same place and with the same discipline as code. It lives in the repo as Markdown, changes go through a PR, CI catches broken links and pages that don't build, and a feature whose documentation hasn't been updated doesn't count as "done".

What I have in mind is something like this: documentation based on Docusaurus, living next to the code in Bitbucket, but not cut off from Confluence either. So the team can keep reading from the place they're used to, while the source sits in the repo and changes together with the code. That way both people and agents look at the same, up-to-date source.

We're just starting the new setup. I'll write separately about how it goes.

Final words⌗

Before I started working with AI, documentation was something I did at the end of a project "if there was time". And since developers aren't expected to produce technical analysis documents at the company, that time never came. Now it has moved in front of the code. Because the code is now largely written by an agent, and the agent only knows as much as I tell it.

If you work with agents too, and you have those moments of "why is this so confidently talking nonsense", take a look at your documentation as well. In my experience, the problem was most often there.

If you finished before your coffee went cold, good for you.