AI Skills
code-tour

code-tour

热门

创建 CodeTour `.tour` 文件——针对特定角色的分步式代码导览，包含真实的文件和行号锚点。适用于入职导览、架构讲解、PR 导览、RCA 导览以及结构化的“解释这是如何工作的”请求。

23万Star
3.5万Fork
更新于 2026/7/21
获取 Skill源代码

相关 Skills

planning-with-files-es2.5万herdr2.4万herdr1.7万
SKILL.md
readonly只读
name
code-tour
description

创建 CodeTour `.tour` 文件——针对特定角色的分步式代码导览，包含真实的文件和行号锚点。适用于入职导览、架构讲解、PR 导览、RCA 导览以及结构化的“解释这是如何工作的”请求。

Code Tour

创建 CodeTour .tour 文件，用于代码库导览，可直接打开真实文件并定位到行范围。导览文件存放在 .tours/ 目录下，专为 CodeTour 格式设计，而非临时性的 Markdown 笔记。

一个好的导览是为特定读者讲述一个故事：

  • 他们正在看什么
  • 为什么重要
  • 接下来应该遵循什么路径

仅创建 .tour JSON 文件。不要在此技能中修改源代码。

何时使用

在以下情况下使用此技能：

  • 用户请求代码导览、入职导览、架构讲解或 PR 导览
  • 用户说“解释 X 是如何工作的”，并希望得到一个可重用的引导式产物
  • 用户希望为新工程师或审查者提供一条上手路径
  • 任务更适合通过引导式序列而非平面摘要来完成

示例：

  • 新维护者入职
  • 单个服务或包的架构导览
  • 锚定到变更文件的 PR 审查导览
  • 展示失败路径的 RCA 导览
  • 信任边界和关键检查的安全审查导览

何时不使用

代替 code-tour 使用
在聊天中一次性解释就足够了 直接回答
用户想要散文式文档，而不是 .tour 产物 documentation-lookup 或仓库文档编辑
任务是实现或重构 执行实现工作
任务是没有导览产物的广泛代码库入职 codebase-onboarding

工作流程

1. 探索

在编写任何内容之前先探索仓库：

  • README 和包/应用入口点
  • 文件夹结构
  • 相关配置文件
  • 如果导览是 PR 导向的，则查看变更的文件

在理解代码结构之前，不要开始编写步骤。

2. 推断读者

根据请求决定角色和深度。

请求形式 角色 建议步骤数
“入职”、“新成员” new-joiner 9-13 步
“快速导览”、“快速了解” vibecoder 5-8 步
“架构” architect 14-18 步
“导览这个 PR” pr-reviewer 7-11 步
“为什么这个坏了” rca-investigator 7-11 步
“安全审查” security-reviewer 7-11 步
“解释这个功能如何工作” feature-explainer 7-11 步
“调试这个路径” bug-fixer 7-11 步

3. 读取并验证锚点

每个文件路径和行锚点必须是真实的：

  • 确认文件存在
  • 确认行号在范围内
  • 如果使用选区，验证确切的代码块
  • 如果文件易变，优先使用模式锚点

永远不要猜测行号。

4. 编写 .tour

写入：

.tours/<角色>-<焦点>.tour

保持路径确定且可读。

5. 验证

在完成之前：

  • 每个引用的路径都存在
  • 每一行或选区都有效
  • 第一步锚定到一个真实文件或目录
  • ref 指向一个分支或提交，该分支或提交确实包含导览引用的所有文件（见下文）
  • 导览讲述一个连贯的故事，而不是列出文件

ref 字段

ref 将导览绑定到一个 git 分支或提交。它比看起来更重要：当 ref 不是读者检出的分支时，CodeTour 会从该修订版本中打开每个步骤的文件，而不是从磁盘上的文件。如果文件不在该修订版本中，步骤将无法打开——读者会看到“编辑器无法打开，因为找不到文件”，即使文件就在那里。导览及其注释仍然显示，因此真正的原因很容易被忽略。

