Back to Details

code-tour

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Code Tour Skill

Code Tour Skill

You are creating a CodeTour — a persona-targeted, step-by-step walkthrough of a codebase that links directly to files and line numbers. CodeTour files live in 
.tours/
and work with the VS Code CodeTour extension.
Two scripts are bundled in 
scripts/
:
  • scripts/validate_tour.py
     — run after writing any tour. Checks JSON validity, file/directory existence, line numbers within bounds, pattern matches, nextTour cross-references, and narrative arc. Run it: 
    python ~/.agents/skills/code-tour/scripts/validate_tour.py .tours/<name>.tour --repo-root .
  • scripts/generate_from_docs.py
     — when the user asks to generate from README/docs, run this first to extract a skeleton, then fill it in. Run it: 
    python ~/.agents/skills/code-tour/scripts/generate_from_docs.py --persona new-joiner --output .tours/skeleton.tour
Two reference files are bundled:
  • references/codetour-schema.json
     — the authoritative JSON schema. Read it to verify any field name or type. Every field you use must conform to it.
  • references/examples.md
     — 8 real-world CodeTour tours from production repos with annotated techniques. Read it when you want to see how a specific feature (
    commands
    , 
    selection
    , 
    view
    , 
    pattern
    , 
    isPrimary
    , multi-tour series) is used in practice.
你正在创建一个CodeTour——面向特定角色、分步式的代码仓库导览，可直接链接至文件和行号。CodeTour文件存储在
.tours/
目录下，可与VS Code CodeTour扩展配合使用。
scripts/
目录下包含两个脚本：
  • scripts/validate_tour.py
     —— 编写完任何导览后运行此脚本。检查JSON有效性、文件/目录是否存在、行号是否在范围内、模式匹配、nextTour交叉引用以及叙事逻辑。运行命令：
    python ~/.agents/skills/code-tour/scripts/validate_tour.py .tours/<name>.tour --repo-root .
  • scripts/generate_from_docs.py
     —— 当用户要求从README/文档生成导览时，先运行此脚本提取框架，再填充内容。运行命令：
    python ~/.agents/skills/code-tour/scripts/generate_from_docs.py --persona new-joiner --output .tours/skeleton.tour
还包含两个参考文件：
  • references/codetour-schema.json
     —— 权威JSON Schema。可查阅此文件验证任何字段名称或类型。你使用的每个字段都必须符合该Schema规范。
  • references/examples.md
     —— 来自生产仓库的8个真实CodeTour导览示例，并附带注释说明。当你想了解特定功能（
    commands
    、
    selection
    、
    view
    、
    pattern
    、
    isPrimary
    、多导览系列）的实际用法时，可查阅此文件。

Real-world 
.tour
files on GitHub

GitHub上的真实
.tour
文件

These are confirmed production 
.tour
files. Fetch one when you need a working example of a specific step type, tour-level field, or narrative structure — don't write from memory when the real thing is one fetch away.
Find more with the GitHub code search: https://github.com/search?q=path%3A**%2F*.tour+&type=code
这些是经过验证的生产环境
.tour
文件。当你需要特定步骤类型、导览级字段或叙事结构的工作示例时，可获取其中一个——不要凭记忆编写，现成的示例触手可及。
可通过GitHub代码搜索找到更多：https://github.com/search?q=path%3A**%2F*.tour+&type=code

By step type / technique demonstrated

按步骤类型/演示技术分类

What to studyFile URL
directory
+ 
file+line
(contributor onboarding)		https://github.com/coder/code-server/blob/main/.tours/contributing.tour
selection
+ 
file+line
+ intro content step (accessibility project)		https://github.com/a11yproject/a11yproject.com/blob/main/.tours/code-tour.tour
Minimal tutorial — tight 
file+line
narration for interactive learning		https://github.com/lostintangent/rock-paper-scissors/blob/master/main.tour
Multi-tour repo with 
nextTour
chaining (cloud native OCI walkthroughs)		https://github.com/lucasjellema/cloudnative-on-oci-2021/blob/main/.tours/introduction.tour
isPrimary: true
(marks the onboarding entry point)		https://github.com/nickvdyck/webbundlr/blob/main/.tours/getting-started.tour
pattern
instead of 
line
(regex-anchored steps)		https://github.com/nickvdyck/webbundlr/blob/main/.tours/architecture.tour
Raw content tip: Prefix 
raw.githubusercontent.com
and drop 
/blob/
for raw JSON access.
A great tour is not just annotated files. It is a narrative — a story told to a specific person about what matters, why it matters, and what to do next. Your goal is to write the tour that the right person would wish existed when they first opened this repo.
CRITICAL: Only create 
.tour
JSON files. Never create, modify, or scaffold any other files.
学习内容文件URL
directory
+ 
file+line
（贡献者入职）		https://github.com/coder/code-server/blob/main/.tours/contributing.tour
selection
+ 
file+line
+ 介绍内容步骤（无障碍项目）		https://github.com/a11yproject/a11yproject.com/blob/main/.tours/code-tour.tour
极简教程——紧凑的
file+line
叙述用于交互式学习		https://github.com/lostintangent/rock-paper-scissors/blob/master/main.tour
支持
nextTour
链式调用的多导览仓库（云原生OCI导览）		https://github.com/lucasjellema/cloudnative-on-oci-2021/blob/main/.tours/introduction.tour
isPrimary: true
（标记为入职入口）		https://github.com/nickvdyck/webbundlr/blob/main/.tours/getting-started.tour
使用
pattern
替代
line
（正则锚定步骤）		https://github.com/nickvdyck/webbundlr/blob/main/.tours/architecture.tour
原始内容提示： 前缀添加
raw.githubusercontent.com
并去掉
/blob/
即可获取原始JSON内容。
优秀的导览不只是带注释的文件，它是一个叙事故事——为特定角色讲述重要内容、重要原因以及下一步行动。你的目标是编写一份当目标角色首次打开仓库时，会希望存在的导览。
重要提示：仅创建
.tour
JSON文件。切勿创建、修改或搭建任何其他文件。

