code-tour

code-tour 技能概览

code-tour 技能是做什么的

code-tour 技能会创建可复用的 CodeTour .tour 文件，使用真实的文件路径和行号范围，带读者按顺序浏览一个仓库。它不是一次性的聊天式讲解，而是生成一个存放在 .tours/ 中的工件，可在兼容 CodeTour 的工具里作为引导式流程打开。

最适合的用户与使用场景

这个 code-tour 技能适合维护者、审阅者和技术写作者，他们需要一条结构化的代码阅读路径：入门导览、架构导览、PR 走查、RCA 追踪或安全审查路径。真正要完成的工作不是“总结仓库”，而是“按正确顺序带特定读者看对文件”。

为什么选择 code-tour 而不是通用提示词

通用提示词通常只会返回与代码脱节的文字说明。code-tour 的范围更窄，但在你需要稳定导航时更有用：每一步都指向真实的文件和行区间，同时带有叙述上下文和下一步衔接。这让它在 code-tour for Technical Writing、入门培训和可重复审查流程里尤其强。

安装前的关键限制

code-tour 技能只会创建 .tour JSON 文件；它不是用来修改源代码、重写大段文档或做随意问答的。它最适合仓库已经有清晰文件结构、并且请求范围明确到某个服务、功能、事故路径或 PR diff，而不是“解释整个仓库”。

如何使用 code-tour 技能

安装上下文以及先读什么

先按你平时的 skills 工作流安装父级 skills 仓库，然后在那个环境里调用 code-tour。在这个技能目录中，SKILL.md 是唯一的源文件，所以要先读它。这里没有辅助脚本或额外参考文件，这意味着上手很直接，但你必须自己提供足够好的仓库上下文。

code-tour 技能需要什么输入

要把 code-tour 用好，最好提供：

• 受众：new backend engineer、security reviewer、technical writer
• 目标：入门、架构、PR review、RCA、信任边界审查
• 范围：包、服务、功能或变更文件
• 输出目标：.tours/<name>.tour
• 仓库锚点：关键文件、入口点、模块或 commit/PR 背景

弱请求是：“给我做一个这个仓库的导览。”
更强的请求是：“为 Technical Writing 创建一个 code-tour，说明 auth 请求如何经过 src/server.ts、中间件、token 校验和 session 存储。控制在 8–10 个停靠点，并优化给新入职的文档作者。”

把粗略目标变成可用提示词

一个好的 code-tour 提示词应该明确读者、路径和排除项。比如：

• “为 billing service 的新维护者创建一个 code-tour 入门导览。”
• “每个停靠点都要锚定到真实文件和行号范围。”
• “从请求入口开始，然后是配置加载、领域逻辑、持久化和测试。”
• “避开无关的管理工具。”
• “写简洁的步骤说明，解释这个文件为什么重要，以及下一步该看哪里。”

这样能帮助技能优先组织顺序，而不是简单罗列内容。没有这种框架，导览往往会变成平铺直叙的文件清单。

实用工作流与输出检查

建议的工作流：

1. 先确定读者和具体问题。
2. 检查仓库里的入口点、核心模块和配套测试。
3. 按系统实际被理解的方式，拟定停靠点顺序。
4. 在 .tours/ 里生成 .tour 文件。
5. 校验每个文件路径和行号锚点。
6. 打开导览并删掉薄弱的停靠点。

真正重要的质量检查包括：

• 每个停靠点都有明确存在理由
• 顺序讲的是一个故事，而不是一串列表
• 行号锚点指向有意义的代码，而不是 import 区块
• 导览最后要有“下一步该看什么”或一个归纳步骤

code-tour 技能 FAQ

code-tour 适合初学者吗？

适合，但前提是范围要窄。初学者最能从单一流程、单个服务或单个 PR 的导览中受益。仓库级别的 code-tour 往往会让他们信息过载。如果你在带新人，最好让导览覆盖主执行路径，再加 1–2 个支撑文件。

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

当读者需要按文件逐个导航、并且要和源代码绑定时，用 code-tour。需要概念总览、产品行为说明或长篇说明时，用普通文档。对于技术写作团队来说，code-tour 最适合作为源代码引导型补充，而不是 polished docs 的替代品。

code-tour 技能的主要限制是什么？

它不会实现功能、重构代码，也不会写大规模文档集。它还依赖稳定的文件路径和有意义的代码结构。如果仓库混乱、生成式产物很多，或者命名很差，这个技能仍然能生成导览，但结果通常需要更重的人工审阅。

什么时候不适合用？

如果在聊天里快速回答就够了，如果用户想要的是 Markdown 文档而不是 .tour 工件，或者请求范围太大、很难排出合理顺序，那就不要用 code-tour。没有清晰受众时也不太适合；一旦知道导览是给谁看的，效果会明显更好。

如何改进 code-tour 技能

给出更强的仓库阅读指引

提升质量最大的办法，是在生成前先给出一条发现路径。告诉技能从哪里开始：入口点、路由、处理器、核心服务、测试和配置。如果相关，还可以附上 PR diff 或事故记录。锚点越好，导览质量通常越高。

预防常见的 code-tour 失败模式

常见的低质量输出包括：

• 停靠点过多
• 停靠在不重要的行上
• 只有泛泛而谈的评论，换个仓库也能用
• 没有明确受众
• 步骤之间没有叙事过渡

要避免这些问题，可以设定停靠点预算、明确读者，并要求每一步都写出“这为什么重要”以及“下一步看什么”。

结合受众和意图优化提示词

如果是面向 Technical Writing 的 code-tour，要求它说明术语、边界定义和适合写进文档的概念。做 PR review 时，要求按变更文件顺序组织，并标出风险热点。做入门导览时，要求以架构优先排序，把测试放到最后。同一个仓库，不同提示词，导览质量会非常不同。

在第一版之后继续迭代

把第一版输出当作地图，而不是最终成品。打开 .tour，删掉重复停靠点，收紧行号范围，并在末尾加一个归纳停靠点。如果导览看起来像目录清单，就缩小范围再生成。最好的 code-tour 技能结果，来自一次有针对性的修订，而不是一开始就铺得很宽。