code-tour

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Code Tour

CodeTour

Create CodeTour
.tour
files for codebase walkthroughs that open directly to real files and line ranges. Tours live in
.tours/
and are meant for the CodeTour format, not ad hoc Markdown notes.
A good tour is a narrative for a specific reader:
  • what they are looking at
  • why it matters
  • what path they should follow next
Only create
.tour
JSON files. Do not modify source code as part of this skill.
创建 CodeTour
.tour
文件用于代码库导览,可直接打开定位到真实文件和行范围。导览文件存放在
.tours/
目录下,遵循 CodeTour 格式,而非临时编写的 Markdown 笔记。
一份优质的导览是面向特定读者的叙事内容:
  • 他们当前查看的内容是什么
  • 该内容的重要性
  • 他们后续应该遵循的路径
仅创建
.tour
格式的 JSON 文件,不要将修改源代码作为本 Skill 的一部分。

When to Use

适用场景

Use this skill when:
  • the user asks for a code tour, onboarding tour, architecture walkthrough, or PR tour
  • the user says "explain how X works" and wants a reusable guided artifact
  • the user wants a ramp-up path for a new engineer or reviewer
  • the task is better served by a guided sequence than a flat summary
Examples:
  • onboarding a new maintainer
  • architecture tour for one service or package
  • PR-review walk-through anchored to changed files
  • RCA tour showing the failure path
  • security review tour of trust boundaries and key checks
在以下场景使用本 Skill:
  • 用户请求生成代码导览、入职导览、架构讲解或 PR 导览
  • 用户提出「解释X的运行原理」且需要可复用的引导产物
  • 用户需要为新工程师或评审人提供上手路径
  • 相比平铺直叙的总结,引导式序列更适合完成当前任务
示例:
  • 新维护者入职引导
  • 单个服务或包的架构导览
  • 锚定到变更文件的 PR 评审导览
  • 展示错误路径的 RCA 导览
  • 覆盖信任边界和关键校验的安全评审导览

When NOT to Use

不适用场景

Instead of code-tourUse
A one-off explanation in chat is enoughanswer directly
The user wants prose docs, not a
.tour
artifact
documentation-lookup
or repo docs editing
The task is implementation or refactoringdo the implementation work
The task is broad codebase onboarding without a tour artifact
codebase-onboarding
不适合使用 code-tour 的场景替代方案
仅需要在聊天中给出一次性解释直接回答
用户需要文档内容,而非
.tour
产物
documentation-lookup
或仓库文档编辑
任务为功能实现或重构直接完成实现工作
任务为通用代码库入职,不需要生成导览产物
codebase-onboarding

Workflow

工作流

1. Discover

1. 信息调研

Explore the repo before writing anything:
  • README and package/app entry points
  • folder structure
  • relevant config files
  • the changed files if the tour is PR-focused
Do not start writing steps before you understand the shape of the code.
编写任何内容前先探索仓库:
  • README 和包/应用的入口文件
  • 文件夹结构
  • 相关配置文件
  • 如果是 PR 导向的导览,先查看变更文件
在理解代码结构之前不要开始编写步骤。

2. Infer the reader

2. 推断读者画像

Decide the persona and depth from the request.
Request shapePersonaSuggested depth
"onboarding", "new joiner"
new-joiner
9-13 steps
"quick tour", "vibe check"
vibecoder
5-8 steps
"architecture"
architect
14-18 steps
"tour this PR"
pr-reviewer
7-11 steps
"why did this break"
rca-investigator
7-11 steps
"security review"
security-reviewer
7-11 steps
"explain how this feature works"
feature-explainer
7-11 steps
"debug this path"
bug-fixer
7-11 steps
根据请求确定面向的角色和内容深度:
请求类型角色建议步骤数
"onboarding"、"new joiner"
new-joiner
(新入职者)
9-13 步
"quick tour"、"vibe check"
vibecoder
(快速了解者)
5-8 步
"architecture"
architect
(架构师)
14-18 步
"tour this PR"
pr-reviewer
(PR 评审者)
7-11 步
"why did this break"
rca-investigator
(RCA 调研者)
7-11 步
"security review"
security-reviewer
(安全评审者)
7-11 步
"explain how this feature works"
feature-explainer
(功能讲解受众)
7-11 步
"debug this path"
bug-fixer
(问题修复者)
7-11 步

3. Read and verify anchors

3. 读取并校验锚点

Every file path and line anchor must be real:
  • confirm the file exists
  • confirm the line numbers are in range
  • if using a selection, verify the exact block
  • if the file is volatile, prefer a pattern-based anchor
Never guess line numbers.
每个文件路径和行号锚点必须真实存在:
  • 确认文件存在
  • 确认行号在有效范围内
  • 如果使用选中范围,校验具体的代码块
  • 如果文件变动频繁,优先使用基于模式的锚点
绝对不要猜测行号。

4. Write the
.tour

4. 编写
.tour
文件

Write to:
text
.tours/<persona>-<focus>.tour
Keep the path deterministic and readable.
写入路径:
text
.tours/<persona>-<focus>.tour
保持路径确定性强且可读性高。

5. Validate

5. 校验

Before finishing:
  • every referenced path exists
  • every line or selection is valid
  • the first step is anchored to a real file or directory
  • the tour tells a coherent story rather than listing files
完成前确认:
  • 所有引用的路径都存在
  • 所有行号或选中范围都有效
  • 第一步锚定到真实的文件或目录
  • 导览是连贯的叙事,而非单纯的文件列表

Step Types

步骤类型

Content

纯内容

