Context Belongs Where the Agent Works
New feature, new ticket. I read the description and two paragraphs in I realize: this is half the story, at best. So, off to the wiki. There has to be a concept page for this somewhere. Three search terms later I've found it, or at least some version of it. Then Teams. Wasn't there a thread a few months ago where we decided to do it differently after all? Scroll, scroll, found it. And whatever isn't written down anywhere, well, the colleague two desks over knows.
In the end I'm sitting there with a pile of snippets. A bit of ticket, a paragraph from the wiki, two chat messages, my own notes. I copy it all together and dump it into the agent so it even knows what this is about.
And then, a good while later, the actual work starts.
The agent only knows what it sees
These days the agent writes most of my code. That works really well, but only if it has the full picture. Not just the one file, but why the system is built the way it is, what's hanging off it, and what's been tried before and thrown out.
Sure, you can connect a lot of things. Wiki via MCP, tickets via API, some internal chatbot. All doable. But every tool is one more step: one more connection, one more login, one more place you have to remember to keep up to date. That's friction, and friction means the context is missing exactly when you need it.
Close, fast, simple
My point is actually simple: context has to live close to the agent, be quickly available, and be easy to access.
For me, today, that means: in the repo, as Markdown, right next to the code. The code is already a lot of documentation. What's missing is everything around it: the idea behind it, decisions, things you deliberately didn't do. I write that down and put it right there.
Nice side effect: code and docs change together. I used to rework something and then think: oh right, that's in the wiki too. And then of course I forgot anyway. Now the agent updates the docs in the same step, and they go through review like everything else. Even diagrams are just Mermaid in the text.
What that looks like for me
In my own projects, all the documentation lives in the repo. On top of that, proper pipelines, a release tool, and a few skills for things I do all the time.
A typical evening goes like this: I notice a bug. I describe it briefly, the agent finds the spot, we fix it together, and then I say: "Okay, now cut a release." And that's what happens. No searching, no explaining, no copy-pasting.
It even goes beyond the code. My stuff runs on my own VPS, and the agent knows how it's set up: which reverse proxy sits in front, how the containers are organized, where the config lives. That's in its own skill, because I didn't feel like explaining it every single time. When I want to get a new project online, I just say: "Hey, we want to deploy this, write everything we need for it." A few minutes later, everything I need is there.
Less typing, more steering
What's changed the most: I barely type anything myself anymore. I read, review, and decide. I set the direction and put up guardrails so the thing is still maintainable a few years from now.
I also hand off a lot more, including small stuff. Some port is taken and the dev server won't start. That used to mean googling how to find the process blocking the port, then googling how to kill it, then trying three commands from Stack Overflow. Now I tell Claude or Codex: "Port 3000 is taken, free it up." I do something else in the meantime, and when I come back, it's done.
Same with knowledge. I don't have to keep every detail in my head anymore, and I don't have to wait until someone has time for my question. I just ask.
But the reason I can hand off this much is that I learned the craft behind it at some point. Over the years you develop a feel for what's good and what isn't. And because you know what options are out there, you also notice when the agent is overengineering again or just picking the worse approach.
AI is a good tool, but it's still a tool. If you know what you're doing, it makes you really fast. If you don't, you don't just produce code faster, you mostly produce garbage faster: code nobody thought about, and architectures that blow up in your face six months later.
And in a team?
In a team I'd do exactly the same: docs as Markdown in a docs folder in the repo, not scattered across five tools.
You could take this further. Here's an idea I'm not sure holds up in practice: everyone gets their own folder in the repo for notes and thoughts, and an agent regularly tidies up and pulls the important bits into the shared docs. Then the agent wouldn't just know what's in the code, but also what people were thinking. Whether that actually works or turns into a graveyard after three weeks, you'd have to try.
Maybe the future is just Git. A folder full of Markdown files where humans and agents work together, instead of five tools that each know a little bit.
That leaves the people who don't have anything to do with Git. Honestly, I don't see a problem there. You need a clear convention for the folder and a nice interface on top that lets anyone comfortably read and edit. With AI you can build something like that really quickly these days, and everything's still versioned.
Time to look at your own processes
In the end it's not about a specific tool. The way we build software is changing quite a bit right now, and our processes often haven't caught up. A lot of the time we still work as if a human has to find every piece of information themselves and keep it in their head.
AI is here to stay. So it's worth taking an honest look: where do we actually store knowledge? How quickly can you get to it, as a human and as an agent? And how much time goes into hunting things down every day?
If you rework things a little, you don't have to copy anymore. You can just start.
PS: Yes, I worked on this text with AI. The thoughts and ideas are still all mine, I just skipped the typing. Less typing, more steering, you know how it goes.