Corpus in its own repo: what to include in the directory and what not to – Corpus 3/3
AI
Many assume that implementing Corpus is a massive documentation project. The first version can be created roughly in the time it takes to have a coffee break.
Text: Arttu Ylärakkola
Quick guide for busy people
Talk to us (arttu@rakettitiede.com) to get the Corpus PDF.
Drop the PDF into your project's version control.
Tell the AI: "Read this PDF and let's set up Corpus."
Go for a coffee.
When you get back, the first version of Corpus will be waiting on your machine.
The PDF tells the AI what Corpus is and how to work with it. The rest it infers from your repo. It reads the code, the documents and the history, drafts a directory, and hooks updates into your workflow. There's nothing to buy, install or learn.
And step 1 is not a sales call: we want to hear how you use AI, and both sides learn something.
Pick one repo
Corpus is a directory of Markdown files in the project's version control. The files describe the system at a business level, written so that they can be read by a developer, a business person, or an AI.
Start with a single pilot. A good candidate is a project in active development with plenty of user journeys and processes: orders, approvals, roles and edge cases.
A bad candidate is a tightly specified, purely technical API microservice. The code and interface specification already say almost everything about it, and Corpus won't add much.
Don't start from a blank page
The first version isn't written by hand. It's generated from what you already have: Confluence pages, Word and PDF specs, slide decks, architecture diagrams, Jira tickets, ADRs, README files, commit history, and the code itself. The AI handles this part during your coffee break. The Corpus PDF tells the AI what to aim for.
After the coffee comes the part that actually matters. Go through the draft with people who know the business. They don't need to write anything. It's enough for them to say "this is wrong" and "that's out of date". This is a review task, not a documentation project. It requires domain expertise, not technical skills.
What should you put in the directory?
Glossary. What do terms mean specifically in this system and in this company? In software projects, the same thing often has multiple names: one in the database, another in the code, a third in the UI, a fourth in how users talk about it, and a fifth in marketing materials. A shared glossary makes up a surprisingly large part of the value, as it reduces misunderstandings with both humans and AI.
Roles. For each user role, record three things:
what the role is and what it concretely does,
what it wants to do and what it doesn't,
what it needs to see and be able to do, and what it doesn't.
The third point is described at the conceptual level, not field by field. A more detailed description is already in the code, and there's no point copying it into Corpus. The second point—the role's motives—is the easiest to forget, and that's precisely what the AI can't infer from the code.
Processes. What happens, and in what order? Mermaid diagrams work well for this. Their source code is plain text that is easy for the AI to read, and humans get a diagram from the very same file.
What shouldn't you put in the directory?
Plans for the future state of the system. The AI easily gets confused about whether Corpus describes the current or the planned state. Corpus describes what is true now. Plans belong elsewhere.
UI descriptions. The AI infers the user interface from the source code very well. Writing it out as text is wasted effort that will only become outdated.
Anything that quickly becomes outdated. Screenshots are the worst, because the AI takes time to interpret them, and updating them takes up human time.
Connect Corpus to the workflow
A Corpus that no one remembers to update is just one more outdated document. That's why updating is integrated into the daily routine. AGENTS.md, a commit hook, or whatever method suits you tells the AI that Corpus is read before starting work and updated alongside the work. Keep this simple.
One line goes into the definition of done: every pull request that changes how the system behaves also updates Corpus, and the Corpus diff is reviewed.
The good news is that the AI writes Corpus and keeps it up to date surprisingly well. The bad news is that it won't take the initiative to split a file that has grown too long into smaller ones, even though smaller files would let it utilise context more effectively. You need to remind it of that every now and then.
Who is going to read all of this?
It's worth bearing in mind that no one needs to read it cover to cover like a manual. Day to day, people either read the diff when something changes, or the AI's answer based on Corpus. The question is put to the AI, and no one has to hunt for information across files that might be out of date.
The response also adapts to the person asking. A developer gets architecture and trade-offs, while a non-technical product owner gets a conceptual-level answer. This can be fine-tuned by defining different roles as commands or skills.
How do you know it works?
Assess the situation after a couple of weeks. The biggest benefits might not show up in the first commit.
They show up when a poorly written ticket arrives for some complex functionality that the developers don't understand, but the AI is able to explain it using Corpus. Or when a new developer asks Corpus instead of guessing which documents are up to date.
The effort won't be wasted, even if tools change. Development tools in 2030 might be entirely different from today's, but they too will need someone to tell them what the system is supposed to do: the rules, roles, processes, and decisions. Nobody knows what format that will be communicated in then. However, the information is the same as what you are recording in Corpus right now.
And even if the tools change, the work won't be lost. The development tools of 2030 might be completely different from today's, but they too will need someone to tell them what the system needs to do: the rules, roles, processes, and decisions. Nobody knows what format it will take then. The information, however, is the same as what you record in Corpus now – and the tools of 2030 will be able to read Corpus too.
Read all parts of the Corpus series:
1/3: Technically perfect, practically wrong: why fast code creates cognitive debt
2/3: Code wrong, Corpus wrong, or both? Three contradictions that reveal more than tests
3/3: Corpus in your own repo: what to include in the directory and what to leave out (hang on, you just read that one!)
What is Corpus?
Corpus is a directory of Markdown files in a project's version control. They describe the system at a business level: the glossary, user roles and their motives, the flow of processes, and decisions made. The files can be read by a developer, a business person, or an AI, and they are updated whenever the system's behaviour changes.
The code tells the AI how the system works. Corpus tells it why.
Corpus is not a product, nor does it require a licence. It is simply a version-controlled directory of text files, so it works with any language, tool, and methodology. We don't claim to have invented it. We gravitated towards this way of working in our own projects and named it Corpus.
Example repo: github.com/rakettitiede/corpus