HomeCasa Prompts

Understand an unfamiliar codebase: architecture map and onboarding guide

Turn a repo tree and key files into a clear map: architecture, how a request flows, glossary, risky areas and exactly where to start for your specific task. Designed for ChatGPT, Claude, Gemini and Microsoft Copilot. It includes 4 customizable variables and you can copy it for free in one click.

Intermediate · Text · Pending editorial review

Designed for:

Prompt

Act as a senior engineer helping a newcomer understand a repository they have never seen.

Context:
- Project and stack: {{project}}
- Folder tree and key files (README, config, entry point, routes, models): {{files}}
- My specific task in this code: {{task}}
- My experience with this stack: {{experience}}

Deliverables:
1. A 5-line summary: what the system does, for whom and its main pieces.
2. An architecture map: layers or modules, the responsibility of each important folder and how they communicate. Include a Mermaid diagram.
3. A walkthrough of a typical request or flow from start to finish, citing real files and functions that appear in what I gave you.
4. A glossary of domain and project terms found in the code.
5. For my task: the files I will probably need to touch, the order to read them in and which tests to run.
6. Risky areas: tight coupling, framework magic, per-environment configuration, hidden side effects.
7. Ten concrete questions to ask the team.

Constraints:
- Base everything on what I provided. If you infer something without seeing it, mark it [VERIFY]; if a key file is missing, tell me which one and why you need it.
- Do not invent file names, functions or commands.
- Match the level of detail to my experience: {{experience}}.
- If the information is not enough for the map, ask me for the missing files first.

Format: numbered sections, a Mermaid diagram and short lists.

How to use it

Generate the tree with a command like tree -L 3 -I node_modules or git ls-files, and also paste the README, the main config file and the entry point. If the context is large, share the repo in parts and ask for the map at the end.

Usage example

Project: NestJS booking API with PostgreSQL · Task: add partial refunds to the payments module · Experience: I know Node.js but not NestJS.

Sample output

Assuming the folder tree you pasted follows the standard Symfony 6 layout…

1. Summary

A B2C online store: catalog, cart, checkout and orders. Controllers in src/Controller, logic in src/Service, persistence through Doctrine on MySQL, and Twig views.

2. Architecture map

flowchart LR
  R[config/routes] --> C[src/Controller]
  C --> S[src/Service]
  S --> E[src/Entity + Repository]
  E --> DB[(MySQL)]
  C --> T[templates/ Twig]

5. For your task: weight-based shipping

Suggested reading order:

  1. src/Entity/ShippingMethod.php [VERIFY] — how existing methods are modeled.
  2. The service that computes shipping cost, probably under src/Service/Shipping/ [VERIFY].
  3. src/Entity/Product.php — is there already a weight field? If not, you will need a Doctrine migration.
  4. The checkout template in templates/checkout/ [VERIFY].

Tests to run: at least php bin/phpunit tests/Service.

6. Risky areas

  • Doctrine or kernel event listeners that change the order without showing up in the controller.
  • Per-environment config in config/packages/{dev,prod}.

7. Questions for the team

  1. Is weight stored in grams or kilograms?
  2. Do weight-based rates change by destination country?…

Key facts

Category
Programming & development · Documentation
Output type
Text
Level
Intermediate
Designed for
ChatGPT, Claude, Gemini and Microsoft Copilot
Verified in
Pending editorial verification
Variables
Project and stack, Tree and key files, My task and Experience with the stack
Language
English
Price
Free, no sign-up
Updated
Nov 7, 2026

Frequently asked questions

How much code do I need to paste?

Start with the folder tree, README, config and entry point. With that the model can ask for the specific files it needs instead of processing the whole repository.

Can I trust the diagram?

It is a starting point. Check anything marked [VERIFY] against the code or with the team before making design decisions.

What is this prompt for?

Turn a repo tree and key files into a clear map: architecture, how a request flows, glossary, risky areas and exactly where to start for your specific task.

Which AI tools does it work with?

It is designed for ChatGPT, Claude, Gemini and Microsoft Copilot. We have not verified it in these tools yet, so results may vary between them.

How do I customize the prompt?

Click “Customize” and fill in the variables (Project and stack, Tree and key files, My task and Experience with the stack). The text updates instantly and you can then copy it in one click. Values are stored only in your browser.

Do I need experience to use it?

It is intermediate: it helps to know the topic so you can provide good context and review the result critically.

Is this prompt free?

Yes. Every HomeCasa Prompts prompt is free, with no sign-up or subscription. You can also use them in professional projects.

Can I trust the AI output?

Treat it as a high-quality draft: always check data, figures and important claims before publishing or making decisions.

Related prompts