Code Tour

.tour

.tours/

• what they are looking at
• why it matters
• what path they should follow next

.tour

When to Use

• the user asks for a code tour, onboarding tour, architecture walkthrough, or PR tour
• the user says "explain how X works" and wants a reusable guided artifact
• the user wants a ramp-up path for a new engineer or reviewer
• the task is better served by a guided sequence than a flat summary

• onboarding a new maintainer
• architecture tour for one service or package
• PR-review walk-through anchored to changed files
• RCA tour showing the failure path
• security review tour of trust boundaries and key checks

When NOT to Use

.tour

documentation-lookup

codebase-onboarding

Workflow

1. Discover

• README and package/app entry points
• folder structure
• relevant config files
• the changed files if the tour is PR-focused

2. Infer the reader

new-joiner

vibecoder

architect

pr-reviewer

rca-investigator

security-reviewer

feature-explainer

bug-fixer

3. Read and verify anchors

• confirm the file exists
• confirm the line numbers are in range
• if using a selection, verify the exact block
• if the file is volatile, prefer a pattern-based anchor

4. Write the

.tour

.tours/<persona>-<focus>.tour

5. Validate

• every referenced path exists
• every line or selection is valid
• the first step is anchored to a real file or directory
• the tour tells a coherent story rather than listing files

Step Types

Content

{ "title": "Next Steps", "description": "You can now trace the request path end to end." }

Directory

{ "directory": "src/services", "title": "Service Layer", "description": "The core orchestration logic lives here." }

File + line

{ "file": "src/auth/middleware.ts", "line": 42, "title": "Auth Gate", "description": "Every protected request passes here first." }

Selection

{
  "file": "src/core/pipeline.ts",
  "selection": {
    "start": { "line": 15, "character": 0 },
    "end": { "line": 34, "character": 0 }
  },
  "title": "Request Pipeline",
  "description": "This block wires validation, auth, and downstream execution."
}

Pattern

{ "file": "src/app.ts", "pattern": "export default class App", "title": "Application Entry" }

URI

{ "uri": "https://github.com/org/repo/pull/456", "title": "The PR" }

Writing Rule: SMIG

• Situation: what the reader is looking at
• Mechanism: how it works
• Implication: why it matters for this persona
• Gotcha: what a smart reader might miss

Narrative Shape

1. orientation
2. module map
3. core execution path
4. edge case or gotcha
5. closing / next move

Example

{
  "$schema": "https://aka.ms/codetour-schema",
  "title": "API Service Tour",
  "description": "Walkthrough of the request path for the payments service.",
  "ref": "main",
  "steps": [
    {
      "directory": "src",
      "title": "Source Root",
      "description": "All runtime code for the service starts here."
    },
    {
      "file": "src/server.ts",
      "line": 12,
      "title": "Entry Point",
      "description": "The server boots here and wires middleware before any route is reached."
    },
    {
      "file": "src/routes/payments.ts",
      "line": 8,
      "title": "Payment Routes",
      "description": "Every payments request enters through this router before hitting service logic."
    },
    {
      "title": "Next Steps",
      "description": "You can now follow any payment request end to end with the main anchors in place."
    }
  ]
}

Anti-Patterns

Best Practices

• keep step count proportional to repo size and persona depth
• use directory steps for orientation, file steps for substance
• for PR tours, cover changed files first
• for monorepos, scope to the relevant packages instead of touring everything
• close with what the reader can now do, not a recap

Related Skills

• codebase-onboarding

• coding-standards

• council

• official upstream format:

  microsoft/codetour