code-tour
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
ChineseCode Tour
CodeTour
Create CodeTour files for codebase walkthroughs that open directly to real files and line ranges. Tours live in and are meant for the CodeTour format, not ad hoc Markdown notes.
.tour.tours/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 JSON files. Do not modify source code as part of this skill.
.tour创建 CodeTour 文件用于代码库导览,可直接打开定位到真实文件和行范围。导览文件存放在 目录下,遵循 CodeTour 格式,而非临时编写的 Markdown 笔记。
.tour.tours/一份优质的导览是面向特定读者的叙事内容:
- 他们当前查看的内容是什么
- 该内容的重要性
- 他们后续应该遵循的路径
仅创建 格式的 JSON 文件,不要将修改源代码作为本 Skill 的一部分。
.tourWhen 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-tour | Use |
|---|---|
| A one-off explanation in chat is enough | answer directly |
The user wants prose docs, not a | |
| The task is implementation or refactoring | do the implementation work |
| The task is broad codebase onboarding without a tour artifact | |
| 不适合使用 code-tour 的场景 | 替代方案 |
|---|---|
| 仅需要在聊天中给出一次性解释 | 直接回答 |
用户需要文档内容,而非 | |
| 任务为功能实现或重构 | 直接完成实现工作 |
| 任务为通用代码库入职,不需要生成导览产物 | |
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 shape | Persona | Suggested depth |
|---|---|---|
| "onboarding", "new joiner" | | 9-13 steps |
| "quick tour", "vibe check" | | 5-8 steps |
| "architecture" | | 14-18 steps |
| "tour this PR" | | 7-11 steps |
| "why did this break" | | 7-11 steps |
| "security review" | | 7-11 steps |
| "explain how this feature works" | | 7-11 steps |
| "debug this path" | | 7-11 steps |
根据请求确定面向的角色和内容深度:
| 请求类型 | 角色 | 建议步骤数 |
|---|---|---|
| "onboarding"、"new joiner" | | 9-13 步 |
| "quick tour"、"vibe check" | | 5-8 步 |
| "architecture" | | 14-18 步 |
| "tour this PR" | | 7-11 步 |
| "why did this break" | | 7-11 步 |
| "security review" | | 7-11 步 |
| "explain how this feature works" | | 7-11 步 |
| "debug this path" | | 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
.tour4. 编写 .tour
文件
.tourWrite to:
text
.tours/<persona>-<focus>.tourKeep 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:
- orientation
- module map
- core execution path
- edge case or gotcha
- closing / next move
The tour should feel like a path, not an inventory.
除非任务明确要求其他结构,否则遵循以下叙事弧:
- 整体定位
- 模块映射
- 核心执行路径
- 边缘 case 或注意点
- 收尾/后续动作
导览应该像一条路径,而不是一份清单。
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-pattern | Fix |
|---|---|
| Flat file listing | Tell a story with dependency between steps |
| Generic descriptions | Name the concrete code path or pattern |
| Guessed anchors | Verify every file and line first |
| Too many steps for a quick tour | Cut aggressively |
| First step is content-only | Anchor the first step to a real file or directory |
| Persona mismatch | Write 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-onboardingcoding-standardscouncil- official upstream format:
microsoft/codetour
codebase-onboardingcoding-standardscouncil- 官方上游格式:
microsoft/codetour