code-distill

Code-Distill — GitHub 代码库的模式提取方法论

提炼 Agent 根据聚焦查询，从特定 GitHub 代码库中按需提取代码模式时所采用的通用方法论。这不是针对单个库的技能——只需一个技能，再加上共享知识图谱中的一条精简的库记录（/knowledge/libraries/），因为无论针对哪个仓库，90% 的工作都是相同的。

这是静态代码图谱提炼的动态轻量版：opencode-ts、openai-codex-rust-patterns、nextjs-ppr-patterns。这些技能是经过精心整理的重型产物——它们提前从单个仓库中提炼了模式。此技能则提供按需替代方案：如果该库还没有静态技能，就指定仓库并运行此方法论。

适用场景

在以下情况使用此技能：

• 用户询问“<library> 如何实现 <feature>？”，并指出（或说出）一个真实的 GitHub 仓库
• 查询聚焦于单个子系统（设计系统、组合、状态、错误处理、副作用、构建、路由），而不是“这个代码库整体是做什么的？”
• 该库尚无静态代码图谱技能（或现有技能已过时）
• 临时调用形式类似 /distill <library> <query>，或用自然语言提出“给我看看仓库 Y 中的 X”
• 该库的功能范围太小或生命周期太短，不值得编写完整的静态代码图谱提炼技能

以下情况不适用此技能：

• 已有静态代码图谱技能的库——优先使用 opencode-ts、openai-codex-rust-patterns、nextjs-ppr-patterns 或其他已发布的单库技能。它们速度更快（已经过整理），还纳入了此技能无法按需重新发现的失败案例经验。
• 完整代码库架构映射——如果问题是“从领域角度看，整个代码库做什么？”，请使用 codebase-comprehension-algorithms。该技能是重型算法工具集（Leiden、MoJoFM、SBM）；此技能则专注于从聚焦查询中提取信息。
• 编写完整的静态代码图谱技能——这项编写任务的方法论手册是另一项独立技能（尚未构建），是 library-reference-distillation 的代码源对应技能。如果你发现自己针对同一个库运行 code-distill 超过约 3 次，就该考虑升级为完整的静态技能。
• 查找文档——如果你想知道“在 <library> 的文档中哪里能找到 X？”，请使用 docs-search。此技能面向源代码，而不是文档。

使用方法

这四类操作彼此独立。根据症状选择操作：

症状	选择	首先阅读的规则
准备盲目 grep，查询内容模糊	Find	find-classify-query
还没找到模式就准备读取整个文件	Find（grep）	find-grep-before-read
找到候选文件，但不确定是否符合惯用写法	Find（测试）	find-tests-show-intent
准备在 knowledge/libraries/ 中扫描，但还没读取指定条目	Find（有界读取）	find-bounded-knowledge-read
找到实现；需要梳理其公共接口	Trace（向外）	trace-imports-outward
已了解公共接口；需要查看不同变体和演变过程	Trace（向内）	trace-usages-inward
深陷样板代码、旧版路径、测试脚手架	Filter	filter-load-bearing
已完成 — 准备结束会话	Capture	capture-registry-record

类别概览和顺序设置依据，请参阅 references/_sections.md。

规则类别

#	类别	前缀	操作	规则数
1	Find	find	根据查询定位合适的代码；有界读取知识内容	4
2	Trace	trace	跟踪导入和使用情况，梳理模式	2
3	Filter	filter	去除噪声，突出关键模式	1
4	Capture	capture	将代码概况写入 registry/，以便复用	1

快速参考

1. Find

• find-classify-query — grep 前先对查询分类（组件 / 组合 / 状态 / 副作用 / 错误 / 构建 / 路由）；分类结果决定 grep 目标和目录提示
• find-grep-before-read — 先进行范围较小的 grep，精准定位文件；切勿一开始就读取整个文件
• find-tests-show-intent — 测试、examples/ 和 e2e/ 目录是作者展示设计意图的标准示例；根据文字说明形成假设之前，应先查阅这些内容
• find-bounded-knowledge-read — 文件名就是索引：只读取 knowledge/libraries/<slug>.md，切勿扫描整个目录；无论知识库大小如何，都能限制每次调用的 token 开销

2. Trace

• trace-imports-outward — 从实现文件出发，沿导入关系向外追踪，找出该模式的公共接口和依赖项
• trace-usages-inward — 从公共接口出发，在同一仓库中查找调用点，了解不同变体、边界情况以及模式如何演变

3. Filter

• filter-load-bearing — 从答案中剔除样板代码（重新导出、构建器、辅助函数）、旧版路径（已弃用目录、_old/、legacy/）和测试脚手架；答案只保留关键模式

4. Capture

• capture-registry-record — 在成功会话结束时，将 knowledge/libraries/<library>.md 的 code: 部分写入信息（仓库 URL、分支、SHA、目录映射、命名约定、AGENTS.md 标记、samples-dir 位置），让下次查找时无需再探索

知识库

每个库的代码拓扑记录都存放在仓库根目录的共享知识图谱中，路径为 /knowledge/libraries/。docs-search 也会写入这些文件——每个技能各自负责一个部分（此技能负责 code:，docs-search 负责 docs:），绝不会覆盖另一部分。合并后的架构、Wiki 链接惯例和合并规范，请参阅 knowledge/README.md。

知识库在 v0.1.0 时刻意保持为空。促成此技能的激进简化建议是：不要预先行动；从一次真实查询开始添加第一条记录。如果你发现自己正要为一个尚未实际查询过的仓库添加记录，请停下来——等待真正的需求出现。

读取规范：用户提到某个库时，只执行 read knowledge/libraries/<slug>.md。绝不要扫描 knowledge/libraries/ 来“看看有哪些内容”——文件名就是索引，惰性访问能确保每次调用的令牌成本不受知识库大小影响。

相关技能

• docs-search — 面向文档而非源代码的对应技能；结构相同（方法论 + 共享知识图谱）；它写入与此技能相同的 knowledge/libraries/<lib>.md 文件中的 docs: 部分，而此技能写入 code: 部分
• library-reference-distillation — 基于上游文档编写完整库参考规则包的指南；面向文档源的重型对应技能
• （未来）code-atlas-distillation — 尚未构建。用于编写完整静态代码图谱技能（如 opencode-ts）的指南。在发布第 4 或第 5 个静态代码图谱技能，且经验模式已清晰可见时再提取。
• opencode-ts、openai-codex-rust-patterns、nextjs-ppr-patterns — 面向特定库的重型精选成果；若它们存在，优先使用它们，而非此技能
• codebase-comprehension-algorithms — 用于全代码库领域映射的重型算法工具包（Leiden、MoJoFM、SBM）；与聚焦查询提取正交
• radical-simplification — 位于此技能之上的思维层；此技能本身是将“约束 → 命名不变量”这一做法应用于反复出现的“N 个 X 技能”陷阱的第三个实例

编写说明

这些规则承载关键作用，并非装饰。每条规则都指出了 Agent 查阅陌生源代码时容易采取的错误默认做法：先读完整文件再搜索、忽略测试所体现的规范意图、混淆样板代码与关键模式、把每次查询都当作一次性操作。如果某条规则只是在重述一个能力足够强的模型本来就能正确做到的事，就删掉它。覆盖效果应通过 /dev-skill:eval 对真实的“X 如何实现 Y”提示词进行评估来证明，而非靠规则数量。随着真实查询产生需求，注册表会自然扩展；当某个库被查询超过约 3 次时，就说明应将其升级为完整的静态代码图谱技能。