How to Understand a Codebase Using AI
To understand a codebase using AI, point the tool at the repository and ask for a map before you ask for a change. In Claude Code, start in the project, request an overview, then trace one real path through the files. If the repo is public, turn that GitHub repo into a course. Ailurn builds the lessons from the repo's real files, not a generic syllabus.
Start from the files
Claude Code reads the project as it goes. The quickstart says you do not have to add context by hand. From the project root, run claude and ask:
- what does this project do?
- what technologies does this project use?
- where is the main entry point?
- explain the folder structure
The common-workflows guide uses the same opening for someone who just joined a project. Ask give me an overview of this codebase, then explain the main architecture patterns used here, what are the key data models?, and how is authentication handled?
Anthropic's tips on that page are short. Start with broad questions, then narrow to one area. Ask about the coding conventions in this project. Ask for a glossary of the terms the code uses.
Search, file reads, and shell commands are built-in tools. The architecture page says a question about your codebase might only need the context-gathering phase. Stay there until you can name the parts yourself.
Trace one path
An overview is a map. The next prompt should follow one behavior from the edge of the system to the data it touches.
The docs' recipe for finding code is specific. Ask Claude to find the files that handle user authentication, then how those files work together, then to trace the login process from front-end to database. Swap in the feature you actually need. Use the project's names for routes, services, and tables.
You can also name a file directly. Explain the logic in @src/utils/auth.js includes that file. A directory reference, such as @src/components/, shows the listing. The docs say a directory reference shows file names, and the contents stay out until a file is read.
If your language has a code intelligence plugin, install it. The workflows page says that gives Claude go-to-definition and find-references, which is tighter than text search alone.
Plan mode is the right setting for this pass. Start with claude --permission-mode plan, or press Shift+Tab until the status bar shows plan mode. Claude reads files and proposes a plan. It makes no edits until you approve. The best-practices guide calls the order explore, then plan, then code, and the explore step is a prompt like: read the auth directory and explain how sessions and login work.
On a large tree, those file reads fill the context window. Delegate the survey with use a subagent to investigate how our auth system handles token refresh. The subagent reads in its own context and reports a summary back.
Check the answer against the repo
When you run claude in a directory, it can see the project files, the current branch, uncommitted changes, and recent commit history. Ask which file a behavior lives in, then open that file. Ask show me the last 5 commits if you want the recent shape of the work. Keep going until the path names functions and files you can find yourself.
/init writes a starter CLAUDE.md from the current project. Claude Code reads that file at the start of every session, so it is the place for build commands, test commands, and conventions. It is loaded every time, which is why the best-practices page says to keep it to rules that apply broadly. Run /context to see what is already using the window.
Sessions are saved on your machine. claude --continue reopens the most recent one in this directory. claude --resume lets you pick. The map does not have to be rebuilt on the next sitting.
When you want a course from the same repo
A chat overview lives in the transcript. A course is a sequence you can retake.
Ailurn turns a prompt, a PDF, a docs URL, or a public GitHub repo into a structured course you take in the same workspace, with quizzes and flashcards from that material. For a codebase, paste the public repository URL. The course is built from the repo's real files, not a generic syllabus.
Free includes planning and one lesson from a prompt. File attachments start on a paid plan, so a private tree you cannot publish stays on your machine with Claude Code. Ailurn does not issue accredited certificates, and it does not watch a YouTube video or import a YouTube link.
A docs URL or a written goal goes in the AI course builder. The repository path is GitHub to course.
A sequence you can repeat
- Open the project and start Claude Code in that directory.
- Ask for the overview, the stack, the entry point, and the folder structure.
- Pick one user-visible behavior and trace it from the outside in.
- Stay in plan mode until you can name the files.
- If the repository is public and you want drills, generate the course from those files and use the quizzes to check the path.
Understanding a codebase with AI is a series of questions against the files that are there. Claude Code can search and read that tree. The course is the same tree, sequenced, when you want to review it later.