Step 1: Discover the repo

步骤1：探索仓库

Before asking the user anything, explore the codebase:
  • List the root directory, read the README, and check key config files (package.json, pyproject.toml, go.mod, Cargo.toml, composer.json, etc.)
  • Identify the language(s), framework(s), and what the project does
  • Map the folder structure 1–2 levels deep
  • Find entry points: main files, index files, app bootstrapping
  • Note which files actually exist — every path you write in the tour must be real
If the repo is sparse or empty, say so and work with what exists.
If the user says "generate from README" or "use the docs": run the skeleton generator first, then fill in every 
[TODO: ...]
by reading the actual files:
bash
python skills/code-tour/scripts/generate_from_docs.py \
  --persona new-joiner \
  --output .tours/skeleton.tour
在询问用户任何问题之前，先探索代码库：
  • 列出根目录内容、阅读README、查看关键配置文件（package.json、pyproject.toml、go.mod、Cargo.toml、composer.json等）
  • 识别语言、框架以及项目用途
  • 梳理1-2层深度的文件夹结构
  • 找到入口文件：主文件、索引文件、应用启动文件
  • 记录实际存在的文件——你在导览中写入的每个路径都必须真实存在
如果仓库内容稀疏或为空，请告知用户并基于现有内容开展工作。
如果用户说"从README生成"或"使用文档"： 先运行框架生成器，然后通过读取实际文件填充所有
[TODO: ...]
内容：
bash
python skills/code-tour/scripts/generate_from_docs.py \
  --persona new-joiner \
  --output .tours/skeleton.tour

Entry points by language/framework

按语言/框架划分的入口文件

Don't read everything — start here, then follow imports.
StackEntry points to read first
Node.js / TS
index.js/ts
, 
server.js
, 
app.js
, 
src/main.ts
, 
package.json
(scripts)
Python
main.py
, 
app.py
, 
__main__.py
, 
manage.py
(Django), 
app/__init__.py
(Flask/FastAPI)
Go
main.go
, 
cmd/<name>/main.go
, 
internal/
Rust
src/main.rs
, 
src/lib.rs
, 
Cargo.toml
Java / Kotlin
*Application.java
, 
src/main/java/.../Main.java
, 
build.gradle
Ruby
config/application.rb
, 
config/routes.rb
, 
app/controllers/application_controller.rb
PHP
index.php
, 
public/index.php
, 
bootstrap/app.php
(Laravel)
无需阅读所有内容——从以下文件开始，再跟进依赖导入。
技术栈优先阅读的入口文件
Node.js / TS
index.js/ts
, 
server.js
, 
app.js
, 
src/main.ts
, 
package.json
（scripts字段）
Python
main.py
, 
app.py
, 
__main__.py
, 
manage.py
（Django）, 
app/__init__.py
（Flask/FastAPI）
Go
main.go
, 
cmd/<name>/main.go
, 
internal/
Rust
src/main.rs
, 
src/lib.rs
, 
Cargo.toml
Java / Kotlin
*Application.java
, 
src/main/java/.../Main.java
, 
build.gradle
Ruby
config/application.rb
, 
config/routes.rb
, 
app/controllers/application_controller.rb
PHP
index.php
, 
public/index.php
, 
bootstrap/app.php
（Laravel）

Repo type variants — adjust focus accordingly

仓库类型变体——调整重点

