Code Tour Mentor

An agent that creates and maintains VSCode CodeTour walkthrough files, designing guided step-by-step tours of codebases that help new engineers onboard faster by understanding code structure, patterns, and key architectural decisions.

When to Use This Agent

Choose Code Tour Mentor when:

• Creating onboarding walkthroughs for new team members
• Documenting complex code flows across multiple files
• Building guided tutorials for library or framework usage
• Creating code review tours that explain PR changes in context
• Maintaining living documentation that stays tied to actual code

Consider alternatives when:

• Writing standalone documentation not tied to code locations (use a docs generator)
• Creating API reference docs (use OpenAPI or TypeDoc tooling)
• Recording video walkthroughs of code (use screen recording tools)

Quick Start

Copy
# .claude/agents/code-tour-mentor.yml
name: Code Tour Mentor
model: claude-sonnet-4-20250514
tools:
  - Read
  - Write
  - Glob
  - Grep
prompt: |
  You are a CodeTour expert. Create .tour JSON files that guide
  developers through codebases step by step. Each step should
  reference specific files and line ranges, with clear explanations
  that build understanding progressively.

Example invocation:

Copy
claude --agent code-tour-mentor "Create an onboarding tour for
  our authentication system, covering the login flow from the
  React component through the API route to the database query"

Core Concepts

Tour File Structure

Copy
{
  "$schema": "https://aka.ms/codetour-schema",
  "title": "Authentication Flow",
  "description": "How user login works end-to-end",
  "isPrimary": true,
  "steps": [
    {
      "file": "src/components/LoginForm.tsx",
      "line": 42,
      "description": "## Login Form Submission\n\nThe login flow starts here when the user submits their credentials. The `handleSubmit` function prevents default form behavior and calls the auth API."
    },
    {
      "file": "src/api/auth.ts",
      "line": 15,
      "description": "## API Authentication\n\nCredentials arrive here. Note the rate limiting middleware applied at line 12 — this prevents brute force attacks."
    }
  ]
}

Step Types

Type	Use Case	JSON Key
File step	Point to specific code line	file + line
Directory step	Explain folder structure	directory
Content step	Standalone explanation	description only
Selection step	Highlight code range	file + selection
Command step	Run a command during tour	commands

Tour Organization Patterns

.tours/
├── 01-getting-started.tour       # Environment setup
├── 02-architecture-overview.tour # System structure
├── 03-auth-flow.tour            # Authentication deep dive
├── 04-data-pipeline.tour        # Data processing flow
├── 05-deployment.tour           # CI/CD and deployment
└── pr-reviews/
    └── feature-xyz.tour         # PR-specific walkthrough

Configuration

Parameter	Description	Default
tour_directory	Where to store tour files	.tours/
git_ref	Pin steps to specific commit	HEAD
step_format	Markdown style for descriptions	GitHub-flavored
include_commands	Add executable command steps	false
max_steps	Maximum steps per tour	25
numbering_prefix	Tour file naming convention	NN-
auto_update	Track file changes for step updates	false

Best Practices

1. Tell a story, don't list files. A tour should follow a logical flow that mirrors how the system processes a request, handles an event, or builds a feature. Each step should build on the previous one. "First the request arrives here, then it's validated here, then processed here" teaches far more than a random collection of interesting code locations.

2. Start each step with context before details. The step description should first explain why the developer is looking at this code, then explain what the code does. Lead with "This middleware runs before every authenticated route" rather than diving straight into implementation details about token parsing.

3. Keep tours focused on one concept or flow. A tour covering authentication, authorization, session management, and password reset is four tours pretending to be one. Each tour should take 10-15 minutes to complete. If your tour has more than 20 steps, find a natural breaking point and split it.

4. Use line ranges rather than single lines for complex code. The selection field lets you highlight a range of lines. When explaining a function, highlight the entire function body rather than just the declaration line. This gives the developer visual context without requiring them to scroll or guess which code the step refers to.

5. Pin tours to git refs for stability. When a tour references line 42 of a file, any code change can shift that line. For stable documentation tours, pin to a specific commit using the ref field. For active development tours, accept that they need periodic updates and include update instructions.

Common Issues

Tour steps point to wrong lines after code changes. Line numbers shift when code is added or removed above the referenced line. Mitigate this by pinning tours to git refs for stable documentation, using selection ranges instead of single lines (ranges are more resilient to small changes), and running a tour validation script in CI that checks whether referenced lines still contain expected content.

Tours become stale and misleading. Treat tours like tests: if they break, fix or delete them. Add a CI check that validates tour files against the current codebase. Include a "last verified" date in tour descriptions. Assign tour ownership to the team that owns the code, and review tours during sprint retrospectives or documentation sprints.

New team members don't discover available tours. Add tour information to your README and onboarding checklist. Use the isPrimary flag on the most important tour so it auto-starts when opening the project. Create a table of contents tour that links to all other tours, explaining what each covers and when to take it. Include the CodeTour extension in your workspace recommendations.