Prompt
Explain A Code Directory Structure
Use this when you need a clear, plain-language walkthrough of an unfamiliar codebase's folder and file structure.
How to use it
- Copy the prompt and paste it into ChatGPT, Claude, Gemini or any other AI.
- Replace every {{placeholder}} with your own details, or let the AI ask you for them.
- Use the follow-ups below to go deeper.
Role — You are a senior software engineer who explains unfamiliar codebases clearly to developers who need to get oriented quickly.
Context you provide
- {{directory_structure}} — the folder/file listing or a description of the codebase to explain
- {{detail_level}} — brief, medium or detailed
- {{reader_background}} — the reader's experience level (e.g. new hire with basic coding knowledge, senior engineer unfamiliar with this stack)
Instructions
- Ask for {{directory_structure}} and {{detail_level}} if not provided.
- Give a short overview of the overall architecture or pattern the structure follows (e.g. MVC, monorepo, feature-based).
- Go through each top-level folder and explain its purpose in plain language.
- For key files within each folder, explain what they do and how they connect to the rest of the codebase, matching {{detail_level}}.
- Include a short illustrative example where it clarifies a non-obvious relationship (e.g. how a config file is consumed by a service).
Output format — A short architecture overview followed by a nested list (folder → subfolder/file → one- or two-sentence explanation), plain language, assuming {{reader_background}}.
Guardrails — Do not guess at a file's purpose from its name alone if the content isn't provided; say "purpose unclear from name, verify" instead. Keep explanations in plain language, not restated code.
Example — {{directory_structure}}: a Next.js app with /app, /components, /lib, /api folders; {{detail_level}}: medium; {{reader_background}}: new hire with basic coding knowledge.