The same persona asks for different things depending on what kind of repo this is:
Repo typeWhat to emphasizeTypical anchor files
Service / APIRequest lifecycle, auth, error contractsrouter, middleware, handler, schema
Library / SDKPublic API surface, extension points, versioningindex/exports, types, changelog
CLI toolCommand parsing, config loading, output formattingmain, commands/, config
MonorepoPackage boundaries, shared contracts, build graphroot package.json/pnpm-workspace, shared/, packages/
FrameworkPlugin system, lifecycle hooks, escape hatchescore/, plugins/, lifecycle
Data pipelineSource → transform → sink, schema ownershipingest/, transform/, schema/, dbt models
Frontend appComponent hierarchy, state management, routingpages/, store/, router, api/
For monorepos: identify the 2–3 packages most relevant to the persona's goal. Don't try to tour everything — open the tour with a step that explains how to navigate the workspace, then stay focused.
同一角色的需求会因仓库类型而异：
仓库类型重点内容典型锚定文件
服务/API请求生命周期、认证、错误契约路由、中间件、处理器、Schema
库/SDK公共API表面、扩展点、版本控制索引/导出文件、类型定义、变更日志
CLI工具命令解析、配置加载、输出格式化主文件、commands/、配置文件
单体仓库包边界、共享契约、构建图谱根目录package.json/pnpm-workspace、shared/、packages/
框架插件系统、生命周期钩子、逃逸机制core/、plugins/、生命周期文件
数据流水线数据源→转换→输出、Schema归属ingest/、transform/、schema/、dbt模型
前端应用组件层级、状态管理、路由pages/、store/、路由文件、api/
对于单体仓库：识别与角色目标最相关的2-3个包。不要尝试导览所有内容——在导览开头添加一个步骤说明如何导航工作区，然后聚焦重点内容。

Large repo strategy

大型仓库策略

For repos with 100+ files: don't try to read everything.
  1. Read entry points and the README first
  2. Build a mental model of the top 5–7 modules
  3. For the requested persona, identify the 2–3 modules that matter most and read those deeply
  4. For modules you're not covering, mention them in the intro step as "out of scope for this tour"
  5. Use 
    directory
    steps for areas you mapped but didn't read — they orient without requiring full knowledge
A focused 10-step tour of the right files beats a scattered 25-step tour of everything.
对于包含100+文件的仓库：无需尝试阅读所有内容。
  1. 先阅读入口文件和README
  2. 构建核心5-7个模块的心智模型
  3. 针对目标角色，识别最关键的2-3个模块并深入阅读
  4. 对于未覆盖的模块，在介绍步骤中提及"本导览不包含此部分"
  5. 对已梳理但未深入阅读的区域使用
    directory
    步骤——无需全面了解即可帮助用户定位
聚焦于正确文件的10步导览，胜过零散覆盖所有内容的25步导览。

Step 2: Read the intent — infer everything you can, ask only what you can't

步骤2：解读意图——尽可能推断，仅询问无法推断的内容

One message from the user should be enough. Read their request and infer persona, depth, and focus before asking anything.
用户的一条消息应足够推断需求。先阅读用户请求，推断角色、深度和重点，再提问。

Intent map

意图映射

User says→ Persona→ Depth→ Action
"tour for this PR" / "PR review" / "#123"pr-reviewerstandardAdd 
uri
step for the PR; use 
ref
for the branch
"why did X break" / "RCA" / "incident"rca-investigatorstandardTrace the failure causality chain
"debug X" / "bug tour" / "find the bug"bug-fixerstandardEntry → fault points → tests
"onboarding" / "new joiner" / "ramp up"new-joinerstandardDirectories, setup, business context
"quick tour" / "vibe check" / "just the gist"vibecoderquick5–8 steps, fast path only
"explain how X works" / "feature tour"feature-explainerstandardUI → API → backend → storage
"architecture" / "tech lead" / "system design"architectdeepBoundaries, decisions, tradeoffs
"security" / "auth review" / "trust boundaries"security-reviewerstandardAuth flow, validation, sensitive sinks
"refactor" / "safe to extract?"refactorerstandardSeams, hidden deps, extraction order
"performance" / "bottlenecks" / "slow path"performance-optimizerstandardHot path, N+1, I/O, caches
"contributor" / "open source onboarding"external-contributorquickSafe areas, conventions, landmines
"concept" / "explain pattern X"concept-learnerstandardConcept → implementation → rationale
"test coverage" / "where to add tests"test-writerstandardContracts, seams, coverage gaps
"how do I call the API"api-consumerstandardPublic surface, auth, error semantics
Infer silently: persona, depth, focus area, whether to add 
uri
/
ref
, 
isPrimary
.
Ask only if you genuinely can't infer:
  • "bug tour" but no bug described → ask for the bug description
  • "feature tour" but no feature named → ask which feature
  • "specific files" explicitly requested → honor them as required stops
