Generate comprehensive architecture documentation (noob.md) for junior engineers who are new to a codebase. Use this skill whenever the user asks to document a codebase, create onboarding docs, write architecture guides, generate "noob docs", explain a project's structure for new team members, or mentions wanting documentation that helps someone unfamiliar with the code get up to speed. Also use when users say things like "document this for a junior", "create a getting started guide for the codebase", "explain the architecture", "write developer onboarding docs", or "I need docs so new engineers can contribute".
You are generating a comprehensive architecture document (noob.md) that will allow a junior engineer — who has never seen this codebase — to understand the system well enough to add significant features. The document must be self-contained: after reading it, the engineer should not need to ask "but how does X work?"
Before exploring, ask the user these questions to scope the work. Use AskUserQuestion with sensible defaults:
Scope: "What should the doc cover?"
Audience baseline: "What can we assume the reader already knows?"
Output location: "Where should I put the document?"
noob.md in the repo rootFeature implementation example: "The doc will include a walkthrough of implementing a feature end-to-end (no code — just which files, classes, and methods to touch and why). Do you have a specific feature you'd like to see walked through, or should I suggest one that exercises as many parts of the codebase as possible?"
If the user seems impatient or says "just go", skip the interview and use the defaults (AI-suggested feature for the implementation example).
Before launching deep exploration, quickly identify the project's shape. This takes ~30 seconds and informs everything else.
Run these in parallel:
From this, determine:
Run these in parallel while planning the exploration:
# Coupling analysis: which files change together
git log --stat --oneline -30
# Recent activity: what's being worked on
git log --all --oneline -20
# Build/test/run commands
# (read from package.json scripts, Makefile targets, or equivalent)
Also read:
Launch up to 5 Explore agents in parallel. Adapt the agent focus areas to the project — these are starting points, not rigid categories.
If the user specified a feature in Phase 1, bias each agent to also note how their subsystem would be involved in implementing that feature (e.g., "if adding feature X, this subsystem would need…"). This contextual awareness will feed directly into the Feature Implementation Guide section.
| Agent | Focus | What to find |
|---|---|---|
| 1. Entry & Boot | Main entry point, CLI wiring, startup sequence | How the process starts and what gets initialized in what order |
| 2. Transport / Input | How external inputs arrive (HTTP, CLI, message queues, file watchers) | Request/event lifecycle from outside world to internal processing |
| 3. Core Business Logic | Main processing pipeline, domain models, key algorithms | The "heart" of the system — what it actually does |
| 4. Extension Points | Plugin system, middleware, hooks, event bus, module registration | How the system is extended without modifying core |
| 5. Shared Infrastructure | Types, utils, config, logging, error handling, security | Cross-cutting concerns everything depends on |
Each agent prompt should ask for:
Important: Tell each agent to be very thorough and to read full files, not just scan headers.
If the project has an LSP available (check by trying a hover operation on a source file), use it to build a type map of the key abstractions:
workspaceSymbol — map all exported interfaces/types (this may return a lot; focus on the top-level module boundaries)hover on key type names found by exploration agents — get full type signaturesdocumentSymbol on critical files — list all symbolsgoToDefinition — trace type hierarchies for the 3-5 most important typesfindReferences — understand where key interfaces are implementedBased on agents' findings, read and understand these critical files (typically 10-20 files):
Read each file thoroughly. Take notes on patterns, conventions, and design decisions.
Generate the document using Mermaid.js for diagrams. Use PlantUML only if Mermaid cannot express a particular diagram (rare — Mermaid handles sequence, graph, class, state, ER, and flowcharts).
Adapt this structure to the project. Not every section applies to every project — skip sections that don't make sense, add sections that do.
# [Project Name] Architecture Guide for New Engineers
> **Audience**: [from interview — e.g., "You know TypeScript and Node.js..."]
> You do **not** know this codebase. This document will fix that.
**Version**: [version] · **Runtime**: [runtime] · **Language**: [language]
**Build**: [build tool] · **Package manager**: [pm] · **Tests**: [test framework]
---
## Table of Contents
[auto-generate from sections]
## 1. What is [Project]?
[1-paragraph elevator pitch. What does it do? Who uses it? Why does it exist?]
[ASCII or Mermaid diagram showing the 10,000-foot view]
## 2. High-Level Architecture
[Mermaid graph TB showing major components and data flow]
[Layered architecture diagram if applicable]
## 3. Repository Layout
[Annotated directory tree — every important directory explained]
[Star (★) the most important directories]
## 4. Boot/Startup Sequence
[Mermaid sequence diagram: process start → "system ready"]
[Table: step | file | what happens]
## 5. Core Concepts
[Mermaid concept map linking key abstractions]
[Table: concept | what it is | where it lives]
## 6. [Main Processing Flow] (end-to-end)
[This section title should reflect what the project does:
- For a web server: "Request Lifecycle"
- For a message gateway: "Message Lifecycle"
- For a compiler: "Compilation Pipeline"
- For a CLI tool: "Command Execution Flow"]
[Detailed Mermaid sequence diagram with ALL steps]
[Annotated code walkthrough of the key types in this flow]
## 7-N. [Subsystem Deep Dives]
[One section per major subsystem. Include as needed:
- Class/type diagrams (Mermaid classDiagram)
- State machines (Mermaid stateDiagram)
- Adapter/strategy patterns
- Annotated code snippets]
## N+1. Configuration System
[Master config type with annotations]
[How config is loaded, validated, and accessed]
## N+2. Extension/Plugin Architecture
[Registration flow (Mermaid sequence diagram)]
[SDK interface with annotations]
[Complete minimal extension example using REAL project types]
## N+3. Security Model (if applicable)
[Layered security diagram]
[Key concepts: auth, authz, sandboxing, input validation]
## N+4. Key Patterns and Conventions
[Dependency injection pattern]
[Naming conventions]
[File organization conventions]
[Testing patterns]
## N+5. Walkthrough: Adding a [Feature Type]
[Pick a feature type that exercises the main extension point]
[Step-by-step guide with REAL code using REAL project types]
[This should be a complete, working example]
## N+6. Feature Implementation Guide
[This section walks through implementing a real feature WITHOUT any code.
It shows the reader which files, classes, and methods to touch and why —
teaching them to navigate the codebase by tracing a feature end-to-end.]
### Choosing the feature
- **If the user provided a feature in the Phase 1 interview**, use that feature.
- **If the user asked the AI to suggest one**, choose a user-facing feature that
touches as many layers and subsystems as possible (e.g., API/transport, business
logic, data access, configuration, tests). Then explain:
- What the feature is and why it's valuable to end users
- **Why this feature was chosen as the example** — which layers/subsystems it
exercises and why that makes it an effective learning walkthrough
### Structure
**Opening**: A brief description of the feature and its user-facing value.
**Sequence diagram (if relevant)**: A Mermaid sequence diagram showing how the
feature's execution flows through the system's layers and components. This gives
the reader a bird's-eye view before diving into individual files.
**File-by-file narrative**: For each file that needs to be modified or created,
write a narrative subsection:
#### `path/to/file.ext` — modify | create
**Why this file is involved**: [1-2 sentences explaining this file's role in
the feature]
**What needs to happen**:
- `ClassName.methodName()` — [description of what should change and why,
without showing code]
- `AnotherClass` — [description of a new method or field to add and its
purpose]
[Order files in the sequence a developer would naturally work through them —