根据导览类型选择 ref：

导览类型 将 ref 设置为
PR 导览 PR 分支——永远不要设置为基础分支
入职/架构导览 读者将检出的分支（通常是 main），或者省略
不确定 省略 ref，这样 CodeTour 直接从磁盘读取文件

PR 情况是常见的陷阱：PR 通常会添加新文件，而新文件在基础分支上还不存在。将 ref 指向基础分支（例如 develop），那么每个在新文件上的步骤都无法打开。

在完成之前，确认每个步骤的文件在你选择的 ref 上确实存在。

步骤类型

内容

谨慎使用，通常仅用于结束步骤：

{ "title": "下一步", "description": "你现在可以端到端地追踪请求路径了。" }

不要将第一步设为仅内容。

目录

用于引导读者了解模块：

{ "directory": "src/services", "title": "服务层", "description": "核心编排逻辑位于此处。" }

文件 + 行

这是默认的步骤类型：

{ "file": "src/auth/middleware.ts", "line": 42, "title": "认证门禁", "description": "每个受保护的请求首先经过这里。" }

选区

当某个代码块比整个文件更重要时使用：

{
  "file": "src/core/pipeline.ts",
  "selection": {
    "start": { "line": 15, "character": 0 },
    "end": { "line": 34, "character": 0 }
  },
  "title": "请求管道",
  "description": "此代码块连接了验证、认证和下游执行。"
}

模式

当精确行号可能变化时使用：

{ "file": "src/app.ts", "pattern": "export default class App", "title": "应用入口" }

URI

在需要时用于 PR、问题或文档：

{ "uri": "https://github.com/org/repo/pull/456", "title": "该 PR" }

编写规则：SMIG

每个描述应回答：

  • 情境：读者正在看什么
  • 机制：它是如何工作的
  • 影响：为什么对这个角色重要
  • 陷阱：聪明的读者可能会错过什么

保持描述简洁、具体，并基于实际代码。

叙事结构

除非任务明确需要不同结构，否则使用以下弧线：

  1. 定位
  2. 模块地图
  3. 核心执行路径
  4. 边界情况或陷阱
  5. 结束/下一步行动

导览应该感觉像一条路径，而不是一份清单。

示例

{
  "$schema": "https://aka.ms/codetour-schema",
  "title": "API 服务导览",
  "description": "支付服务请求路径的讲解。",
  "ref": "main",
  "steps": [
    {
      "directory": "src",
      "title": "源码根目录",
      "description": "服务的所有运行时代码从这里开始。"
    },
    {
      "file": "src/server.ts",
      "line": 12,
      "title": "入口点",
      "description": "服务器在此启动，并在到达任何路由之前连接中间件。"
    },
    {
      "file": "src/routes/payments.ts",
      "line": 8,
      "title": "支付路由",
      "description": "所有支付请求在进入服务逻辑之前先经过此路由器。"
    },
    {
      "title": "下一步",
      "description": "现在你可以借助主要锚点端到端地追踪任何支付请求。"
    }
  ]
}

反模式

反模式 修复
平面文件列表 讲述一个步骤间有依赖关系的故事
通用描述 命名具体的代码路径或模式
猜测的锚点 首先验证每个文件和行
快速导览步骤过多 大幅削减
第一步仅内容 将第一步锚定到真实文件或目录
角色不匹配 为实际读者编写，而不是泛泛的工程师

最佳实践

  • 步骤数与仓库大小和角色深度成比例
  • 使用目录步骤进行定位，文件步骤进行实质性内容
  • 对于 PR 导览，首先覆盖变更的文件
  • 对于单体仓库，将范围限定到相关包，而不是导览所有内容
  • 以读者现在可以做什么来结束，而不是总结

相关技能

  • codebase-onboarding
  • coding-standards
  • council
  • 官方上游格式：microsoft/codetour