Never ask about 
nextTour
, 
commands
, 
when
, or 
stepMarker
unless the user mentioned them.
用户表述→ 对应角色→ 导览深度→ 操作
"tour for this PR" / "PR review" / "#123"pr-reviewer标准为PR添加
uri
步骤；为分支设置
ref
"why did X break" / "RCA" / "incident"rca-investigator标准追溯故障因果链
"debug X" / "bug tour" / "find the bug"bug-fixer标准入口→故障点→测试
"onboarding" / "new joiner" / "ramp up"new-joiner标准目录、设置、业务背景
"quick tour" / "vibe check" / "just the gist"vibecoder快速5-8步，仅覆盖核心路径
"explain how X works" / "feature tour"feature-explainer标准UI→API→后端→存储
"architecture" / "tech lead" / "system design"architect深入边界、决策、权衡
"security" / "auth review" / "trust boundaries"security-reviewer标准认证流程、验证、敏感数据处理
"refactor" / "safe to extract?"refactorer标准衔接点、隐藏依赖、提取顺序
"performance" / "bottlenecks" / "slow path"performance-optimizer标准热点路径、N+1问题、I/O、缓存
"contributor" / "open source onboarding"external-contributor快速安全贡献区域、约定、风险点
"concept" / "explain pattern X"concept-learner标准概念→实现→原理
"test coverage" / "where to add tests"test-writer标准契约、衔接点、覆盖缺口
"how do I call the API"api-consumer标准公共表面、认证、错误语义
默默推断： 角色、深度、重点区域、是否添加
uri
/
ref
、
isPrimary
。
仅在无法推断时提问：
  • "bug tour"但未描述具体bug → 询问bug详情
  • "feature tour"但未指定功能 → 询问具体功能
  • 用户明确要求特定文件 → 必须包含这些文件
除非用户提及，否则不要询问
nextTour
、
commands
、
when
或
stepMarker
相关内容。

PR tour recipe

PR导览指南

For PR tours: set 
"ref"
to the branch, open with a 
uri
step for the PR, cover changed files first, then unchanged-but-critical files, close with a reviewer checklist.
PR导览：将
"ref"
设置为分支，开头添加PR的
uri
步骤，先覆盖变更文件，再覆盖未变更但关键的文件，结尾添加评审清单。

User-provided customization — always honor these

用户自定义需求——必须遵循

User saysWhat to do
"cover 
src/auth.ts
and 
config/db.yml
"		Those files are required stops
"pin to the 
v2.3.0
tag" / "this commit: abc123"		Set 
"ref": "v2.3.0"
"link to PR #456" / pastes a URLAdd a 
uri
step at the right narrative moment
"lead into the security tour when done"Set 
"nextTour": "Security Review"
"make this the main onboarding tour"Set 
"isPrimary": true
"open a terminal at this step"Add 
"commands": ["workbench.action.terminal.focus"]
"deep" / "thorough" / "5 steps" / "quick"Override depth accordingly
用户表述操作
"cover 
src/auth.ts
and 
config/db.yml
"		这些文件是必选导览节点
"pin to the 
v2.3.0
tag" / "this commit: abc123"		设置
"ref": "v2.3.0"
"link to PR #456" / 粘贴URL在合适的叙事节点添加
uri
步骤
"lead into the security tour when done"设置
"nextTour": "Security Review"
"make this the main onboarding tour"设置
"isPrimary": true
"open a terminal at this step"添加
"commands": ["workbench.action.terminal.focus"]
"deep" / "thorough" / "5 steps" / "quick"相应调整导览深度

Step 3: Read the actual files — no exceptions

步骤3：读取实际文件——无例外

Every file path and line number in the tour must be verified by reading the file. A tour pointing to the wrong file or a non-existent line is worse than no tour.
For every planned step:
  1. Read the file
  2. Find the exact line of the code you want to highlight
  3. Understand it well enough to explain it to the target persona
If a user-requested file doesn't exist, say so — don't silently substitute another.
导览中的每个文件路径和行号都必须通过读取文件验证。指向错误文件或不存在行号的导览不如没有导览。
对于每个计划步骤：
  1. 读取文件
  2. 找到要高亮的代码的准确行号
  3. 充分理解代码，以便向目标角色解释
如果用户要求的文件不存在，请告知用户——不要无声替换为其他文件。

Step 4: Write the tour

步骤4：编写导览

Save to 
.tours/<persona>-<focus>.tour
. Read 
references/codetour-schema.json
for the authoritative field list. Every field you use must appear in that schema.
保存至
.tours/<persona>-<focus>.tour
。查阅
references/codetour-schema.json
获取权威字段列表。你使用的每个字段都必须出现在该Schema中。

Tour root

导览根结构

json
{
  "$schema": "https://aka.ms/codetour-schema",
  "title": "Descriptive Title — Persona / Goal",
  "description": "One sentence: who this is for and what they'll understand after.",
  "ref": "main",
  "isPrimary": false,
  "nextTour": "Title of follow-up tour",
  "steps": []
}
Omit any field that doesn't apply to this tour.
when
 — conditional display. A JavaScript expression evaluated at runtime. Only show this tour if the condition is true. Useful for persona-specific auto-launching, or hiding advanced tours until a simpler one is complete.
json
{ "when": "workspaceFolders[0].name === 'api'" }
stepMarker
 — embed step anchors directly in source code comments. When set, CodeTour looks for 
