Project Structure Analysis
📚 Series Navigation: The previous article 12 Project Initialization discussed how to create a new project from 0 to 1. This article tackles the more common pain point: taking over someone else's existing codebase. How do you get Claude Code to help you rapidly understand the architecture? Next article 14 Interface and Shortcuts.
"Company gave me a 5-year-old legacy project today, opening it there are 300+ files, no docs, the original author already resigned. I stared at the screen for two hours, utterly confused."
This scenario is too common. In the past, you could only search for main globally, then follow the function calls one by one, jumping through definitions, drawing architectural diagrams on paper until your head spun.
Now, with Claude Code, you have a "Super Code Reader". But remember the iron rule from previous articles: Don't just throw a vague "explain this project" at it, otherwise it will wildly read dozens of files and consume a massive amount of tokens, and the summary it gives will be as generic as water.
After reading this article, you will get:
- A progressive 3-step prompt formula for analyzing unfamiliar projects (Overview -> Entry -> Link)
- How to use the "Plan Mode" to limit its token consumption when reading code
- How to get it to output a clear Mermaid architecture diagram
01 Why Can't You Just Ask "Explain This Project"?
If you run claude in a large project and directly ask:
"Help me understand what this project does."
What Claude actually does in the background: It triggers tools like Glob (search files), Grep (search content), View (read files). Because your instruction is too vague, it might randomly read package.json, read some utils.ts, read a few components, and finally deduce: "This is a frontend project doing data management." Result: You spent a few cents on tokens, but got a piece of useless nonsense.
The core logic of codebase analysis is: Progressive zooming. From macroscopic directory structure -> to finding the execution entry point -> to tracking a specific business flow.
02 The Progressive 3-Step Analysis Method
Step 1: Macroscopic Overview (Only look at directories, don't read code)
The first step is to establish a mental model of the modules. We explicitly forbid it from reading specific code, only let it look at the file tree.
Prompt Example:
I am taking over this project for the first time. Please only use the ls or directory listing tool to view the top-level and second-level directory structure.
Do not read the contents of any specific code files.
Based on the directory names and configuration files (like package.json or pom.xml), briefly summarize what the responsibilities of each main directory are.Expected Outcome: It will quickly output something like:
src/api: Likely handles network requests.src/components: Public UI components.src/views: Page-level components. It didn't read the code, so it's extremely fast and consumes very few tokens.
Step 2: Find the Execution Entry Point
Once you know the directories, you need to know how the program runs.
Prompt Example:
Based on the directory structure just now, find the startup entry of this project (e.g., main.ts, index.js, or App.tsx).
Read this entry file and the core configuration it imports.
Tell me:
1. How does the project start?
2. What core global dependencies are injected (like Router, Store, Theme)?Expected Outcome: It will precisely locate src/main.ts, read it, and tell you: "The project mounts React to the root node here, and injects Redux store and React Router." Now you have the "root" of the tree.
Step 3: Trace a Specific Business Link
Don't let it analyze the whole project, let it analyze a specific feature.
Prompt Example:
I want to understand the 'User Login' feature.
Starting from the routing configuration, find the login page component, and trace down to the API request function it calls.
Please analyze this specific calling link and list the files involved.Expected Outcome: It will accurately string together Router -> Login.tsx -> authService.ts, explaining exactly how a login request is sent. This is directly applicable to fixing bugs.
03 Outputting an Architecture Diagram (Mermaid)
Text is sometimes not intuitive enough. You can leverage Markdown's Mermaid syntax to let Claude draw for you.
Prompt Example:
Based on your understanding of the user login flow above, please generate a Mermaid flowchart.
Show the interaction sequence from User clicking the button -> Component -> Service -> Backend API.Claude will output a code block wrapped in ```mermaid, which renders as a clear flowchart in VS Code (using a Markdown preview extension) or on the Web version.
04 Advanced Tip: Use Plan Mode (Shift+Tab)
When you need it to deeply analyze a complex problem (like "Find all places related to caching"), we strongly recommend using Plan Mode.
Why? In normal mode, it reads a file, thinks for a bit, reads another, sometimes getting sidetracked, and the token consumption is uncontrollable. In Plan Mode, it will first tell you: "I plan to search redis keywords first, then read cache.ts, then analyze user.ts." You can review this plan. If you find it plans to read a completely irrelevant test folder, you can directly reject it and say "Skip the test folder," preventing it from wasting tokens on useless work.
💡 One-sentence summary: Codebase analysis must be progressive—first directories, then entry points, then specific links; use Plan Mode to control its reading range.
05 Summary
Taking over a legacy project is no longer a nightmare. Claude Code is your senior colleague leading your onboarding:
- Don't ask vague questions: Vague questions waste tokens and yield generic answers.
- Progressive 3-Steps: Directory Overview -> Startup Entry -> Specific Feature Link.
- Visualize: Let it draw Mermaid diagrams to clarify the architecture.
- Control Cost: Use Plan Mode to review its reading path.
You should now be able to jump into any unfamiliar project, map out its skeleton within 10 minutes, and confidently find the location to modify code.
Next article 14 Interface and Shortcuts—After talking about practical strategies, let's sharpen our tools. The terminal interface of Claude Code hides many efficiency-boosting shortcuts (like calling up historical commands, multi-line input). Mastering them will double your typing speed.