Documentation Is Context: For People and, Now, for AI

The AI you use at work has the same problem as the developer who just joined your team: nobody explained anything to it. I saw this problem happen with people years before I saw it happen with AI. And the solution was the same in both cases.

The problem: explaining everything, every single time

About six years ago, I was working on a front-end team that was growing fast and had a lot of demand.

There was no onboarding. Every new person had to be trained from scratch, and the same explanation was repeated with each new arrival.

On top of that, part of the team's knowledge was concentrated in just a few people.

That's when we decided to start documenting.

Taking the initiative

I started driving this effort together with the team: bringing our agreements, our standards and everything we used day to day into a single place.

But documenting wasn't enough: the documentation kept getting outdated. So I did two things.

The first was showing the team why documentation mattered.

The second was creating the Guild, sessions where someone on the team shared what they knew with everyone else. Every session turned into documentation.

What changed in the team

After that presentation, the team truly got on board. People started using the documentation not only to look things up, but also to record what they were doing. Documentation stopped being "one person's thing" and became everyone's responsibility.

The Guild also helped bring the team together: presenting to the group became more natural, even for the shyer ones, and no one was the sole owner of a project anymore.

The biggest lesson for me was that no tool solves this on its own. What changes a team is people understanding the why.

Today, documentation is context for AI

Years later, I use AI every day to build software. And I've realized that everything I used to advocate for has become even more important. AI is like a new developer joining the team: it only does good work if someone explains how things work.

The difference is that, for AI, that explanation has to be written down. A well-crafted prompt, a reusable skill or a file with the project's rules works as a mini documentation: it tells the AI what the standards are, what it can and can't do, where to start and where to stop.

To make it concrete, it can be as simple as this. On the project I work on today, I set up an agent hook with rules like these:

# Project rules  - Do not create translation files. Translations are generated automatically after merge. - Do not invent requirements. Do only what was asked. - Make the minimum changes necessary. - Reuse first: look for an existing component or function before creating a new one. - Constants go in a dedicated constants file, never scattered in the code. - Be token-efficient: don't explore the whole project when the location of the change has already been given. 

Just a few lines, but with them the AI stops guessing and starts working the way the team works. Before, every time I asked for a task, it would create all the translation files at once, files that shouldn't even exist in that project. One rule fixed it.

When this context is already written down, I see three benefits:

• The AI gets it right sooner. During a system migration, someone on the team had already written down this context, and the AI followed the right path from the start.
• Results are consistent. Whether someone joined yesterday or has been on the team for years, everyone gets the same guidance.
• Usage is more efficient. With a clear scope, the AI doesn't do what wasn't asked and doesn't waste effort, or tokens, exploring what it doesn't need to.

And, just like with the team's documentation, this context only works if it's shared and maintained. A prompt that only one person knows about repeats the old problem: knowledge stuck with a single person.

The lesson was the same: the problem is rarely the tool. It's almost always the lack of context.

Wrapping up

Before, documenting was a way of taking care of the people on the team: those who were just arriving, those who were overloaded, those who felt embarrassed to ask. Today, on top of that, it's how you get AI to work the way your team works.

A well-written prompt, a skill, a project rules file: all of it is documentation. If you've learned to document for people, you already know half of what you need to work well with AI.