code-tour

name	code-tour
description	创建 CodeTour `.tour` 文件 — 面向特定角色的分步导览，带有真实文件和行号锚点。用于入职导览、架构导览、PR 导览、RCA 导览和结构化的"解释其工作原理"请求。
origin	ECC

Code Tour

创建 CodeTour .tour 文件用于代码库导览，直接打开到真实文件和行范围。导览文件存放在 .tours/ 中，采用 CodeTour 格式，而非临时的 Markdown 笔记。

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

• 他们正在看什么
• 为什么重要
• 他们接下来应该跟随的路径

仅创建 .tour JSON 文件。不要将修改源代码作为此技能的一部分。

何时使用

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

• 用户请求代码导览、入职导览、架构导览或 PR 导览
• 用户说"解释 X 的工作原理"并希望获得可复用的导览制品
• 用户希望为新工程师或审查者提供入门路径
• 任务更适合通过引导序列而非平面摘要来完成

示例：

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

何时不使用

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

工作流

1. 探索

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

• README 和 package/app 入口点
• 文件夹结构
• 相关配置文件
• 如果导览针对 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/<persona>-<focus>.tour

保持路径确定性和可读性。

5. 验证

完成前：

• 每个引用的路径都存在
• 每个行号或选区都有效
• 第一步锚定到真实文件或目录
• 导览讲述了一个连贯的故事而非列举文件

步骤类型

内容

谨慎使用，通常只用于收尾步骤：

{ "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

每段描述应回答：

• 场景（Situation）：读者正在看什么
• 机制（Mechanism）：它是如何工作的
• 影响（Implication）：为什么对这一角色重要
• 陷阱（Gotcha）：聪明的读者可能遗漏什么

保持描述紧凑、具体，并立足于实际代码。

叙事结构

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

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",
       
       
       
    
    
       
       
    
  

反模式

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

最佳实践

• 保持步骤数量与仓库大小和角色深度成比例
• 使用目录步骤进行定位，文件步骤用于实质内容
• 对于 PR 导览，优先覆盖变更文件
• 对于单体仓库，限定到相关包而非导览所有内容
• 以读者现在可以做什么来收尾，而非总结回顾

相关技能

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