How to get AI to
understand my code.

What you’ll be able to do

Most people paste a function into ChatGPT, get an answer, and call it a day. That works fine for a one-off question. It falls apart the moment you want the assistant to actually know your codebase, the way a decent new hire would after a few weeks. Structure, conventions, the weird bits that look wrong but aren’t. None of that lives in a pasted snippet.

By the end of this you’ll have an assistant that can look at your repository and explain it back to you properly: what the entry points are, how data moves through it, and which of your habits are deliberate rather than accidental. You’ll have a file the assistant reads automatically that captures the rules nobody wrote down. And you’ll have a few honest ways to check whether any of this actually worked, rather than just assuming it did because the output sounded confident.

Before you start

The first thing to get right is scale. Give the assistant the whole repository, not pasted snippets. Claude Code runs inside the folder and reads what it needs as it goes. Cursor indexes the workspace. GitHub Copilot’s chat can use the open workspace. Codex works inside the repo too. Every one of these tools is built to look around, not to be spoon-fed fragments.

This matters because the value isn’t really in the code the assistant reads first. It’s in the corrections you make afterwards. Ask for a map of the structure, and it will get some of it wrong, or miss the thing that only makes sense because of a decision made eighteen months ago. Fixing that map is where the actual understanding gets built. Skip the map, and you skip the bit that would have caught the misunderstanding early.

On privacy: keep secrets out of what you hand over. .env files, API keys, customer data, none of it needs to go anywhere near the assistant for it to understand your code. Claude Code has permission settings and ignore rules for this. Cursor has .cursorignore. Use them. The assistant doesn’t need your production credentials to explain how your router works.

Get set up

Start by writing down the unwritten rules, once, in the file the tool actually reads at start-up. Claude Code looks for CLAUDE.md. Other setups use AGENTS.md, .cursor/rules, or .github/copilot-instructions.md for Copilot. Pick whichever your tool supports and put it at the root of the repo.

What goes in there isn’t code documentation, it’s the stuff that never made it into a comment. Things like: stage files by name, never git add -A, because several sessions share this checkout. Or: this deploy tool needs IPv4 forced or authentication fails, for reasons nobody bothered to write down at the time. Or: these two directories are the same files, not a copy, so don’t go “fixing” one to match the other. None of that is visible in the code itself. Every single one of those rules cost someone hours before they got written down. Yours will be different, but you’ve got a list like this in your head right now if you think about it for thirty seconds.

Alongside that, put the why next to the code, not in your head. A short comment where a choice looks wrong but is deliberate. A docs/decisions folder with one file per decision, the ADR habit, if you’ve not come across it. Tests with plain-English names that state the behaviour rather than just asserting numbers. Assistants read all three of these and, crucially, stop trying to “fix” things that were correct all along.

If your codebase is big, don’t try to feed it the whole thing at once. Point the assistant at one folder and ask for that module explained as if to a new hire, then have it list what it couldn’t see. That gap list is often more useful than the explanation.

Try it yourself

Here are three prompts. Each one does something different, so run them in order rather than picking your favourite.

First, the map. Run this before anything else, in the root of the repo:

Give me a map of this codebase: the overall structure, the main entry points, 
how data flows between the major parts, and anywhere you're unsure or guessing. 
Don't suggest changes yet, just describe what's here.

Read what comes back properly. Correct anything that’s wrong or missing context. That correction step is not optional, it’s the actual work.

Second, ask it to reason about a specific piece before touching anything:

Explain [module] to a new hire, then list what you are unsure about.

Swap in a real module name. What you’re looking for here is honesty about the gaps, not confidence. If it claims to understand everything, be suspicious.

Third, and this is the one that tells you the most:

Before changing anything, tell me the conventions you think this codebase follows.

This forces it to state its assumptions out loud, before it does anything that could go wrong because of a wrong assumption. Compare its list against what you actually do. The gaps are informative either way, sometimes they show you conventions you follow without realising you’d formalised them.

Check the result

Confidence isn’t the same as accuracy, so don’t take a fluent explanation as proof of understanding. Test it properly.

Ask it to explain a module back to you, and grade the explanation yourself against what you know to be true. Then ask it to predict what a specific function returns for a specific input, and actually run the function to check. This is the single most useful test, because it’s falsifiable. Either it’s right or it isn’t.

Try this one too:

What are the three conventions this codebase follows that you would not 
have guessed just from reading standard code style?

If its answers roughly match the unwritten rules you’ve already got in your head, or in your CLAUDE.md, that’s a good sign. If they’re generic (“use meaningful variable names”) rather than specific to your repo, it hasn’t really understood anything yet, it’s just being polite.

Docs drift too, and it’s worth checking that separately. Once a month, ask:

Which statements in README.md does the code contradict?

Docs go stale faster than anyone notices, and this catches it without you having to reread the whole README yourself every time. A twice-weekly version of this is possible if your codebase changes fast enough to justify it, but monthly is a sensible default for most people.

If it doesn’t work

Sometimes the map comes back wrong, or vague, or confidently wrong, which is worse. A few things to try before giving up on the approach.

If the explanation is too generic, it probably hasn’t actually read enough of the repo, or your instructions file is too thin. Add more specifics to CLAUDE.md or whichever file you’re using, especially the weird stuff. The boring conventions are usually inferred fine. It’s the deliberate oddities that need spelling out.

If it keeps trying to “fix” something that’s correct on purpose, that’s a sign the why isn’t written down anywhere it can see. Add a comment, or an ADR entry, right there in the code.

On privacy, worth repeating plainly: don’t hand an assistant your .env files, real API keys, customer data, or anything with personal information in it, even if it’s sitting in the repo. Use the ignore rules, .cursorignore for Cursor, Claude Code’s permission settings, whatever your tool offers, and actually check they’re working rather than assuming. If you’re not sure whether something counts as sensitive, treat it as sensitive. The assistant doesn’t need it to explain how your code works, so there’s no trade-off to make here, just exclude it.

And if none of this seems to be sticking, check that the assistant is actually reading the instructions file at all. Different tools look in different places, and a file in the wrong location is silently ignored rather than flagged as missing, which is an easy mistake to make once and not notice for weeks.

Keep exploring

If this went well and you want the assistant to hold onto what it’s learned between sessions rather than relearning it every time, have a look at “How to get AI to remember context”. If you’re wondering how to keep all this current as the tools themselves change, “How to get AI to update itself” covers that. And once the assistant genuinely understands the codebase, the natural next step is “How to get AI to write code” that actually fits it.

Sources and review notes

https://code.claude.com/docs/en/memory https://code.claude.com/docs/en/settings https://cursor.com/docs/rules https://cursor.com/docs/reference/ignore-file https://docs.github.com/en/copilot/how-tos/copilot-on-github/customize-copilot/add-custom-instructions/add-repository-instructions https://agents.md/

Review date: 2026-09-16