code-tour

code-tour skill 概览

code-tour 会生成什么

code-tour skill 可帮助 AI agent 为 VS Code CodeTour extension 生成 CodeTour .tour JSON 文件。一个 tour 是一条带引导的代码 walkthrough，会把说明步骤关联到真实文件和行号，通常存放在 .tours/ 目录下。这个 skill 面向结构化的代码仓库探索，而不是代码编辑：它的核心边界是只创建 tour 文件，并避免修改源代码。

最适合 Technical Writing 和新人上手

当你需要为 Technical Writing 制作入门路径、贡献者指南、架构 walkthrough、PR review tour、安全审查路径、根因分析线索，或“解释这套机制如何工作”的代码导览时，可以使用 code-tour。当读者画像足够明确时，它的效果最好：比如新加入的后端工程师、前端维护者、reviewer、incident responder、staff engineer，或需要按策划路径理解实现细节的非代码利益相关方。

为什么它比普通 prompt 更有用

普通 prompt 可能只是松散地概括文件内容。code-tour skill 会推动 agent 产出一个真正可用的交付物：面向特定读者画像的叙事步骤，并带有具体文件和行号锚点。这一点很重要，因为 tour 必须能在 VS Code 中导航，必须引用实际存在的路径，也必须说明每一站为什么重要，而不是简单倾倒一份目录摘要。有价值的输出不是“这个 repo 里有什么”，而是“这位读者应该先点哪里、下一步点哪里，以及为什么”。

安装前需要考虑的采用条件

这个 skill 只有聚焦的 SKILL.md，没有额外脚本、规则或参考资料包。这让 code-tour install 很轻量，但也意味着质量高度依赖仓库访问权限和 prompt 细节。它最适合 agent 能检查文件树、README、配置文件和源码入口点的场景。如果你只想要纯文字文档、Mermaid 图、源码修改，或者要为 agent 无法读取的文件创建 tour，那它并不合适。

如何使用 code-tour skill

code-tour install 与仓库上下文

使用你的 skills tooling 从源仓库安装，例如：

npx skills add alirezarezvani/claude-skills --skill code-tour

安装后，如有需要，可确认 skill 路径：engineering/code-tour/skills/code-tour/SKILL.md。在目标项目中，agent 应先检查根目录、README.md、package 或 build config，以及最上层一到两层目录，然后再开始起草。tour 应保存为 .tours/ 下的 .tour JSON 文件，并兼容 VS Code CodeTour extension。

这个 skill 需要哪些输入

要获得高质量的 code-tour usage，请提供五类信息：受众、目标、范围、期望深度，以及必须包含的文件或功能名。较弱的请求是：“make a tour of this repo。”更强的请求是：“Create a CodeTour for a new backend engineer explaining the request lifecycle for login, from route registration through validation, service logic, database access, and error handling. Keep it to 8–12 steps and anchor every step to real files and lines.”

如果这个 tour 用于 Technical Writing，请补充发布目的：新人 onboarding 文档、release note 支撑材料、内部架构指南、review 辅助材料，或 incident learning artifact。

第一次创建 tour 的推荐流程

先做发现，而不是直接写。让 agent 先识别项目用途、语言、框架、入口点和重要目录。然后选择一条叙事路径：从 setup 到第一个 feature、从 request 到 response、从 UI action 到 API、从 bug symptom 到 root cause，或从 PR diff 到 risk。只有在这些确定之后，才生成 .tour 文件。这样的顺序可以减少失效锚点，也能避免产出浅层的“folder tour”——只报目录名，却没有教会读者系统如何运作。

实用 prompt 模板

可以使用类似这样的 prompt：

“Use the code-tour skill to create .tours/auth-onboarding.tour. Audience: new full-stack engineer. Goal: understand authentication flow well enough to make a safe change. Scope: login, session creation, middleware, and tests only. Exclude unrelated account settings. Inspect the repo first, then produce a 10-step CodeTour with real file paths and line numbers. Each step should explain what the reader should notice and why it matters.”

这个写法有效，是因为它给了 agent 一个决策框架，而不只是一个主题。

code-tour skill 常见问题

什么时候该用 code-tour，而不是写文档？

当“在代码中导航”本身就是交付物时，使用 code-tour。传统文档更适合讲概念、政策或 API reference。CodeTour 更适合读者需要按顺序打开文件，并理解 routes、services、tests、configs 和 entry points 之间关系的场景。

初学者能使用 code-tour skill 吗？

可以，但初学者应该收紧请求范围。先要求一个小 tour：一个 feature、一条 bug path，或一个 architecture slice。像“explain the entire codebase”这种宽泛请求，除非仓库非常小，否则往往会生成噪音较多的 tour。对于源文件不到几个的小型仓库，一个快速但有一定深度的 tour 通常就够了。

code-tour 会修改我的应用代码吗？

不会。预期输出是一个 .tour JSON 文件，通常放在 .tours/ 中。这个 skill 的明确边界是避免修改源代码。如果你的 workflow 需要修代码、写测试或重构，请先使用其他 engineering skill，再用 code-tour 记录最终形成的路径。

什么会影响 code-tour 的产出质量？

最大的阻碍包括：缺少仓库访问权限、受众描述模糊、没有范围限制，以及文件路径未经验证。CodeTour 步骤依赖真实锚点。如果 agent 不能读取目标文件，或者在活跃编辑期间行号频繁变化，应等代码稳定后再生成 tour；也可以先要求路径级锚点，之后再细化行号。

如何改进 code-tour skill 的效果

让 code-tour prompt 明确读者画像

提升 code-tour 输出质量最快的方法，是明确点出读者是谁。“New contributor”会得到一条不同于“security reviewer”或“technical writer preparing onboarding material”的路径。请说明读者已经知道什么，以及看完 tour 后必须能够完成什么。这会改变步骤选择、解释深度和用词方式。

要叙事，不要清单

弱 tour 只是列文件。强 tour 会讲一条故事线：执行从哪里开始、数据如何流动、决策在哪里发生、风险藏在哪里，以及哪些测试证明了行为。要求 agent 把每一站与上一站连接起来，并在每一步加入一句“why this matters”。这对 Technical Writing 尤其有价值，因为最终交付物会变得可教学，而不只是可点击。

在第一版输出后迭代

拿到第一版 .tour 草稿后，重点检查三类问题：文件路径失效或不精确、步骤粒度过大、缺少过渡说明。然后提出有针对性的修改请求：“split step 4 into route and service steps”、“add the test that covers this behavior”，或“reduce frontend detail and focus on API error handling”。通常，迭代比一次性要求生成完美的全仓库 tour 更有效。

分享前验证锚点

发布 CodeTour 前，请在 VS Code 中打开它，并使用 CodeTour extension 确认每个路径和行号都能落到预期位置。如果仓库经常变化，优先选择绑定到稳定架构文件、tests 或 entry points 的 tour，并在大型重构后重新生成行号。这样才能让 code-tour skill 持续作为有效的 onboarding 资产，而不是一张过期地图。