Watch an AI coding agent start a task in a large codebase and you'll see it behave exactly like a new developer on their first day. It searches for a word. Opens a file. Searches for another word. Opens three more files. Reads a migration, then a model, then a controller that turns out to be unrelated.

Eventually it finds what it needs, and it's often impressively right. But a big part of its effort, and its context window, went into getting lost first.

A new developer fixes this by learning the map of the system over a few weeks. An agent starts every session with no memory of the last one. So I started giving it the map up front, as a knowledge graph of the codebase. It has become one of the most useful parts of my Claude Code setup.

Why search alone isn't enough

Agents mostly find code by text search and by following what they read. That works well for precise questions like "where is calculateLateFee defined?" It works less well for questions about relationships:

• "Which parts of the system are involved when a contract gets signed?"
• "If I change how payments are recorded, what else is affected?"
• "How does a maintenance request created in the tenant app reach the staff app?"

The answers to these questions are spread across models, controllers, jobs, events, API routes and mobile screens, often with names that don't share a keyword. Grep finds words. These questions are about connections.

That matters on a system like Kate PMS, which has a web portal, a staff app and a tenant app built around contracts and e-signing, rent and payments, maintenance requests and role-based access. Features cross those boundaries all the time.

What the graph actually is

A knowledge graph of a codebase is simple in concept:

• Nodes are things: files, classes, functions, routes, and concepts pulled from docs.
• Edges are relationships: this class extends that one, this controller dispatches that job, this function calls that one, this doc describes that module.

The tool I use is called graphify, and I run it as a Claude Code skill. It builds the graph from the code and docs, then adds a few things that make it more than a pile of edges:

• Communities. Clustering groups tightly connected nodes, which tends to rediscover the real modules of the system, even when the folder structure doesn't reflect them.
• Highly connected nodes. The classes that everything depends on (your User model is always one) are surfaced, because changes there ripple everywhere.
• Honest labels. Each edge is marked as extracted directly from code, or inferred. That difference matters, as you'll see below.
• A plain-language report that summarises the structure, which is useful to read yourself, not just to hand to an agent.

How it fits into my workflow

The setup is deliberately small.

1. Build it once, update it as you go. The first build takes a while on a big repo. After that, an incremental update only re-processes files that changed, so I refresh it after merging meaningful work rather than rebuilding from scratch.

2. Tell the agent it exists. A graph nobody consults is just a nice picture. A few lines in the project's CLAUDE.md change the agent's habits:

## Navigating this codebase
- For questions about architecture or how modules relate, query the
  knowledge graph first, then open the files it points to.
- Treat INFERRED edges as hints. Confirm them in the code.
- For exact symbol lookups, normal search is fine.

3. Ask relationship questions before big tasks. Before planning a change, I ask the graph what's connected to the area I'm touching, or for the path between two concepts. "What connects contract signing to the notifications module?" returns a short chain of nodes, and the agent then reads those specific files instead of exploring.

4. Give sub-agents a head start. When I split work across sub-agents, each one starts with an empty context. Pointing each one at the relevant part of the graph is cheaper than letting each rediscover the codebase on its own.

What it doesn't do

I'd be overselling this if I stopped there. A few honest limits:

• It's a map, not the territory. The graph points to code; it doesn't replace reading it. Decisions are still made from the actual files.
• Stale maps mislead. After a big refactor, an outdated graph confidently points to things that moved. Update it, or tell the agent not to trust it for that area.
• Inferred edges can be wrong. Relationships guessed from naming or docs are useful hints and occasionally pure fiction. That's why the label matters and why my CLAUDE.md says to confirm them.
• It doesn't fix a messy codebase. Clear names, consistent structure and good docs help agents and humans far more than any tool. The graph just makes a reasonable codebase easier to move around in.
• It's as sensitive as your code. The graph and its report describe your system in detail. I keep them local and out of version control, and treat them like the source itself.

Should you try it?

For a small project that fits comfortably in an agent's head, probably not. Search is enough, and there's nothing to map.

For a codebase with several apps, many modules and features that cut across them, I think some form of map is worth it. It could be a knowledge-graph tool, a well-kept architecture doc, or even a CLAUDE.md that lists the main modules and where they live. The point is the same: write down the structure once, so every session doesn't have to rediscover it.

How do you help AI agents find their way around your codebase today: project rules files, architecture docs, a graph, or letting them search?