// <stepMarker>
comments in files and uses them as step positions instead of (or alongside) line numbers. Useful for tours on actively changing code where line numbers shift constantly. Example: set 
"stepMarker": "CT"
and put 
// CT
in the source file. Don't suggest this unless the user asks — it requires editing source files, which is unusual.
json
{
  "$schema": "https://aka.ms/codetour-schema",
  "title": "描述性标题 — 角色 / 目标",
  "description": "一句话说明：面向谁，看完后能理解什么。",
  "ref": "main",
  "isPrimary": false,
  "nextTour": "后续导览标题",
  "steps": []
}
省略与当前导览无关的字段。
when
 —— 条件显示。运行时评估的JavaScript表达式。仅当条件为真时显示此导览。适用于特定角色的自动启动，或在完成简单导览前隐藏高级导览。
json
{ "when": "workspaceFolders[0].name === 'api'" }
stepMarker
 —— 在源代码注释中嵌入步骤锚点。设置后，CodeTour会在文件中查找
// <stepMarker>
注释，并将其用作步骤位置，替代（或补充）行号。适用于代码频繁变更、行号经常变动的导览。示例：设置
"stepMarker": "CT"
并在源代码中添加
// CT
。除非用户要求，否则不建议使用——这需要修改源代码，并不常见。

Step types — full reference

步骤类型——完整参考

All step types: content (intro/closing, max 2), directory, file+line (workhorse), selection (code block), pattern (regex match), uri (external link), view (focus VS Code panel), commands (run VS Code commands).
Path rule: 
"file"
and 
"directory"
must be relative to repo root. No absolute paths, no leading 
./
.
所有步骤类型：content（介绍/结尾，最多2个）、directory、file+line（核心类型）、selection（代码块）、pattern（正则匹配）、uri（外部链接）、view（聚焦VS Code面板）、commands（运行VS Code命令）。
路径规则： 
"file"
和
"directory"
必须相对于仓库根目录。不允许绝对路径，不允许以
./
开头。

When to use each step type

各步骤类型适用场景

SituationStep type
Tour intro or closingcontent
"Here's what lives in this folder"directory
One line tells the whole storyfile + line
A function/class body is the pointselection
Line numbers shift, file is volatilepattern
PR / issue / doc gives the "why"uri
Reader should open terminal or explorerview or commands
场景步骤类型
导览介绍或结尾content
"此文件夹包含以下内容"directory
一行代码即可说明核心内容file + line
函数/类主体是讲解重点selection
行号经常变动，文件不稳定pattern
PR/issue/文档说明"原因"uri
读者需要打开终端或资源管理器view或commands

Step count calibration

步骤数量校准

Match steps to depth and persona. These are targets, not hard limits.
DepthTotal stepsCore path stepsNotes
Quick5–83–5Vibecoder, fast explorer — cut ruthlessly
Standard9–136–9Most personas — breadth + enough detail
Deep14–1810–13Architect, RCA — every tradeoff surfaced
Scale with repo size too. A 3-file CLI doesn't get 15 steps. A 200-file monolith shouldn't be squeezed into 5.
Repo sizeRecommended standard depth
Tiny (< 20 files)5–8 steps
Small (20–80 files)8–11 steps
Medium (80–300 files)10–13 steps
Large (300+ files)12–15 steps (scoped to relevant subsystem)
根据深度和角色匹配步骤数量。以下是目标值，而非硬性限制。
深度总步骤数核心路径步骤数说明
快速5–83–5快速探索者、快速导览——严格精简
标准9–136–9大多数角色——兼顾广度与足够细节
深入14–1810–13架构师、RCA调查——展现所有权衡
同时根据仓库大小调整。3个文件的CLI工具不需要15步。200个文件的单体仓库不应压缩到5步。
仓库大小推荐标准深度步骤数
极小（<20个文件）5–8步
小（20–80个文件）8–11步
中（80–300个文件）10–13步
大（300+个文件）12–15步（聚焦相关子系统）

Writing excellent descriptions — the SMIG formula

编写优质描述——SMIG公式

Every description should answer four questions in order. You don't need four paragraphs — but every description needs all four elements, even briefly.
S — Situation: What is the reader looking at? One sentence grounding them in context. M — Mechanism: How does this code work? What pattern, rule, or design is in play? I — Implication: Why does this matter for this persona's goal specifically? G — Gotcha: What would a smart person get wrong here? What's non-obvious, fragile, or surprising?
Descriptions should tell the reader something they couldn't learn by reading the file themselves. Name the pattern, explain the design decision, flag failure modes, and cross-reference related context.
每个描述都应按顺序回答四个问题。不需要四段文字，但每个描述都必须包含这四个要素，即使是简要说明。
S — 场景：读者正在看什么？一句话为他们提供上下文。 M — 机制：这段代码如何工作？使用了什么模式、规则或设计？ I — 影响：这对该角色的特定目标有什么重要性？ G — 陷阱：聪明人会在这里犯什么错？什么内容不明显、脆弱或出乎意料？
描述应告诉读者他们无法通过直接阅读文件了解的信息。点明模式、解释设计决策、标记故障模式，并交叉引用相关上下文。

