Code Tour Generation

Problem

New developers joining a project face a steep learning curve. Documentation describes what the system does but rarely provides a guided path through how the code implements it. Reading files in alphabetical order or random discovery leads to fragmented understanding. Developers need a curated path through the codebase that builds understanding progressively.

When to Use

• A new developer is joining the team and needs to understand the architecture
• A complex feature spans 5+ files and benefits from a guided walkthrough
• A code review involves changes across multiple modules that reviewers need context for
• The project has a Clean Architecture or CQRS structure that newcomers find disorienting
• You want to document how a request flows from endpoint to database

When NOT to use:

• The codebase has fewer than 10 files — a README is sufficient
• You need API documentation — use the technical-writer agent instead
• The tour would be a single file — just add inline comments

Instruction

Generate a VSCode CodeTour file (.tours/{tour-name}.tour) that guides the reader through the codebase with progressive disclosure.

Tour Structure

Every tour follows the Concentric Circles pattern — start at the outermost layer (entry point, configuration) and spiral inward toward the core domain logic:

1. Entry point (Program.cs, endpoint, hub)
2. Configuration (DI registration, options)
3. Application layer (handler, pipeline)
4. Domain layer (entity, value object, domain service)
5. Infrastructure layer (repository, external service)
6. Cross-cutting (middleware, filters, interceptors)

Step Types

Step Content Guidelines

• Title: Short, descriptive — what this step teaches (not what the code does)
• Description: 2-4 sentences explaining the architectural significance
• Progressive: Each step builds on the previous one — never reference concepts not yet introduced
• Actionable: End each step with what to look for or understand before moving on

Output Format

Generate a JSON file following the CodeTour schema:

json
1{
2  "$schema": "https://aka.ms/codetour-schema",
3  "title": "{Tour Title}",
4  "description": "{One-sentence purpose of this tour}",
5  "steps": [
6    {
7      "title": "Step 1: Entry Point",
8      "description": "This is where requests enter the system...",
9      "file": "src/WebApi/Program.cs",
10      "line": 42
11    },
12    {
13      "title": "Step 2: DI Registration",
14      "description": "All services are registered here...",
15      "directory": "src/WebApi/Extensions/"
16    }
17  ]
18}

Tour Categories

Generate tours for these standard scenarios:

Quality Gates

• Every tour must have ≥ 5 steps and ≤ 25 steps
• Every step must reference a real file/directory that exists in the project
• No two consecutive steps should be in the same file (vary the perspective)
• The first step must orient the reader (where are we, what will we learn)
• The last step must summarize what was learned and suggest next exploration

Output Schema

1. The .tour JSON file content
2. Suggested file path: .tours/{category}-{subject}.tour
3. A summary of what the tour covers and its target audience

See Also

• scaffold-clean-arch — Clean Architecture project structure (tour often follows this layout)
• gen-copilot-instructions — Documentation generation for AI context files