Transcription
Welcome. Today I'm about to show you how you can leverage a single small markdown file to fix your AI coding agent's biggest issue ever. My name is Yan. I'm the developer of Agent Zero and Space Agent. And today I will show you how to properly use Docs. It is extremely simple. No installation, no requirements. And the best part is that it actually fixes the issue.
So now what is the issue? Obviously is the reliability of coding AI agents and we all know the symptoms. You give your AI agent the task. It will do the task but in a wrong place breaking your conventions duplicating functionality instead of extending a function that could have just one line addition. It will create a brand new helper module etc. Your codebase will bloat and this makes things even worse for the future. And you know how this ends right? Never-ending cycles of debugging, fixing one thing breaks another, your agent is confused from all the code, etc.
So now I will show you what Docs actually is, why is it so simple and why it works so well, why did we develop it and how can you use it in your project. So first we need to identify what is the real problem here. The issue is not intelligence, it's context awareness. Because your agent is already smart enough, your LLM is smart enough to do any programming work better than you can. But where it fails is maintaining large code bases because it doesn't see behind the corner. It does not know the context of your full codebase. And that's why it makes these simple mistakes because it simply cannot see the big picture. And throwing more tokens at it. That's not a solution. The question is not how do we give it more context. The question is how do we give it exactly the right amount of context it needs. Not more, not less, minimum context required to make the minimal edit and that's it.
Now to understand why did I develop Docs, we need to take a look at Space Agent because this is where it started. Space Agent, if you don't know what it is, it's an AI agent that runs completely in the browser runtime. It can execute code. It can generate its own UIs on the fly. It can communicate to external services. You tell it to build you something, it will build it on the fly right away in the browser. And it has a ton of advanced features like user management, groups. It is extensible in many many ways. It has a large code base, a lot of layers, a lot of concepts, a lot of cool features like the time travel and it was completely developed by AI. I didn't write a single line of code on this project. And it took me about 3 weeks to completely develop, polish and publish this. And so since the very beginning, I knew that I cannot be writing code here. It's not possible in 2026. You need to have a team of agents that will do this for you, but you need them to do it reliably and to write good quality code, maintain the right principles and best practices etc.
And so the very thing I did inside Space Agent was creating this agents.md file where back then it wasn't called Docs framework. It was just the first prototype of a self-documenting framework built specifically for the Space Agent project. But it was mostly what Docs framework is now. It explained to this agent to read documentation before editing, update documentation after editing, maintain the documentation in a hierarchy corresponding to the codebase and how the documentation should look like. So like we say here, Docs is a self-documenting agents.md framework. The big difference here is that it's not a single agents.md file. It's not a documentation that's detached from the codebase somewhere. What we are used to a lot of projects have their documentations in a wiki somewhere or in separate folder. Here we tightly couple the documentation with the codebase. And I can show it to you here. This is the codebase of Agent Zero for example. It's a very large project, very large codebase, very deep and it all starts with the top-level agents.md file. Here we have our original Agent Zero instructions and somewhere here starts the Docs framework which is one of the beauties of it. You can simply take the markdown from the GitHub repo, copy paste it into your existing agents.md. It does not mess up your existing instructions. It just adds the let's say responsibility to your agent for the documentation.
Now the agent knows that it needs to crawl the hierarchy of agents.md files because each agents.md is created in every subfolder throughout the codebase except for some temporary files and garbage etc. And every agents.md file is responsible for a single domain, a single folder, but it contains a child docs index. And we are now in the top-level agents.md. And here we have our subfolders agents, API, configuration, docker, etc. Each of these have their own agents.md files inside that document that one specific domain. And for example in the agents we will once again find child doc index at the end documenting individual agents inside of the system. And why this tree structure is so important is that this way the agent can always take the fastest, most straightforward path to the place where it needs to make the changes. So if I tell the agent, create an API endpoint for me, right in the top agents.md file that the agent can see at all times, it can see that there is a documentation for API endpoints, here is a short description, HTTP API handlers and WebSocket handler entry points. The agent will open that file, read about the purpose, ownership, local contracts aka rules, work guidance, how to test and verify. So the agent can quickly navigate to the relevant place, make the minimal edit, and most importantly, after any edit, update the documentation files, which keeps the documentation in sync with the actual codebase.
And I know this may seem like a simple concept. It actually is. And it may be hard to believe that this actually brings any real benefits to AI agents. But the difference between the input and output, what I mean is the size of the addition to your codebase, no installation required, no manual work, and the output in terms of code quality and agent efficiency is so disproportional here that we had to release this as a standalone product. I say product, but of course it's open source. Just go and copy paste it. And we can probably best see it on the Space Agent itself, which was completely AI coded. We can take a look at the top-level agents.md and it will point us to the front-end application, commands, packaging, server, test. We can take a look into the server documentation for example. And this will point us further into API endpoints, jobs, library, pages, router, runtime. You get the idea. Everything is thoroughly documented. The agent updates all the relevant documentation, not just the closest agents.md file to where the agent does the edits, but also the parents if that is relevant. So if we change something about the concept, if I tell the agent that I want him to use different coding practices, different styling, formatting, whatever, it can update this in the parents files agents.md. And this will be reflected anywhere down the tree because as the agent navigates the documentation hierarchy from top to bottom, it will keep in the context window all the information and instruction from the parents agent.md files and all the detailed instructions from the end of the tree. So once we get, once we get deep enough like into, I don't know, maybe jobs here, we should have more specific instructions, function names, etc. to the problem at hand in this folder. But in the parents, in the server for example, we will have higher-level instructions where to put stuff, how to work, how to organize code, etc. And all of this compounds as the agent traverses the tree. So no information is lost. Even is even if something is in a different branch of the tree, it can still be linked in the docs index or in one of the sections above. If you have a shared functionality like helpers, they can be in a different part of the tree and the agent can still link them together using these markdown files. So these markdown files are like a preview of the whole codebase. It's like a map for the agent and the agent only navigates the map until the point it needs to touch the actual code. And so we don't pollute the context window with any irrelevant information. It can see all of the documentation files on the path to the target. It doesn't see any of the sibling folders unless they are manually linked because they are relevant.
Okay, enough talking. I guess I can show you how you can implement this into your own repository. It's, it's very simple. All you need to do is open the agents.md from the Docs repository. Simply copy the file and let's go to terminal.
All right, I am in my terminal. I have cloned our Agent Zero connector that is a repository that is not yet documented. So I will now simply start Codex here and I will tell Codex, add this at the end of agents.md here or create. I don't know if there's already agents.md in this repo. I don't really care. Codex will take this, add it at the end of the agents.md and then I can tell it, now initialize the docs index. Okay, I'm putting this to queue. And so now agents.md is either created or edited with the Docs framework appended at the end. And so now Codex will understand what Docs means because agents.md is always included in the system prompt or in the context window. And now that I have told it to initialize the doc index, it knows what to do. It will start reading through the codebase and creating this agents.md documentation points throughout the repository and linking these files together. It will probably take a few minutes because the LLM needs to read through all of the codebase or most of the codebase and manually write these documentation files. But in a bit we should be able to see the first result.
Okay. So it took about 5 minutes to index the existing codebase. This is not a particularly large one. These are the agents.md files created in the subfolders for dev tools, documentation for the source, for different screen styles, etc. So let's see how it went. Okay. So this is the top-level agents.md. There were some instructions and links previously. So Docs will start somewhere here. Here we have it. And here we have the child docs index. So we can take a look into, let's say, source screens. And here we have the ownership, parent package, rules, control app, integration commands, protocol, screens should return typed results, data classes or none, and no children under screens. We can enhance this. I can tell, I want to enhance the documentation of screens. I want all the Python files in the screens folder to have their own documentation. The same file name with markdown appended at the end. And they will document individual screens and they will be listed as child docs indices in their parent documentation file. And just like that, if we have something in our project that is not separated enough, like in Agent Zero, we for example have a helpers folder which contains maybe 100 scripts by now. We can do it like this. We don't need to separate it into subfolders. We can simply tell the agent we want to change the documentation structure for this particular folder. We want to document each of these files individually and it will simply put the rule into this agents.md file which will make it be applied only for this folder and this folder can have its individual files documented separately. We can do this for any folder throughout the repo. We can tell the agent we want to do this for every single folder for the repo and in that case the agent would put it into the top-level agents.md. It's up to us. The framework is really simple and customizable. You can simply tell the agent that you want to do something differently and it will apply it to the correct agents.md files. And we can see the update here. So the agents.md in screens was updated somewhere here. It tells that every Python module in this folder must have a sibling markdown document. And just like that, every file in this folder is now documented.
And let's do some edit. What do we have here? We have installed plugins. Okay, I'm going to tell the agent that I want to change something in the plugins view. I want to change the plugins view to have a different background color than the others. Once the user opens that screen, I want the background to change from black or whatever we use now to red. And obviously I have no intention in keeping this edit. I just want to demonstrate how will Codex proceed. I will update the installed plugin screen styling. I will reread the applicable doc chain. This is the important part that the agent will read the doc chain because it may have been changed. So it will start from the top, read through all the documentation, find the right documentation file for the plugins screen. I am looking at the existing installed plugin selectors. Now the likely change is in a screen-scoped CSS rule. I have no idea what it's talking about, but now it has all the documentation. I don't need to worry about it. All right. So, we have changed the installed plugins screen backdrop to red. The inner plugin stays dark. Updated the markdown documentation and verify the syntax. And of course, this is compatible with any AI agent that supports agents.md. In Agent Zero, you can do this in project. For example, when you create a new project, you can put it directly to the project instructions or you can create it as an agents.md file inside that project. The agent will see it or you can simply tell your agent to clone agent0/docs repository into your current workspace. It will do it for you.
So, this is the life-changing markdown file you've been looking for. You can thank me later. You can give us a star. We only have 41 of these by now. It's really fresh. You can subscribe to our channel if you like what we do. And see you next time.