Codetour Authoring

何时使用

当一段走读用「带锚点的引导序列」比「平铺摘要」更有价值时使用。产物是 .tours/ 下的 CodeTour .tour（JSON）文件——能在 VS Code CodeTour 插件里直接打开到真实文件和行范围，而不是临时的 Markdown 笔记。

一份好导览是为特定读者讲的故事：他们在看什么、为什么重要、接下来该走哪条路。

典型场景：

• 新维护者/新工程师入职引导；
• 单个服务或包的架构走读；
• 锚定到变更文件的 PR 审查导览；
• 展示故障路径的 RCA（根因分析）导览；
• 围绕信任边界与关键检查的安全审查导览。

不该用边界：

硬约束：只创建 .tour JSON 文件，本技能范围内不修改任何源代码。

步骤

1. 探索（动笔前必做）

写任何步骤前先摸清代码形状：README 与包/应用入口、目录结构、相关配置文件；若导览聚焦 PR，则先看变更文件。没理解代码结构前不要开始写步骤。

2. 推断读者（定角色与深度）

由请求形态决定 persona 和步数：

3. 读取并验证锚点

每个文件路径和行锚点都必须真实：确认文件存在、确认行号在范围内、用 selection 时核对确切代码块；文件易变时优先用 pattern 锚点。绝不猜测行号。

4. 写 .tour

路径保持确定、可读：

.tours/<persona>-<focus>.tour

5. 验证（收尾前）

• 每个引用路径都存在；
• 每个行号/选区都有效；
• 第一步锚定到真实文件或目录（不能是纯内容步骤）；
• 导览讲的是一条连贯路径，而非文件清单。

指令

步骤类型（steps[]）

• 内容（content）——谨慎使用，通常只用于收尾步。第一步不可为纯内容。

  { "title": "Next Steps", "description": "You can now trace the request path end to end." }
  

• 目录（directory）——给读者定位某个模块：

  { "directory": "src/services", "title": "Service Layer", "description": "The core orchestration logic lives here." }
  

• 文件 + 行（file + line）——默认步骤类型：

  { "file": "src/auth/middleware.ts", "line": 42, "title": "Auth Gate", "description": "Every protected request passes here first." }
  

• 选区（selection）——当某代码块比整文件更关键：

  { "file": "src/core/pipeline.ts", "selection": { "start": { "line": 15, "character": 0 }, "end": { "line": 34, "character": 0 } }, "title": "Request Pipeline" }
  

• 模式（pattern）——当精确行号可能漂移：

  { "file": "src/app.ts", "pattern": "export default class App", "title": "Application Entry" }
  

• URI——指向 PR / issue / 文档：

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

写描述的规则：SMIG

每条 description 应回答四点，并保持简洁、具体、贴合真实代码：

• Situation 情境：读者在看什么；
• Mechanism 机制：它如何工作；
• Implication 影响：为什么对这个角色重要；
• Gotcha 陷阱：聪明的读者可能会忽略什么。

叙事弧（除非任务另有需要）

1. 定位 → 2. 模块地图 → 3. 核心执行路径 → 4. 边缘情况/陷阱 → 5. 收尾/下一步。导览应像一条路径，而非一份清单。

反模式与修复

示例

一份最小可用的 .tour（payments 服务请求路径走读）：

{
  "$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." }
  ]
}

注意事项

• 只产出 .tour，不碰源码——本技能不实现、不重构、不改业务文件。
• 步数与规模匹配：步数随仓库大小与角色深度成比例；用 directory 步做定位、file 步做实质内容。
• PR 导览先覆盖变更文件；单体仓库（monorepo）只圈相关包，不要导览全部。
• 收尾讲「读者现在能做什么」，而不是复述刚才看了啥。
• 行号易漂移的文件优先用 pattern；用 line/selection 时务必先核对，绝不臆造行号。
• 缺关键输入（导览主题/焦点、目标读者、是否锚定某 PR）时先停下澄清。

互见

• related：docs-architect —— 需要散文式架构叙事/设计决策（讲「为什么」）而非可点击导览产物时改用它。
• related：readme-doc-writer —— 项目级 README/快速上手与导览的「定位」步骤互补。
• related：code-tutorial-engineer —— 要「教人动手做」的循序渐进教程，而非「带读已有代码」时改用它。
• combines_with：codebase-onboarding-doc —— 宽泛入职文档 + 一份引导式 .tour，覆盖「读文档」与「跟着走读」两种上手方式。

采编自 affaan-m/everything-claude-code（MIT），适配重写，非逐字翻译。