Wiki, tracker and code graph instead of RAG for AI agents
The question every agent setup has to answer
An AI coding agent starts each session knowing nothing about your project. It does not know your architecture, your conventions or the decision you made last month. Something has to fill that gap before it writes code.
We look at this from one angle: an agency team that builds websites and apps for clients. That usually means several projects at once, each with its own stack, history and decisions the client signed off on. The agent's job is to change a real codebase without breaking what was agreed.
The common answer is RAG, retrieval-augmented generation: a system finds text that looks relevant and pastes it into the prompt. Our setup with CRUX takes another route. The agent gets three sources, a project wiki, the task tracker and a graph of the code, and decides for itself what to read.
This post explains why, and where RAG is still the better tool.
How RAG works, in plain terms
A RAG pipeline splits your documents, and often your code, into chunks of a few hundred words. It turns each chunk into an embedding, a list of numbers that captures its meaning, and stores those in a vector database. When a question comes in, it finds the few chunks whose numbers are closest and pastes them into the prompt.
That works well for a support bot. For an agent changing a real system, it has known weak spots. A chunk loses its surroundings: the heading above it, the exception in the next paragraph. Old and current text that sound alike compete, and the search cannot tell which one is true today. The agent cannot see what was left out. And someone has to run the pipeline: chunking, embedding, re-indexing, the database.
Three sources the agent reads itself
In our setup each source answers a different question:
- The tracker answers "what" and "what happened before". The task holds the request in the human's own words, plus comments and the artifacts that earlier agents posted on it.
- The wiki answers "how" and "why". It is an Obsidian vault: plain Markdown in git, pages linked with
[[wikilinks]], anindex.mdas the entry point. Concepts, features, decisions and conventions, one subject per page. We explain it in Our project wiki: memory that AI agents can read and write. - The code graph answers "where" and "what depends on it". We use GitNexus, an open-source tool that indexes a codebase into a knowledge graph of symbols, calls, dependencies and execution flows. The agent queries it through MCP tools: who calls this function, which flows pass through it, what may break if I change it. Instead of "find code that sounds similar", it gets an exact answer from the parsed structure. Check its license before you adopt it.
Modern coding agents such as Claude Code have long context and file tools. They open the wiki index, follow links, grep, read whole pages and query the graph, the same way they work with code. Nothing is pre-chosen by a similarity score. If the agent needs more, it reads more. If it needs less, it stops: the context window holds what this task needs, not every chunk that scored well. A lean context keeps the agent focused.
Here are the five reasons we prefer this to RAG.
1. It is easy to set up
A wiki is a folder of Markdown files in git. GitNexus builds its index locally with one analyze command. The tracker is one your team already uses.
There is no embedding pipeline, no vector database to host, no chunking strategy to argue about and no re-indexing job to tune. When an answer is wrong, you open a Markdown file and fix a sentence, instead of debugging similarity scores. The how-to is in How to set up a project wiki for AI agents in 30 minutes, and the open obsidian-skills collection teaches Claude Code to write Obsidian Markdown.
2. A human gate, in tools people already know
RAG is a hidden step. Nobody reviews which chunks went into the prompt, and nobody can correct them.
In our setup people follow the agent's work where they always have: tasks, comments, statuses and pull request review. Each agent posts its result as an artifact on the task: interview answers, requirements, a plan, a summary of the change. At the checkpoints, where a wrong turn is still cheap to fix, a person approves or corrects it before later steps build on it. We describe that chain in Stop writing prompts: why AI coding agents need a workflow.
So the context the agent works from, and the decisions made along the way, are visible and editable. If an artifact is wrong, a human fixes it in the task, and every later agent reads the fixed version.
3. Pre-AI methods still work, so we built on Agile
We did not invent a new methodology for AI. Epics, stories, tasks, clear acceptance criteria, small increments, code review and retrospectives existed long before coding agents.
A well-written task helped a human developer understand the job. It helps an agent in exactly the same way. A clear acceptance criterion is a better guide than any retrieved paragraph, and a small increment keeps a mistake small and easy to review.
On top of that runs a structured workflow. Each task status has its own agent, skills and rules, and the next session starts from a ready template in one click. Nobody rethinks the prompt for every task, sessions for different tasks run in parallel, and development moves faster.
4. "Why is this code written this way?"
This is the question RAG answers worst. Similar-sounding text rarely explains a specific line.
In our repository every commit message carries the task key, and a commit hook rejects a commit without one. A short instruction in CLAUDE.md, the agent's rules file, tells it how to use that. When the agent needs to know why some lines exist, it runs git log -L or git blame on them, reads the task key from the commit and opens the task.
That gives it the original request, the discussion in the comments and the artifacts: the intent behind the code. It costs one git command and one task read, and it is exact. No similarity search can match that.
5. Task relations show the neighbourhood
Tasks are linked: blocks, blocked by, parent, related. The agent follows these links the way it follows wikilinks. It can see what was done before this task, what is waiting on it and which earlier tasks touched the same area. That is often where the real constraints are, and it is the kind of context a top-k search simply does not know to fetch.
The wiki stays true because it is curated
Letting the agent read only helps if what it reads is true. In our pipeline the last step after code review is a wiki curator agent. It reads the actual change and rewrites every page the change made false, so a page states the current design, not a changelog. History lives in git. Humans read and fix the same files in Obsidian.
A reliable source also changes the agent's behaviour. If a request quietly contradicts a decision the team accepted earlier, the agent finds that decision page while reading for the task. It notices the conflict and asks a clarifying question instead of building on the wrong assumption.
Side by side
| RAG | Wiki + tracker + code graph | |
|---|---|---|
| Who picks the context | A similarity search, before the agent starts | The agent, while it works |
| What it reads | Chunks of a few hundred words | Whole pages, tasks and exact graph answers |
| Context load | A fixed top-k, useful or not | Only what the task needs |
| Freshness | As of the last re-index; old and new text compete | Wiki pages rewritten after each change; graph re-analyzed from code |
| Setup | Chunking, embeddings, a vector database, re-indexing | Markdown in git, one analyze command, your tracker |
| Human control | Hidden step nobody reviews | Artifacts in tasks that people approve or correct |
| "Why does this code exist?" | Guesses from similar text | Commit, then task key, then task |
| Good at | Large, messy corpora nobody will curate | A project's tasks, design, decisions and structure |
When we would still use RAG
RAG is the right tool in plenty of cases:
- The corpus is huge or unstructured. Thousands of support requests, years of chat logs, a shelf of PDFs. No agent can read all of it, and nobody will turn it into a wiki.
- Nobody will curate the content. A wiki that nobody keeps current rots. A search index over raw material is at least honest about what it is.
- You search across many projects. "Who solved this before?" across dozens of repositories is a search problem.
- The model has no file tools. A plain chat model that cannot open files needs someone to choose text for it.
An agency also often builds RAG into a client's product: a support bot, a search over the client's documents. That is a product feature, and RAG is a good fit there. This post is about something else: how your own team's agents understand the project they are building.
The two can live together
This is not either-or. A team might keep RAG over raw archives, such as old support requests or call transcripts, and keep the wiki, tracker and code graph as the source of truth. The agent searches the archive for leads, then checks the wiki for what holds today. When they disagree, the wiki wins. If the archive turned up something real, the curator folds it into a page.
The cost moves, it does not vanish
Reading is not free: the agent spends tokens on whole pages and tasks. But it reads only what the task needs, usually a handful of short pages, the task and a few graph queries. A fixed top-k of chunks fills the context whether or not they help, and every irrelevant chunk is noise the agent has to work around. Short, single-subject pages help a lot.
What you save is the pipeline, and what you gain is control. The tracker holds the task and its history, the wiki holds the current design and decisions, the graph holds the exact structure, and commit-to-task links tie the code back to intent. The agent picks what to read with its own tools. RAG picks for it.