Use sparingly, usually only for a closing step:
json
{ "title": "Next Steps", "description": "You can now trace the request path end to end." }
Do not make the first step content-only.
谨慎使用,通常仅用于收尾步骤:
json
{ "title": "后续步骤", "description": "你现在已经可以端到端追踪请求路径了。" }
不要把第一步设置为纯内容类型。

Directory

目录

Use to orient the reader to a module:
json
{ "directory": "src/services", "title": "Service Layer", "description": "The core orchestration logic lives here." }
用于帮助读者熟悉模块结构:
json
{ "directory": "src/services", "title": "服务层", "description": "核心编排逻辑存放在这里。" }

File + line

文件+行号

This is the default step type:
json
{ "file": "src/auth/middleware.ts", "line": 42, "title": "Auth Gate", "description": "Every protected request passes here first." }
这是默认的步骤类型:
json
{ "file": "src/auth/middleware.ts", "line": 42, "title": "鉴权网关", "description": "所有受保护的请求都会先经过这里。" }

Selection

选中范围

Use when one code block matters more than the whole file:
json
{
  "file": "src/core/pipeline.ts",
  "selection": {
    "start": { "line": 15, "character": 0 },
    "end": { "line": 34, "character": 0 }
  },
  "title": "Request Pipeline",
  "description": "This block wires validation, auth, and downstream execution."
}
当某个代码块比整个文件更重要时使用:
json
{
  "file": "src/core/pipeline.ts",
  "selection": {
    "start": { "line": 15, "character": 0 },
    "end": { "line": 34, "character": 0 }
  },
  "title": "请求流水线",
  "description": "这个块实现了校验、鉴权和下游执行的串联。"
}

Pattern

模式匹配

Use when exact lines may drift:
json
{ "file": "src/app.ts", "pattern": "export default class App", "title": "Application Entry" }
当准确行号可能变动时使用:
json
{ "file": "src/app.ts", "pattern": "export default class App", "title": "应用入口" }

URI

URI

Use for PRs, issues, or docs when helpful:
json
{ "uri": "https://github.com/org/repo/pull/456", "title": "The PR" }
需要关联 PR、Issue 或文档时使用:
json
{ "uri": "https://github.com/org/repo/pull/456", "title": "对应PR" }

Writing Rule: SMIG

编写规则:SMIG

Each description should answer:
  • Situation: what the reader is looking at
  • Mechanism: how it works
  • Implication: why it matters for this persona
  • Gotcha: what a smart reader might miss
Keep descriptions compact, specific, and grounded in the actual code.
每个步骤的描述需要回答以下问题:
  • Situation(场景):读者当前查看的内容是什么
  • Mechanism(机制):它的运行原理是什么
  • Implication(意义):对当前角色来说它的重要性是什么
  • Gotcha(注意点):聪明的读者可能会忽略的细节是什么
保持描述简洁、具体,并且基于实际代码。

Narrative Shape

叙事结构

Use this arc unless the task clearly needs something different:
  1. orientation
  2. module map
  3. core execution path
  4. edge case or gotcha
  5. closing / next move
The tour should feel like a path, not an inventory.
除非任务明确要求其他结构,否则遵循以下叙事弧:
  1. 整体定位
  2. 模块映射
  3. 核心执行路径
  4. 边缘 case 或注意点
  5. 收尾/后续动作
导览应该像一条路径,而不是一份清单。

Example

示例

json
{
  "$schema": "https://aka.ms/codetour-schema",
  "title": "API Service Tour",
  "description": "Walkthrough of the request path for the payments service.",
  "ref": "main",
  "steps": [
    {
      "directory": "src",
      "title": "Source Root",
      "description": "All runtime code for the service starts here."
    },
    {
      "file": "src/server.ts",
      "line": 12,
      "title": "Entry Point",
      "description": "The server boots here and wires middleware before any route is reached."
    },
    {
      "file": "src/routes/payments.ts",
      "line": 8,
      "title": "Payment Routes",
      "description": "Every payments request enters through this router before hitting service logic."
    },
    {
      "title": "Next Steps",
      "description": "You can now follow any payment request end to end with the main anchors in place."
    }
  ]
}
json
{
  "$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": "现在你已经掌握了核心锚点,可以端到端跟踪任意支付请求了。"
    }
  ]
}

Anti-Patterns

反模式

Anti-patternFix
Flat file listingTell a story with dependency between steps
Generic descriptionsName the concrete code path or pattern
Guessed anchorsVerify every file and line first
Too many steps for a quick tourCut aggressively
First step is content-onlyAnchor the first step to a real file or directory
Persona mismatchWrite for the actual reader, not a generic engineer
反模式修复方案
平铺的文件列表打造有步骤依赖关系的叙事
通用化描述明确指出具体的代码路径或模式
猜测的锚点先校验所有文件和行号
快速导览步骤过多大幅精简内容
第一步是纯内容将第一步锚定到真实的文件或目录
角色不匹配面向真实读者而非通用工程师编写

Best Practices

最佳实践

  • keep step count proportional to repo size and persona depth
  • use directory steps for orientation, file steps for substance
  • for PR tours, cover changed files first
  • for monorepos, scope to the relevant packages instead of touring everything
  • close with what the reader can now do, not a recap
  • 步骤数量和仓库规模、角色要求的深度匹配
  • 用目录步骤做定位,用文件步骤做实质讲解
  • PR 导览优先覆盖变更文件
  • monorepo 场景下限定在相关包范围内,不要导览所有内容
  • 收尾说明读者现在可以完成的操作,而非重复总结

Related Skills

相关 Skill

  • codebase-onboarding
  • coding-standards
  • council
  • official upstream format:
    microsoft/codetour
  • codebase-onboarding
  • coding-standards
  • council
  • 官方上游格式:
    microsoft/codetour