代码导览

code-tour

分类编程

作者Alireza Rezvani

许可MIT

评分4.20/5

使用9.2K

Code Tour

创建 CodeTour 文件 —— 针对特定角色、分步骤的代码库引导流程，可直接链接到文件和行号。CodeTour 文件存放于 .tours/ 目录下，并与 VS Code CodeTour 扩展配合使用。

概述

一次优秀的 tour 应该是一个叙事 —— 向特定人员讲述关于什么重要、为什么重要以及下一步该做什么的故事。仅创建 .tour JSON 文件，切勿修改源代码。

何时使用此技能

用户请求创建代码 tour、入职引导 tour 或架构引导

用户提到 "this PR 的 tour"、"解释 X 如何工作"、"vibe check"、"RCA tour"

用户需要贡献者指南、安全评审或 Bug 调查引导

任何需要带有文件/行锚点的结构化引导请求

核心工作流

1. 探索仓库

在提出任何问题之前，先探索代码库：

并行执行：列出根目录、阅读 README、检查配置文件。
随后：识别语言、框架、项目目的。映射 1-2 层的文件夹结构。寻找入口点 —— tour 中的每条路径必须真实存在。

如果仓库的源文件少于 5 个，无论角色如何，均创建快速深度（quick-depth）的 tour —— 因为文件量不足以支撑深度 tour。

2. 推断意图

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

| 用户表述 | 角色 (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 |
| (无限定词) | new-joiner | standard |

当意图模糊时，默认使用 new-joiner 角色和 standard 深度 —— 这是最通用且有用的。

3. 读取实际文件

必须验证每个文件路径和行号。 一个指向错误行号的 tour 比没有 tour 更糟糕。

4. 编写 tour

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

json

{
  "$schema": "https://aka.ms/codetour-schema",
  "title": "描述性标题 — 角色 / 目标",
  "description": "面向人群以及完成引导后将理解的内容。",
  "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 | 大多数场景 |
sonas |
| Deep | 14-18 | 架构师, RCA |

编写描述 —— SMIG 公式

S — Situation (场景)：读者正在看什么？

M — Mechanism (机制)：这段代码是如何工作的？

I — Implication (影响)：为什么这对该角色很重要？

G — Gotcha (陷阱)：聪明的人可能会在哪里产生误解？

5. 验证

[ ] 所有 file 路径均相对于仓库根目录（无前导 / 或 ./）

[ ] 确认每个 file 均存在

[ ] 通过阅读文件验证每一行 line

[ ] 第一步必须包含 file 或 directory 锚点

[ ] 纯内容步骤最多 2 步

[ ] 若设置了 nextTour，必须与另一个 tour 的 title 完全一致

用户角色 (Personas)

| 角色 | 目标 | 必须覆盖 |
|---------|------|------------|
| Vibecoder | 快速感知氛围 | 入口点，主模块。最多 8 步。 |
| New joiner (新入职者) | 结构化上手 | 目录结构，环境搭建，业务背景 |
| Bug fixer (缺陷修复者) | 快速定位根因 | 触发点 $\rightarrow$ 故障点 $\rightarrow$ 测试用例 |
| RCA investigator (根因分析员) | 分析失败原因 | 因果链，可观测性锚点 |
| Feature explainer (功能讲解员) | 端到端流程 | UI $\rightarrow$ API $\rightarrow$ 后端 $\rightarrow$ 存储 |
| PR reviewer (PR 评审员) | 正确地评审 | 变更逻辑，不变式，高风险区域 |
| Architect (架构师) | 整体形态与设计初衷 | 边界，权衡，扩展点 |
| Security reviewer (安全评审员) | 信任边界 | 认证流，校验，密钥处理 |
| Refactorer (重构者) | 安全地重构 | 接缝，隐藏依赖，提取顺序 |
| External contributor (外部贡献者) | 安全地贡献 | 安全区域，规范，潜在坑点 |

叙事弧线 (Narrative Arc)

1. 方向引导 (Orientation) —— file 或 directory 步骤（第一步绝不能是纯内容，否则在 VS Code 中显示为空白）
2. 高层地图 (High-level map) —— 1-3 个目录步骤，展示主要模块
3. 核心路径 (Core path) —— 文件/行步骤，tour 的核心部分
4. 收尾 (Closing) —— 读者现在可以做什么，建议的后续操作

反模式 (Anti-Patterns)

| 反模式 | 修复方案 |
|---|---|
| 文件清单 —— “此文件包含模型” | 讲述一个故事。每一步都应依赖于前一步。 |
| 泛泛而谈的描述 | 指出该代码库特有的具体模式。 |
| 猜测行号 | 绝不要写未经阅读验证的行号。 |
| 步骤过多 (导致无法快速深入) | 真正地删减步骤。 |
| 幻觉文件 | 如果文件不存在，直接跳过该步骤。 |
| 总结式收尾 —— “我们涵盖了 X, Y, Z” | 告诉读者他们现在可以 *做什么*。 |
| 纯内容第一步 | 将第一步锚定到文件或目录。 |

交叉引用

相关：engineering/codebase-onboarding —— 涵盖 tour 之外的更广泛的入职引导

相关：engineering/pr-review-expert —— 用于自动化 PR 评审工作流

CodeTour 扩展：microsoft/codetour

实际案例：coder/code-server