code-tour

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Code Tour

CodeTour

Create CodeTour files — persona-targeted, step-by-step walkthroughs of a codebase that link directly to files and line numbers. CodeTour files live in

.tours/

and work with the VS Code CodeTour extension.

创建CodeTour文件——针对特定角色、分步式的代码库导览内容，可直接链接到文件和行号。CodeTour文件存储在

.tours/

目录下，可与VS Code CodeTour扩展配合使用。

Overview

概述

A great tour is a narrative — a story told to a specific person about what matters, why it matters, and what to do next. Only create

.tour

JSON files. Never modify source code.

优质的导览是一段叙事内容——为特定人群讲述什么内容重要、为何重要以及下一步该做什么。仅创建

.tour

格式的JSON文件，切勿修改源代码。

When to Use This Skill

使用场景

User asks to create a code tour, onboarding tour, or architecture walkthrough
User says "tour for this PR", "explain how X works", "vibe check", "RCA tour"
User wants a contributor guide, security review, or bug investigation walkthrough
Any request for a structured walkthrough with file/line anchors

用户要求创建代码导览、入职导览或架构走查
用户提及“此PR的导览”、“解释X的工作原理”、“快速了解项目氛围”、“根因分析导览”
用户需要贡献者指南、安全评审或Bug调查走查
任何带有文件/行号锚点的结构化走查请求

Core Workflow

核心工作流程

1. Discover the repo

1. 探索代码库

Before asking anything, explore the codebase:

In parallel: list root directory, read README, check config files. Then: identify language(s), framework(s), project purpose. Map folder structure 1-2 levels deep. Find entry points — every path in the tour must be real.

If the repo has fewer than 5 source files, create a quick-depth tour regardless of persona — there's not enough to warrant a deep one.

在提问前，先探索代码库：

并行执行：列出根目录、阅读README、检查配置文件。然后：识别使用的语言、框架、项目用途。梳理1-2层目录结构。找到入口文件——导览中的每一条路径都必须真实存在。

如果代码库的源文件少于5个，无论目标角色是谁，都创建一个快速导览——内容不足以支撑深度导览。

2. Infer the intent

2. 推断用户意图

One message should be enough. Infer persona, depth, and focus silently.

User says	Persona	Depth
"tour for this PR"	pr-reviewer	standard
"why did X break" / "RCA"	rca-investigator	standard
"onboarding" / "new joiner"	new-joiner	standard
"quick tour" / "vibe check"	vibecoder	quick
"architecture"	architect	deep
"security" / "auth review"	security-reviewer	standard
(no qualifier)	new-joiner	standard

When intent is ambiguous, default to new-joiner persona at standard depth — it's the most generally useful.

仅需一条消息即可推断。默默确定目标角色、导览深度和重点方向。

用户表述	目标角色	导览深度
"tour for this PR"	pr-reviewer	标准
"why did X break" / "RCA"	rca-investigator	标准
"onboarding" / "new joiner"	new-joiner	标准
"quick tour" / "vibe check"	vibecoder	快速
"architecture"	architect	深入
"security" / "auth review"	security-reviewer	标准
无额外说明	new-joiner	标准

当意图不明确时，默认采用new-joiner角色的标准深度导览——这是通用性最强的选项。

3. Read actual files

3. 读取实际文件

Every file path and line number must be verified. A tour pointing to the wrong line is worse than no tour.

必须验证每一个文件路径和行号。指向错误行号的导览还不如没有导览。

4. Write the tour

4. 编写导览

Save to

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

json

{
  "$schema": "https://aka.ms/codetour-schema",
  "title": "Descriptive Title — Persona / Goal",
  "description": "Who this is for and what they'll understand after.",
  "ref": "<current-branch-or-commit>",
  "steps": []
}

保存至

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

。

json

{
  "$schema": "https://aka.ms/codetour-schema",
  "title": "Descriptive Title — Persona / Goal",
  "description": "Who this is for and what they'll understand after.",
  "ref": "<current-branch-or-commit>",
  "steps": []
}

Step types

步骤类型

Type	When to use	Example
Content	Intro/closing only (max 2)	`{ "title": "Welcome", "description": "..." }`
Directory	Orient to a module	`{ "directory": "src/services", "title": "..." }`
File + line	The workhorse	`{ "file": "src/auth.ts", "line": 42, "title": "..." }`
Selection	Highlight a code block	`{ "file": "...", "selection": {...}, "title": "..." }`
Pattern	Regex match (volatile files)	`{ "file": "...", "pattern": "class App", "title": "..." }`
URI	Link to PR, issue, doc	`{ "uri": "https://...", "title": "..." }`

类型	使用场景	示例
Content	仅用于介绍/收尾（最多2个）	`{ "title": "Welcome", "description": "..." }`
Directory	引导用户了解模块	`{ "directory": "src/services", "title": "..." }`
File + line	核心步骤类型	`{ "file": "src/auth.ts", "line": 42, "title": "..." }`
Selection	高亮代码块	`{ "file": "...", "selection": {...}, "title": "..." }`
Pattern	正则匹配（内容易变的文件）	`{ "file": "...", "pattern": "class App", "title": "..." }`
URI	链接到PR、Issue或文档	`{ "uri": "https://...", "title": "..." }`