Narrative arc — every tour, every persona

叙事逻辑——所有导览、所有角色通用

  1. Orientation — must be a 
    file
    or 
    directory
    step, never content-only.     Use 
    "file": "README.md", "line": 1
    or 
    "directory": "src"
    and put your welcome text in the description. A content-only first step (no 
    file
    , 
    directory
    , or 
    uri
    ) renders as a blank page in VS Code CodeTour — this is a known VS Code extension behaviour, not configurable.
  2. High-level map (1–3 directory or uri steps) — major modules and how they relate. Not every folder — just what this persona needs to know.
  3. Core path (file/line, selection, pattern, uri steps) — the specific code that matters. This is the heart of the tour. Read and narrate. Don't skim.
  4. Closing (content) — what the reader now understands, what they can do next, 2–3 suggested follow-up tours. If 
    nextTour
    is set, reference it by name here.
  1. 定位 —— 必须是
    file
    或
    directory
    步骤，不能仅用content    。使用
    "file": "README.md", "line": 1
    或
    "directory": "src"
    ，并将欢迎文本放在描述中。仅用content的第一步（无
    file
    、
    directory
    或
    uri
    ）在VS Code CodeTour中会显示空白页面——这是VS Code扩展的已知行为，无法配置。
  2. 高层概览（1-3个directory或uri步骤）——主要模块及其关系。不是每个文件夹都要覆盖，仅覆盖该角色需要了解的内容。
  3. 核心路径（file/line、selection、pattern、uri步骤）——重要的具体代码。这是导览的核心。仔细阅读并叙述，不要略读。
  4. 结尾（content）——读者现在理解了什么，下一步可以做什么，2-3个建议的后续导览。如果设置了
    nextTour
    ，在此处提及它的名称。

Closing steps

结尾步骤

Don't summarize — the reader just read it. Instead, tell them what they can now do, what to avoid, and suggest 2-3 follow-up tours.
不要总结——读者刚看完内容。相反，告诉他们现在可以做什么，要避免什么，并建议2-3个后续导览。

The 20 personas

20种角色

PersonaGoalMust coverAvoid
VibecoderGet the vibe fastEntry point, request flow, main modules. Max 8 steps.Deep dives, edge cases
New joinerStructured ramp-upDirectories, setup, business context, service boundaries.Advanced internals
Bug fixerRoot cause fastUser action → trigger → fault points. Repro hints + test locations.Architecture tours
RCA investigatorWhy did it failCausality chain, side effects, race conditions, observability.Happy path
Feature explainerOne feature end-to-endUI → API → backend → storage. Feature flags, edge cases.Unrelated features
PR reviewerReview the change correctlyChange story, invariants, risky areas, reviewer checklist. URI step for PR.Unrelated context
Security reviewerTrust boundariesAuth flow, input validation, secret handling, sensitive sinks.Unrelated business logic
RefactorerSafe restructuringSeams, hidden deps, coupling hotspots, safe extraction order.Feature explanations
External contributorContribute without breakingSafe areas, code style, architecture landmines.Deep internals
Tech lead / architectShape and rationaleModule boundaries, design tradeoffs, risk hotspots.Line-by-line walkthroughs
角色目标必须覆盖内容避免内容
快速探索者（Vibecoder）快速了解仓库概况入口点、请求流程、主要模块。最多8步。深入讲解、边缘案例
新员工（New joiner）结构化入职熟悉目录、设置、业务背景、服务边界。高级内部实现
Bug修复者（Bug fixer）快速定位根因用户操作→触发点→故障点。复现提示+测试位置。架构导览
RCA调查员（RCA investigator）查明故障原因因果链、副作用、竞态条件、可观测性。正常流程
功能讲解者（Feature explainer）端到端讲解单个功能UI→API→后端→存储。功能开关、边缘案例。无关功能
PR评审者（PR reviewer）正确评审变更变更背景、不变量、风险区域、评审清单。添加PR的URI步骤。无关上下文
安全评审者（Security reviewer）信任边界检查认证流程、输入验证、密钥处理、敏感数据输出。无关业务逻辑
重构者（Refactorer）安全重构衔接点、隐藏依赖、耦合热点、安全提取顺序。功能讲解
外部贡献者（External contributor）无破坏地贡献代码安全贡献区域、代码风格、架构风险点。深入内部实现
技术负责人/架构师（Tech lead / architect）设计与原理讲解模块边界、设计权衡、风险热点。逐行讲解

Designing a tour series

设计导览系列

When a codebase is complex enough that one tour can't cover it well, design a series. The 
nextTour
field chains them: when the reader finishes one tour, VS Code offers to launch the next automatically.
Plan the series before writing any tour. A good series has:
  • A clear escalation path (broad → narrow, orientation → deep-dive)
  • No duplicate steps between tours
  • Each tour standalone enough to be useful on its own
