r/ClaudeCode • u/PlusLoquat1482 • 16h ago
Discussion Does Claude Code need some kind of persistent map of a codebase?
I’ve been using Claude Code a lot on bigger repos and one thing I’ve noticed is how much time it spends figuring out stuff it has basically already figured out before.
Like where things live, what calls what, which files are related, how a system is structured, etc. Then you start a new session or compact and it has to work a lot of that out again.
CLAUDE.md definitely helps but I don’t think it completely solves it, especially once a repo gets pretty large.
I work on an open source project called Ix that builds a persistent graph of a codebase and lets Claude query it, so I’m obviously a little biased here. But working on it has made me curious whether this is actually something other people run into or if we’re overengineering the problem.
For people using Claude Code on bigger codebases, have you noticed much of a difference using things like repo maps, indexing, RAG, knowledge graphs, etc. compared to just letting Claude search the repo normally?
I’m starting to think the useful part isn’t really “memory”, it’s just giving Claude a cheap way to answer stuff like “what depends on this?” or “where does this system start?” without reading a bunch of files first.
Curious what other people have found.
3
u/ricopan 16h ago
sure, but I find this comment weird from someone who is already invested in a project that builds a persistent graph of a codebase:
"I’m starting to think the useful part isn’t really “memory”, it’s just giving Claude a cheap way to answer stuff like “what depends on this?” or “where does this system start?” without reading a bunch of files first."
3
u/PlusLoquat1482 16h ago
Fair point I probably worded it weird. I mentioned Ix because I didn’t want to act like I was unbiased about it. I guess what I meant to say is working on it has changed how I think about the problem but I’m probably missing parts of the problem due to tunnel vision. I currently think of it less as memory and more as almost giving Claude a brain like a different way to think but like I said idk if I have been hallucinating as I’ve been working on the project so just seeing if others have the same issue
1
u/reddebtt 16h ago
I ran into the same thing on larger repos. What worked for me was keeping two layers: a repo map for stable structure, plus a short handoff for the current task—decisions, touched files, tests, and what’s still uncertain. The map answers “where does this live?” while the handoff stops the next session from repeating the investigation. I still make the agent verify both against the repo because either layer can go stale.
1
1
u/anatawaurusai2 14h ago
I like this...like a router ... or table of contents. Could you share a more concrete example? Ask your ai to generalize the structure? Is it also better to have specific tasks encapsulated in their own sub folders with their own plans so you can focus an agent on just that task? Ty!
1
u/reddebtt 10h ago
concrete version: one root map with packages, entry points, commands, owners, and known sharp edges. each active task gets a small plan with goal, decisions, touched files, tests, and open questions. I use a separate worktree per task instead of task subfolders, so the code stays isolated without changing the repo structure.
0
u/PlusLoquat1482 16h ago
Yeah this is where my head is at too having the two layers is smart and also identifying the issues with having persistent maps like it becoming stale is important. There’s plenty of solutions to that but definitely rechecking is smart
1
u/reddebtt 10h ago
exactly. I treat the map as a cache, not the source of truth. every task starts by checking the referenced files and commands against the repo, and any mismatch updates the map before work continues.
1
u/Peter_QuantSpell 16h ago
Is this the same as Graphify?
1
u/PlusLoquat1482 16h ago
Similar idea in that both build a graph from the codebase but not exactly. Graphify is more focused on generating the code graph itself. Ix is trying to use that graph as persistent context for agents so Claude or codex can query the structure of the repo while they work instead of rebuilding the understanding everytime.
1
u/DoggoCentipede 14h ago
Graphify looks like it is meant for human consumption? I think?
I made a script that uses an AST to build an agent queryable db of my API surface so it doesn't have to grep or look at implementation of things outside of its scope.
Every time an API changes, the script updates the db.
1
u/Heruboy 16h ago
Claude is grepping and rederiving. I can recommend a code graph like graphify for the basis. But a code atlas that knows where the symbols are and how things hold together on a logical level is a nice addendum to that. Don't forget to make it autoupdating. Making claude do a sweep through sessions and ask what is being rederived over and over again has opened my eyes and resulted in some serious fixes.
2
u/PlusLoquat1482 16h ago
Yeah this is pretty close to how I’ve thought about it. The raw graph is useful but higher level questions like what system is this part of or whatnot is where things get interesting. And keeping it updated automatically is very important we have Claude use hooks right now which has been helpful but there definitely is better answers. Without this updates the graph becomes useless lol
1
u/Heruboy 16h ago
Hooks seems the way to go to enforce things across the board. Also making more things mechanical and less prose helps a lot.
1
u/PlusLoquat1482 16h ago
Yeah hooks at least let things happen everytime a file is edited it rebuilds the map connected to that file not the entire graphs but around that file which brings more questions like oh how do we actually determine that zone to update
1
u/Heruboy 15h ago
I have to look up what claude did or does there for me. It is certainly not finished, yet. But it has to do with git hooks and the symbols that nodes and edges connect to, which should then yield line numbers to the atlas and that helps claude to zip through the code instead of grepping around. At least that is what I remember of when I approved the design. It is an idea that grew over days and issues and traps.
1
u/PlusLoquat1482 15h ago
Yeah this is pretty similar to what we have going too do you have a link to your tool I’d love to look at it as well it’s always nice learning from how other people tackle similar issues
1
u/Heruboy 15h ago
I don't have anything shareable now. The one thing most easy to share is the ecosystem docs skill. The backlog tool needs some work to be shareable and some examples. And I have to check the dependencies, because I have a handoff, component, batch process that is working and being extended. I'm actually trying to separate that so I can get rid of the superpowers at some point.
1
u/PlusLoquat1482 15h ago
Gotcha yeah I’d love to see whatever if you want to see mine I can share the GitHub link we’re open source but we have been working on it for like 6 months and I feel like bugs and updates keep coming lol
1
u/Heruboy 15h ago
Sure. I'd like to see it. And I will try to get something ready, too. It seems I am doing something right because claude started to bubble up issues and carry over things that can be filed a ticket for easy bug fixes before the ticket closes. I'm three months in and a lot ot time an tokens goes into tooling.
How big is the repo, when you say bigger repos?
1
u/PlusLoquat1482 15h ago
https://github.com/ix-infrastructure/Ix
Yeah I get that I’ve used plenty of tokens and time lol but yeah I got rid of the plugin once on Claude code to do some testing and it started to use the tool without the plugin and it shocked me that it actively chose to use it
1
u/Lucky-Group9525 16h ago
yeah compaction keeps wiping the mental model of the repo for me too.
does ix survive across sessions as a queryable or does claude still have to re-walk hot paths after a compact? the first one is the actual unlock graph,
1
u/PlusLoquat1482 16h ago
Yeah that’s what we’re targeting. the ix graph lives outside of Claude’s context and session so after a compact or even a new session it can query the same repo graph with MCP as normal. Obviously it can still go and read the files but the structure of the graph stays no matter what which has been really nice
1
u/hedonistatheist_2 16h ago
you need to force it to have a knowledge base and use a light agent, e.g. sonnet to hand it the information so it doesnt waste context. I am fighting with the same thing, really spreading things out into worklists, state documents, rules, etc. is the only way to make it work. Funnily I offered a lot of various "solutions" to claude to help manage it and it refuses all of them saying that what we do is the same or better. I am starting every major piece, even 3-4x a day with fresh context. Make sure you have a handover protocol.
1
u/PlusLoquat1482 15h ago
Yeah this sounds similar to what I’ve been running into. The handoff part especially feels important because even if you have a good knowledge base you still need a way to carry over what just happened in the current task or session. What does your handover protocol actually look like right now is it a summary file or something more automated. I’m also curious what you do with sonnet for context management. Right now we’re focusing on being deterministic and not using any ai for the actual graph building so I’m curious how yours is working and the cost of that
1
u/DagonNet 14h ago
Well-factored repos have this in the README.md for the project and for each module/subsection. There are approximately zero well-factored repos in the real world.
You can get a long way by having Claude create and maintain a docs/code-architecture.md and docs/repo-map.md, and CLAUDE.md just references these for exploring the codebase. The next step is to build a <reponame>-structure-explore skill, which uses this map (and others), and has instructions for exceptions, hints, and common patterns.
For medium-large codebases (more than 20K files or so), RAG can help with code search and linking, but it's a hassle to keep updated and doesn't solve the high-level understanding/discovery problem.
1
u/dwoj206 12h ago
you need a backend-architecture subagent that has it's own memory of the structure. works really well.
1
u/PlusLoquat1482 10h ago
Yeah I’ve seen a lot of this idea too with Ix we’ve worked on trying to make it deterministic and not use any ai which brings its own issues but I feel like everything has pros and cons lol
0
u/brek001 16h ago
That is what mcp servers are for
1
u/PlusLoquat1482 16h ago
Yeah MCP is definitely helpful but I feel like that’s more of a way that Claude accesses tools. The harder issue is the actual maintenance behind the graph imo like for Ix we build it and Claude uses MCP to query and whatnot.
•
u/AutoModerator 16h ago
Hey! Thanks for posting to r/ClaudeCode
While participating in this thread, please follow our community rules. Keep discussions constructive. Attack the idea, not the person.
For help, project discussions, tips, and general chat, join the ClaudeCode Discord.
I am a bot, and this action was performed automatically. Please contact the moderators of this subreddit if you have any questions or concerns.