Step count

步骤数量

Depth	Steps	Use for
Quick	5-8	Vibecoder, fast exploration
Standard	9-13	Most personas
Deep	14-18	Architect, RCA

深度	步骤数	适用场景
快速	5-8	Vibecoder角色、快速探索
标准	9-13	大多数角色
深入	14-18	Architect角色、根因分析

Writing descriptions — SMIG formula

描述编写——SMIG公式

S — Situation: What is the reader looking at?
M — Mechanism: How does this code work?
I — Implication: Why does this matter for this persona?
G — Gotcha: What would a smart person get wrong?

S — 场景: 读者正在查看什么内容？
M — 机制: 这段代码如何工作？
I — 意义: 这对该角色为何重要？
G — 注意点: 聪明人容易犯什么错误？

5. Validate

5. 验证

Every
```
file
```
path relative to repo root (no leading
```
/
```
or
```
./
```
)
Every
```
file
```
confirmed to exist
Every
```
line
```
verified by reading the file
First step has
```
file
```
or
```
directory
```
anchor
At most 2 content-only steps
```
nextTour
```
matches another tour's
```
title
```
exactly if set

所有
```
file
```
路径均为相对于代码库根目录的路径（无前缀
```
/
```
或
```
./
```
）
所有
```
file
```
已确认存在
所有
```
line
```
均已通过读取文件验证
第一步包含
```
file
```
或
```
directory
```
锚点
内容型步骤最多2个
如果设置了
```
nextTour
```
，需与另一个导览的
```
title
```
完全匹配

Personas

目标角色

Persona	Goal	Must cover
Vibecoder	Get the vibe fast	Entry point, main modules. Max 8 steps.
New joiner	Structured ramp-up	Directories, setup, business context
Bug fixer	Root cause fast	Trigger -> fault points -> tests
RCA investigator	Why did it fail	Causality chain, observability anchors
Feature explainer	End-to-end	UI -> API -> backend -> storage
PR reviewer	Review correctly	Change story, invariants, risky areas
Architect	Shape and rationale	Boundaries, tradeoffs, extension points
Security reviewer	Trust boundaries	Auth flow, validation, secret handling
Refactorer	Safe restructuring	Seams, hidden deps, extraction order
External contributor	Contribute safely	Safe areas, conventions, landmines

角色	目标	必须覆盖的内容
Vibecoder	快速了解项目氛围	入口文件、主要模块。最多8个步骤。
New joiner	结构化上手	目录结构、环境搭建、业务背景
Bug fixer	快速定位根因	触发点 -> 故障点 -> 测试用例
RCA investigator	分析故障原因	因果链、可观测性锚点
Feature explainer	端到端讲解	UI -> API -> 后端 -> 存储
PR reviewer	正确评审PR	变更背景、不变量、风险区域
Architect	了解架构设计与 rationale	边界、权衡点、扩展点
Security reviewer	检查信任边界	认证流程、验证逻辑、密钥处理
Refactorer	安全重构	衔接点、隐藏依赖、提取顺序
External contributor	安全贡献代码	安全修改区域、规范、注意事项

Narrative Arc

叙事结构

Orientation —
```
file
```
or
```
directory
```
step (never content-only first step — blank in VS Code)
High-level map — 1-3 directory steps showing major modules
Core path — file/line steps, the heart of the tour
Closing — what the reader can now do, suggested follow-ups

定位 —
```
file
```
或
```
directory
```
步骤（第一步切勿仅为内容型步骤——在VS Code中会显示空白）
全局概览 — 1-3个目录步骤展示主要模块
核心路径 — 文件/行号步骤，导览的核心内容
收尾 — 读者现在可以完成的操作、建议后续内容

Anti-Patterns

反模式

Anti-pattern	Fix
File listing — "this file contains the models"	Tell a story. Each step depends on the previous.
Generic descriptions	Name the specific pattern unique to this codebase.
Line number guessing	Never write a line you didn't verify by reading.
Too many steps for quick depth	Actually cut steps.
Hallucinated files	If it doesn't exist, skip the step.
Recap closing — "we covered X, Y, Z"	Tell the reader what they can now do.
Content-only first step	Anchor step 1 to a file or directory.

反模式	修复方案
文件罗列 — “此文件包含模型”	讲述完整故事，每个步骤需依赖前序内容。
通用描述	点明代码库特有的具体模式。
猜测行号	切勿编写未通过读取文件验证的行号。
快速深度导览包含过多步骤	实际删减步骤。
虚构文件	如果文件不存在，跳过该步骤。
总结式收尾 — “我们介绍了X、Y、Z”	告诉读者现在可以执行什么操作。
第一步仅为内容型	将第一步锚定到某个文件或目录。

Cross-References

交叉引用

Related:
```
engineering/codebase-onboarding
```
— for broader onboarding beyond tours
Related:
```
engineering/pr-review-expert
```
— for automated PR review workflows
CodeTour extension: microsoft/codetour
Real-world tours: coder/code-server

相关内容：
```
engineering/codebase-onboarding
```
— 适用于导览之外的更全面入职流程
相关内容：
```
engineering/pr-review-expert
```
— 自动化PR评审流程
CodeTour扩展：microsoft/codetour
真实案例：coder/code-server