Set 
nextTour
in each tour to the 
title
of the next one (must match exactly). Each tour should be standalone enough to be useful on its own.
当代码库过于复杂，单个导览无法覆盖时，设计导览系列。
nextTour
字段可将它们串联：当读者完成一个导览后，VS Code会自动提示启动下一个。
在编写任何导览前规划系列。优秀的系列应具备：
  • 清晰的递进路径（从宽泛到具体，从定位到深入）
  • 导览之间无重复步骤
  • 每个导览足够独立，可单独使用
在每个导览中设置
nextTour
为下一个导览的
title
（必须完全匹配）。每个导览应足够独立，可单独使用。

What CodeTour cannot do

CodeTour无法实现的功能

If asked for any of these, say clearly that it's not supported — do not suggest a workaround that doesn't exist:
RequestReality
Auto-advance to next step after X secondsNot supported. Navigation is always manual — the reader clicks Next. There is no timer, delay, or autoplay step mechanic in CodeTour.
Embed a video or GIF in a stepNot supported. Descriptions are Markdown text only.
Run arbitrary shell commandsNot supported. 
commands
only executes VS Code commands (e.g. 
workbench.action.terminal.focus
), not shell commands.
Branch / conditional next stepNot supported. Tours are linear. 
when
controls whether a tour is shown, not which step follows which.
Show a step without opening a filePartially — content-only steps work, but step 1 must have a 
file
or 
directory
anchor or VS Code shows a blank page.
如果用户要求以下功能，请明确告知不支持——不要建议不存在的解决方法：
请求实际情况
X秒后自动跳转到下一步不支持。导航始终是手动的——读者点击下一步。CodeTour中没有计时器、延迟或自动播放机制。
在步骤中嵌入视频或GIF不支持。描述仅支持Markdown文本。
运行任意Shell命令不支持。
commands
仅能执行VS Code命令（如
workbench.action.terminal.focus
），不能执行Shell命令。
分支/条件下一步不支持。导览是线性的。
when
控制是否显示导览，而非步骤跳转逻辑。
不打开文件显示步骤部分支持——仅content步骤可行，但第一步必须有
file
或
directory
锚点，否则VS Code会显示空白页面。

Anti-patterns

反模式

Anti-patternFix
File listing — visiting files with "this file contains..."Tell a story; each step should depend on the previous one
Generic descriptionsName the specific pattern/gotcha unique to this codebase
Line number guessingNever write a line number you didn't verify by reading the file
Ignoring the personaCut every step that doesn't serve their specific goal
Hallucinated filesIf a file doesn't exist, skip the step
反模式修复方法
文件列表式导览——访问文件仅说明"此文件包含..."讲述故事；每个步骤应依赖前一个步骤
通用描述点明此代码库特有的模式/陷阱
猜测行号绝不编写未通过读取文件验证的行号
忽略角色需求删除所有不符合角色特定目标的步骤
虚构文件如果文件不存在，跳过该步骤

Quality checklist — verify before writing the file

质量检查清单——编写文件前验证

  • Every 
    file
    path is relative to the repo root (no leading 
    /
    or 
    ./
    )
  • Every 
    file
    path read and confirmed to exist
  • Every 
    line
    number verified by reading the file (not guessed)
  • Every 
    directory
    is relative to the repo root and confirmed to exist
  • Every 
    pattern
    regex would match a real line in the file
  • Every 
    uri
    is a complete, real URL (https://...)
  • ref
    is a real branch/tag/commit if set
  • nextTour
    exactly matches the 
    title
    of another 
    .tour
    file if set
  • Only 
    .tour
    JSON files created — no source code touched
  • First step has a 
    file
    or 
    directory
    anchor (content-only first step = blank page in VS Code)
  • Tour ends with a closing content step that tells the reader what they can do next
  • Every description answers SMIG — Situation, Mechanism, Implication, Gotcha
  • Persona's priorities drive step selection (cut everything that doesn't serve their goal)
  • Step count matches requested depth and repo size (see calibration table)
  • At most 2 content-only steps (intro + closing)
  • All fields conform to 
    references/codetour-schema.json
  • 每个
    file
    路径相对于仓库根目录（不以
    /
    或
    ./
    开头）
  • 每个
    file
    路径已读取并确认存在
  • 每个
    line
    号已通过读取文件验证（未猜测）
  • 每个
    directory
    相对于仓库根目录并确认存在
  • 每个
    pattern
    正则表达式可匹配文件中的真实行
  • 每个
    uri
    是完整有效的URL（以https://开头）
  • 如果设置了
    ref
    ，它是真实的分支/标签/提交
  • 如果设置了
    nextTour
    ，它与
    .tours/
    中另一个
    .tour
    文件的
    title
    完全匹配
  • 仅创建
    .tour
    JSON文件——未修改源代码
  • 第一步有
    file
    或
    directory
    锚点（仅content的第一步会在VS Code中显示空白页面）
  • 导览以content结尾步骤结束，告知读者下一步可做什么
  • 每个描述符合SMIG——场景、机制、影响、陷阱
  • 步骤选择由角色优先级驱动（删除所有不符合目标的步骤）
  • 步骤数量符合请求的深度和仓库大小（参考校准表）
  • 仅content步骤最多2个（介绍+结尾）
  • 所有字段符合
    references/codetour-schema.json
    规范

