Español

Tour Files: Persona-Targeted Code Walkthroughs

A file tree is a map. A code tour is a GPS route through your code. Drop a new developer into an unfamiliar repo and a directory listing tells them what exists, not where to start. A .tour file fixes that: a checked-in JSON walkthrough whose steps are anchored to real files and lines, played back stop by stop inside the editor.

What a .tour file actually is

CodeTour is a free, open-source VS Code extension from Microsoft. A tour is one JSON file with a title and a steps array; each step points at a file (workspace-relative path) plus a line, and carries a markdown description — one note on why that spot matters. The extension discovers tours from a .tours, .vscode/tours, or .github/tours directory (sub-directories are fine), or from a single .tour file at the repo root.

// .tours/backend-request-path.tour
{
  "title": "1 - Backend: life of a request",
  "description": "For new backend devs — follow one request end to end.",
  "steps": [
    {
      "file": "src/api/router.py",
      "line": 42,
      "description": "Every request enters here. Note the auth middleware on line 42 — it runs before any handler."
    },
    {
      "file": "src/services/orders.py",
      "line": 118,
      "description": "Business logic lives in services, never in handlers. This is the pattern to copy."
    }
  ]
}

Playback is in-editor: each step opens the file, jumps to the line, and shows the note as a comment bubble. You don't hand-write the JSON either — run CodeTour: Record Tour, click the comment bar on the line you want, type the note, and steps append in order.

One tour per persona

The tip that makes tours scale: don't write one grand tour of everything. Write one route per audience.

CodeTour supports this directly: number the titles (1 - Backend, 2 - Frontend) and it links them with Next/Previous, mark one isPrimary so first-time openers get the default route, and use a when clause to show a tour only when its condition holds.

Keep the anchors honest

Line numbers drift as code changes — a tour that points at the wrong line is worse than no tour. CodeTour gives you three tools:

• Pin to a git ref. Each tour has an optional ref (branch, tag, or commit). Pinned to a tag or commit, the tour opens the code exactly as recorded and never desyncs; left un-pinned, it tracks the working tree and you edit steps as code moves.
• Pattern anchors. A step can use a regex pattern instead of a fixed line, so the anchor follows the code it describes.
• Verify in review. Treat .tours/ like tests: when a PR moves a file a tour references, updating the tour is part of the diff.

Power moves

• Content steps need no file at all — pure markdown title-plus-text stops for intro and summary screens inside a tour.
• Directory steps anchor to a folder instead of a line — useful for "everything under src/services/ follows this shape".
• Export with embedded content — an exported tour bundles the file contents it references, so it plays back without cloning the repo (or share it as a GitHub Gist via GistPad).
• Steps can run commands — a step's commands property triggers VS Code commands on navigation, so a tour can open a terminal or run the test suite at the right stop.
• Feed tours to your AI agent. A .tour file is plain JSON with file:line anchors and human rationale — exactly the "where to look and why" context coding agents lack in a fresh repo. Point the agent at .tours/ before a task the way you'd point a new hire.

Resources

• CodeTour — GitHub repository and full docs
• Recording tours
• Versioning tours with a git ref
• Tour file locations and format
• Exporting tours for playback without the repo
• CodeTour on the VS Code Marketplace