code-tour

Code Tour

创建 CodeTour 文件：这是面向特定角色、分步骤的代码库导览，并直接链接到文件和行号。CodeTour 文件存放在 .tours/ 目录中，配合 VS Code CodeTour 扩展使用。

概述

优秀的导览是一段叙述，是讲给特定读者的故事，讲清楚什么最重要、为什么重要，以及接下来该做什么。只创建 .tour JSON 文件，绝不修改源代码。

何时使用此技能

• 用户要求创建代码导览、新人导览或架构导览
• 用户说“这个 PR 的导览”“解释 X 如何工作”“vibe check”“RCA 导览”
• 用户需要贡献者指南、安全审查或缺陷排查导览
• 任何需要带文件/行号锚点的结构化导览请求

核心工作流

1. 探索代码仓库

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

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

如果仓库源文件少于 5 个，无论角色如何，都创建快速深度的导览，因为内容不足以支撑深度导览。

2. 推断意图

一条消息通常就足够。静默推断角色、深度和重点。

用户表述	角色	深度
“这个 PR 的导览”	pr-reviewer	standard
“为什么 X 坏了” / “RCA”	rca-investigator	standard
“入职” / “新成员”	new-joiner	standard
“快速导览” / “vibe check”	vibecoder	quick
“架构”	architect	deep
“安全” / “认证审查”	security-reviewer	standard
（无限定词）	new-joiner	standard

当意图不明确时，默认使用 new-joiner 角色和 standard 深度，这是最普遍适用的组合。

3. 阅读实际文件

每个文件路径和行号都必须经过核实。 指向错误行的导览比没有导览更糟。

4. 编写导览

保存为 .tours/<persona>-<focus>.tour。

{
  "$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": []
}

步骤类型

类型	使用场景	示例
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": "..." }

步骤数量

深度	步骤数	适用场景
Quick	5-8	Vibecoder，快速探索
Standard	9-13	大多数角色
Deep	14-18	Architect、RCA

编写描述：SMIG 公式

• S — Situation（情境）：读者正在看什么？
• M — Mechanism（机制）：这段代码如何工作？
• I — Implication（影响）：这对该角色为何重要？
• G — Gotcha（陷阱）：聪明的人可能会在哪里出错？

5. 校验

• 每个 file 路径都相对于仓库根目录（不带前导 / 或 ./）
• 每个 file 都已确认存在
• 每个 line 都已通过阅读文件核实
• 第一步带有 file 或 directory 锚点
• 纯内容步骤最多 2 个
• 若设置了 nextTour，其值必须与另一个导览的 title 完全一致

Personas

Persona	Goal	Must cover
Vibecoder	快速上手体验	入口点，主要模块。最多 8 步。
New joiner	结构化入门	目录，环境搭建，业务背景
Bug fixer	快速定位根因	触发条件 -> 故障点 -> 测试
RCA investigator	为何失败	因果链，可观测性锚点
Feature explainer	端到端讲解	UI -> API -> 后端 -> 存储
PR reviewer	正确地审查	变更脉络，不变量，风险区域
Architect	架构与设计理由	边界，权衡，扩展点
Security reviewer	信任边界	认证流程，校验，密钥处理
Refactorer	安全的重构	接缝，隐藏依赖，抽取顺序
External contributor	安全地参与贡献	安全区域，约定，雷区

Narrative Arc

1. Orientation — file 或 directory 步骤（绝不能以纯内容作为第一步，否则在 VS Code 中会显示为空白）
2. High-level map — 1-3 个 directory 步骤，展示主要模块
3. Core path — file/line 步骤，即导览的核心
4. Closing — 读者现在能够做什么，建议的后续步骤

Anti-Patterns

Anti-pattern	Fix
File listing — "this file contains the models"	讲述一个故事。每一步都依赖前一步。
Generic descriptions	指出该代码库独有的具体模式。
Line number guessing	绝不写下未通过阅读代码验证过的行号。
Too many steps for quick depth	真正削减步骤。
Hallucinated files	如果文件不存在，则跳过该步骤。
Recap closing — "we covered X, Y, Z"	告诉读者他们现在能够做什么。
Content-only first step	将第 1 步锚定到一个文件或目录。

Cross-References

• Related: engineering/codebase-onboarding — 用于导览之外更广泛的代码库入门
• Related: engineering/pr-review-expert — 用于自动化 PR 审查工作流
• CodeTour extension: microsoft/codetour
• Real-world tours: coder/code-server