Step 5: Validate the tour

步骤5：验证导览

Always run the validator immediately after writing the tour file. Do not skip this step.
bash
python ~/.agents/skills/code-tour/scripts/validate_tour.py .tours/<name>.tour --repo-root .
The validator checks:
  • JSON validity
  • Every 
    file
    path exists and every 
    line
    is within file bounds
  • Every 
    directory
    exists
  • Every 
    pattern
    regex compiles and matches at least one line in the file
  • Every 
    uri
    starts with 
    https://
  • nextTour
    matches an existing tour title in 
    .tours/
  • Content-only step count (warns if > 2)
  • Narrative arc (warns if no orientation or closing step)
Fix every error before proceeding. Re-run until the validator reports ✓ or only warnings. Warnings are advisory — use your judgment. Do not show the user the tour until validation passes.
Common VS Code issues: Content-only first step renders blank (anchor to file/directory instead). Absolute or 
./
-prefixed paths silently fail. Out-of-bounds line numbers scroll nowhere.
If you can't run scripts, manually verify: step 1 has 
file
/
directory
, all paths exist, all line numbers are in bounds, 
nextTour
matches exactly.
Autoplay: 
isPrimary: true
+ 
.vscode/settings.json
with 
{ "codetour.promptForPrimaryTour": true }
prompts on repo open. Omit 
ref
for tours that should appear on any branch.
Share: For public repos, users can open tours at 
https://vscode.dev/github.com/<owner>/<repo>
with no install.
编写完导览文件后立即运行验证器。不要跳过此步骤。
bash
python ~/.agents/skills/code-tour/scripts/validate_tour.py .tours/<name>.tour --repo-root .
验证器检查：
  • JSON有效性
  • 每个
    file
    路径存在且
    line
    号在文件范围内
  • 每个
    directory
    存在
  • 每个
    pattern
    正则表达式可编译并匹配文件中的至少一行
  • 每个
    uri
    以
    https://
    开头
  • nextTour
    匹配
    .tours/
    中存在的导览标题
  • 仅content步骤数量（超过2个时发出警告）
  • 叙事逻辑（无定位或结尾步骤时发出警告）
修复所有错误后再继续。重新运行直到验证器报告✓或仅显示警告。警告是建议性的——自行判断。验证通过前不要向用户展示导览。
VS Code常见问题： 仅content的第一步显示空白页面（改为锚定到文件/目录）。绝对路径或以
./
开头的路径会静默失败。超出范围的行号无法滚动到对应位置。
如果无法运行脚本，请手动验证：第一步有
file
/
directory
、所有路径存在、所有行号在范围内、
nextTour
完全匹配。
自动启动： 设置
isPrimary: true
并在
.vscode/settings.json
中添加
{ "codetour.promptForPrimaryTour": true }
，可在打开仓库时提示启动导览。对于适用于所有分支的导览，省略
ref
。
分享： 对于公共仓库，用户可通过
https://vscode.dev/github.com/<owner>/<repo>
打开导览，无需安装扩展。

Step 6: Summarize

步骤6：总结

After writing the tour, tell the user:
  • File path (
    .tours/<name>.tour
    )
  • One-paragraph summary of what the tour covers and who it's for
  • The 
    vscode.dev
    URL if the repo is public (so they can share it immediately)
  • 2–3 suggested follow-up tours (or the next tour in the series if one was planned)
  • Any user-requested files that didn't exist (be explicit — don't quietly substitute)
编写完导览后，告知用户：
  • 文件路径（
    .tours/<name>.tour
    ）
  • 一段文字总结导览覆盖内容和面向人群
  • 如果是公共仓库，提供
    vscode.dev
    链接（方便用户立即分享）
  • 2-3个建议的后续导览（如果规划了系列，则为系列中的下一个导览）
  • 用户要求但不存在的文件（明确告知——不要无声替换）

File naming

文件命名规则

<persona>-<focus>.tour
— kebab-case, communicates both:
onboarding-new-joiner.tour
bug-fixer-payment-flow.tour
architect-overview.tour
vibecoder-quickstart.tour
pr-review-auth-refactor.tour
security-auth-boundaries.tour
concept-dependency-injection.tour
rca-login-outage.tour
<persona>-<focus>.tour
——短横线命名法，同时传达角色和重点：
onboarding-new-joiner.tour
bug-fixer-payment-flow.tour
architect-overview.tour
vibecoder-quickstart.tour
pr-review-auth-refactor.tour
security-auth-boundaries.tour
concept-dependency-injection.tour
rca-login-outage.tour