code-distiller
Installation
SKILL.md
代码蒸馏器 · Code Distiller
「代码是思想的快照。蒸馏代码，就是还原写代码那个人的认知操作系统。」
核心理念
代码蒸馏器不是生成文档，是提炼认知框架。
一个好的项目Skill是一套可运行的代码认知操作系统：
- 用什么架构模式组织系统？（骨架）
- 用什么业务模型表达领域？（灵魂）
- 用什么设计模式解决问题？（招式）
- 用什么编码DNA写代码？（风格）
- 技术债务和已知局限在哪？（诚实边界）
关键区分：捕捉的是 WHY they code this way，不是 WHAT the code does。
主动触发检测
不必等用户主动请求。以下信号出现时，主动建议蒸馏：
- 用户在同一个项目中反复问「这个文件是干什么的」「这里为什么这么写」
- 新人加入项目、接手他人代码
- 准备重构前需要理解全貌
- 用户说「帮我理解这套代码」「这个项目太复杂了」
执行流程
Phase 0: 入口确认
收到用户输入后，确认：
- 项目路径：需要蒸馏的代码在哪里？
- 蒸馏深度（详见下方「蒸馏深度分级」）：
quick：快速扫描，5分钟出结果，只出架构概览standard：标准蒸馏，6路并行，输出完整 Skilldeep：深度蒸馏，增加执行路径追踪、量化指标、Mermaid 图
- 聚焦方向（可选）：全面蒸馏 vs 聚焦某个维度？
- 用途：
- 新人上手指南？→ 侧重架构+约定+业务流+陷阱清单
- 代码审查参考？→ 侧重模式+反模式+编码DNA+自由度标注
- 项目重构指南？→ 侧重架构决策+技术债+依赖关系+量化指标
- 通用认知Skill？→ 全面蒸馏
- 输出位置：Cursor Skill / Claude Code Skill / 两者都要？
- 补充材料：有没有架构文档、设计决策记录、README、CHANGELOG 等？
用户说「蒸馏这个项目」→ 默认 deep 深度 + 通用认知Skill + 双格式输出，直接推进。
规模适配：如果项目 <20 个文件或 <2000 行代码，建议改为生成 Cursor Rule（.cursor/rules/）而非完整 Skill，避免过度分析。
确认后 → Phase 0.5。
蒸馏深度分级
| 级别 | 行为 | 产出 | 适用场景 |
|---|---|---|---|
quick |
扫描入口文件+配置+README，不启动 subagent | 架构概览（1页） | 快速了解陌生项目 |
standard |
6路并行 Agent，完整 Phase 1-4 | 完整 SKILL.md + research 文件 | 中小型项目快速蒸馏 |
deep（默认） |
standard + 执行路径追踪 + 量化指标 + Mermaid 图 + 确定性脚本预扫描 + Git 演化分析 | 完整 Skill + 量化报告 + 架构图 + 演化时序 | 任何项目的全方位蒸馏 |
Phase 0.5: 确定性预扫描 + 创建 Skill 目录
收到确认后立即执行，在 Agent 分析之前完成。
Step 1: 确定性预扫描（脚本采集事实）
先用确定性命令采集客观事实，为 Agent 的 LLM 判断提供锚点：
# 项目规模统计
find [项目路径] -type f -name '*.ts' -o -name '*.tsx' -o -name '*.js' -o -name '*.jsx' -o -name '*.py' -o -name '*.go' | wc -l
find [项目路径] -type f \( -name '*.ts' -o -name '*.tsx' \) | xargs wc -l | tail -1
# 目录结构（2层深度）
tree [项目路径] -L 2 -d --noreport
# 依赖清单
cat [项目路径]/package.json | jq '.dependencies, .devDependencies' 2>/dev/null
# 配置文件清单
ls [项目路径]/*.config.* [项目路径]/.*rc* [项目路径]/*.json 2>/dev/null
Step 1.5: Git 演化时序分析
理解一个项目，不只要看它现在长什么样，更要看它是怎样一步步演变成现在这个样子的。通过 git 历史还原项目的演化轨迹：
# 第一次提交（项目起点）
git -C [项目路径] log --reverse --oneline | head -1
# 完整提交时间线（按时间排列的关键里程碑）
git -C [项目路径] log --oneline --date=short --format="%ad %s" | head -50
# 按月统计提交量（开发节奏）
git -C [项目路径] log --format="%ad" --date=format:"%Y-%m" | sort | uniq -c
# 贡献者及其活跃度
git -C [项目路径] shortlog -sn --all
# 每个目录/模块的首次创建时间（模块演化顺序）
for dir in $(find [项目路径] -maxdepth 2 -type d -not -path '*/.git/*' -not -path '*/node_modules/*'); do
echo "$(git -C [项目路径] log --diff-filter=A --format=%ad --date=short -- "$dir" | tail -1) $dir"
done | sort
# 最近的重大变更（识别当前开发方向）
git -C [项目路径] log --oneline -20
# 高频变更文件（热点代码）
git -C [项目路径] log --pretty=format: --name-only | sort | uniq -c | sort -rn | head -20
# 标签/版本历史（版本演化）
git -C [项目路径] tag --sort=-creatordate | head -10
# Bug修复和Hotfix历史（陷阱信号源）
git -C [项目路径] log --oneline --grep="fix\|bug\|revert\|hotfix\|workaround" -i | head -20
预扫描结果存入 references/research/00-prescan.md，包含：
- 文件数/行数/语言分布（客观数据，不是 LLM 推测）
- 目录骨架
- 依赖清单
- 配置文件清单
- Git 演化时序：
- 项目起点和年龄
- 模块创建顺序（哪些是最初就有的核心，哪些是后来新增的）
- 开发节奏（哪些阶段开发密集，哪些阶段沉寂）
- 贡献者分布（单人项目还是团队协作）
- 热点文件（哪些文件被修改最频繁→往往是核心也是痛点）
- 版本演化轨迹（从 tag/release 识别重大里程碑）
- Bug/Hotfix 历史（陷阱的第一手信号源）
Step 2: 创建 Skill 目录
[output-path]/[project-name]-codebase/
├── SKILL.md # 最终产物
├── analysis.json # 结构化分析结果（可供后续对比）
└── references/
├── research/ # 每个 Agent 的分析结果（必存）
│ ├── 00-prescan.md # 确定性预扫描数据
│ ├── 01-architecture.md # 架构与系统设计
│ ├── 02-business-logic.md # 业务逻辑与领域模型
│ ├── 03-patterns.md # 设计模式与代码惯例
│ ├── 04-data-flow.md # 数据流与状态管理
│ ├── 05-infrastructure.md # 构建、部署与工程化
│ └── 06-quality.md # 质量、安全与性能
├── code-samples/ # 关键代码片段（代表性样本）
└── diagrams/ # Mermaid 架构图（deep 模式生成）
关键规则：
- 每个 subagent 必须把分析结果写入对应的 md 文件
- 所有文件必须存在 skill 目录内部，Skill 必须自包含
- 代码片段只引用关键的、有代表性的部分，不是全文复制
analysis.json保存结构化结果，用于增量更新时的差异对比
Phase 1: 六路并行代码分析（Agent Swarm）
启动6个并行 subagent，每个负责不同的分析维度。每个 Agent 在启动时获得 00-prescan.md 的预扫描数据作为锚点。
Agent 分析视角（允许重叠，各有侧重）
同一段代码可以被多个 Agent 从不同视角分析——正如同一段业务代码，架构 Agent 看的是它在系统中的位置，模式 Agent 看的是它用了什么抽象策略，质量 Agent 看的是它的错误处理方式。重叠不是浪费，是多维度认知的来源。
| Agent | 分析视角 | 看同一段代码时关注什么 |
|---|---|---|
| 1 架构 | 系统骨架 | 这段代码在系统中扮演什么角色？模块间如何连接？ |
| 2 业务 | 领域含义 | 这段代码表达了什么业务规则？实体关系是什么？ |
| 3 模式 | 解决方案 | 这段代码用了什么设计模式？抽象是否合理？ |
| 4 数据流 | 数据生命周期 | 数据从哪来、怎么变换、存在哪、谁消费？ |
| 5 工程 | 开发体验 | 构建配置、脚本、环境管理如何支撑开发？ |
| 6 质量 | 健壮性 | 错误怎么处理？安全风险在哪？性能瓶颈？ |
多 Agent 发现同一模式时：在 Phase 1.5 合并阶段，将多视角发现合并为更丰富的认知，而非去重丢弃。
6 个 Agent 的任务分配
| Agent | 分析目标 | 提取重点 | 输出文件 |
|---|---|---|---|
| 1 架构 | 项目结构、框架选择、模块划分 | 分层策略、模块边界、依赖关系图、入口点、路由架构 | 01-architecture.md |
| 2 业务 | 核心业务逻辑、领域模型 | 实体关系、业务规则、工作流、状态机、核心算法 | 02-business-logic.md |
| 3 模式 | 设计模式、代码惯例 | 复用的解决方案模式、抽象策略、接口设计、组件化方式 | 03-patterns.md |
| 4 数据流 | 状态管理、API 设计、数据模型 | 数据流向、缓存策略、API 契约、数据库 schema、类型系统 | 04-data-flow.md |
| 5 工程 | 构建工具、部署流程、CI/CD | 包管理、构建配置、环境管理、脚本、开发工作流 | 05-infrastructure.md |
| 6 质量 | 错误处理、安全、性能、测试 | 错误边界、验证策略、安全模式、性能优化、测试覆盖 | 06-quality.md |
每个 Agent 的硬性要求
- 分析结果必须写入
references/research/0X-xxx.md - 以
00-prescan.md的客观数据为锚点，LLM 判断不得与客观数据矛盾 - 区分「明确的设计决策」vs「可能的约定」vs「我推断的」
- 发现矛盾/不一致时保留记录，不要合理化
- 标注信息充分度：哪些维度分析充分，哪些信息不足
- 提取代表性代码片段（不超过20行/片段），存入
code-samples/ - 追踪执行路径（deep 模式）：对核心功能追踪 Happy Path → Error Path → Edge Case
Agent Prompt 模板（以 Agent 1 架构为例）
你的任务：分析 [项目路径] 的架构与系统设计。
预扫描数据：[粘贴 00-prescan.md 内容，包含 Git 演化时序]
你的分析视角：系统骨架——关注代码在系统中的位置和模块间的连接方式。
其他 Agent 会从业务逻辑、设计模式、数据流等不同视角分析同一份代码。
你可以分析任何代码，但始终从「架构」这个视角出发。
分析方向：
- 项目整体目录结构及其设计意图
- 技术栈选择（框架、语言、核心库）及背后的 trade-off
- 模块/层次划分策略（按功能？按特性？按领域？）
- 模块间的依赖关系和通信方式
- 入口点和启动流程
- 路由/导航架构
- 配置管理策略
- 与标准框架约定的差异点（这些差异往往是最有信息量的）
- 公共 API 表面（项目对外暴露了哪些接口/页面/命令）
- [利用Git演化数据] 模块的创建顺序揭示了哪些是核心、哪些是后续扩展
- [利用Git演化数据] 热点文件和高频变更目录揭示了架构的痛点
输出要求：
- 写入 [skill目录]/references/research/01-architecture.md
- 每个发现标注置信度（确定/推测/信息不足）
- 架构决策用「决策-理由-trade-off」三元组记录
- 提取 3-5 段最能体现架构思想的代码片段
- 生成 Mermaid 架构图存入 references/diagrams/
Agent 超时与失败处理
- 某维度代码极少（如没有测试）：标注「该维度缺失」，在诚实边界中说明
- Agent 结果冲突：保留矛盾，这本身是有价值信号
- 项目过大（>1000文件）：采样策略——按依赖中心度排序（被更多文件 import 的文件优先），核心模块全扫，边缘模块抽样
关键规则：宁可生成一个诚实标注了局限的60分 Skill，也不要生成一个看起来完美但遗漏关键细节的90分 Skill。
Phase 1.5: 跨 Agent 合并 + Review 检查点
Step 1: 跨 Agent 结果合并与去重
6 个 Agent 可能独立发现同一个模式。合并规则：
- 相同模式被 2+ 个 Agent 发现 → 增强置信度，合并证据
- 同一代码段被不同 Agent 从不同角度分析 → 保留多角度视角，标注交叉引用
- 矛盾发现 → 保留为「内在张力」
Step 2: 上下文刷新（防遗忘）
在生成摘要之前，必须重新读取所有 6 个 research 文件。 长时间分析后早期发现可能在上下文中衰减，此步骤确保完整性。
Step 3: 展示分析质量摘要
┌──────────────────┬──────────┬──────────────────────────┐
│ Agent │ 覆盖度 │ 关键发现 │
├──────────────────┼──────────┼──────────────────────────┤
│ 1 架构 │ 充分 │ Expo Router + 模块化分层 │
│ 2 业务 │ 充分 │ 核心实体: 3个, 工作流: 2个 │
│ 3 模式 │ 中等 │ 组合模式, Hook 抽象... │
│ 4 数据流 │ 充分 │ Zustand + React Query... │
│ 5 工程 │ 充分 │ EAS Build, OTA... │
│ 6 质量 │ 不足 │ 测试覆盖极低 │
├──────────────────┼──────────┼──────────────────────────┤
│ 跨Agent重复发现 │ 2个模式 │ 已合并，置信度提升 │
│ 矛盾点 │ 1处 │ 状态管理存在混用 │
│ 信息不足维度 │ 测试 │ │
│ 项目规模 │ 150文件 │ ~12,500行代码 │
└──────────────────┴──────────┴──────────────────────────┘
用户确认 OK → Phase 2。用户觉得不够 → 补充分析。
Phase 2: 认知框架提炼（Synthesis）
读取 references/extraction-framework.md 获取代码模式的三重验证方法论，确保提炼质量。
2.1 架构心智模型提取（3-7 个）
三重验证筛选（详见 extraction-framework.md）：
- 频率复现：模式在 ≥3 个不同模块/文件中出现
- 意图性：明显是刻意设计，不是框架强制
- 特异性：不是该框架的通用约定，体现了项目特有的设计思想
反抽象化护栏：每个模型必须能回答「如果违反它会怎样？」——如果答不出具体后果，说明太抽象，应丢弃或降级为编码惯例。
每个模型记录：名称、一句话描述、代码证据（≥2处）、应用场景、局限性、自由度标注。
2.1.1 模式自由度标注
每个提取的模式标注遵循自由度，指导后续使用者判断何时必须严格遵循、何时可灵活调整：
| 自由度 | 含义 | 示例 |
|---|---|---|
| 严格 | 违反会导致功能故障或架构崩塌，必须严格遵循 | 状态管理必须用指定方案、路由必须按约定组织 |
| 推荐 | 有明确偏好，偏离需要理由，但不会导致故障 | 命名约定、文件组织、组件拆分粒度 |
| 灵活 | 多种写法都可接受，项目中也存在变体 | 工具函数风格、注释方式 |
2.2 业务领域模型提取
- 核心实体及其关系
- 业务规则（不变量、约束、验证逻辑）
- 工作流/状态机
- 领域术语表
- 公共 API 表面：项目对外暴露的完整接口清单（页面/API端点/导出函数/CLI命令）
2.3 编码 DNA 分析
| 维度 | 提取内容 |
|---|---|
| 命名约定 | 变量/函数/组件/文件命名风格 |
| 文件组织 | 单文件 vs 拆分、导出方式、index 使用 |
| 抽象偏好 | 何时抽象、抽象层次、DRY vs 显式 |
| 错误处理风格 | try-catch vs Result vs 提前返回 |
| 类型使用 | interface vs type、泛型使用、strict 程度 |
| 注释风格 | 注释密度、注释位置、文档格式 |
| 异步模式 | async/await vs Promise vs callback |
2.4 陷阱清单（Pitfalls & Gotchas）
主动捕获项目中的「坑」——新人容易犯的错、反直觉的设计、隐藏的约束：
- 架构陷阱：违反哪些隐含规则会导致难以调试的问题？
- 配置陷阱：哪些配置项看似可选但实际必须？
- 依赖陷阱：哪些依赖有版本兼容性问题或隐藏限制？
- 业务陷阱：哪些业务规则在代码中不明显但至关重要？
- 环境陷阱：开发/测试/生产环境间的差异陷阱？
每个陷阱记录：现象（你会看到什么）→ 原因（为什么会这样）→ 正确做法（应该怎么做）。
2.5 技术决策与 Trade-off
- 主动选择：明确选了什么，为什么
- 主动放弃：明确没用什么，为什么
- 技术债务：已知的妥协和遗留问题
- 内在张力：设计中存在的矛盾（如灵活性 vs 类型安全）
2.6 依赖谱系
核心依赖 → 项目 → 对外暴露的接口/API
2.7 量化指标（deep 模式）
| 指标 | 测量方式 |
|---|---|
| 代码行数（按语言） | cloc 或 wc -l |
| 文件数量分布 | 按目录/文件类型统计 |
| 圈复杂度 | 识别高复杂度函数（>10） |
| 依赖数量 | package.json 或等价文件 |
| 测试覆盖率 | 测试文件数/源文件数的比值 |
| 最大文件行数 | 识别「上帝文件」 |
2.8 诚实边界
- 分析基于代码快照，不包含运行时行为
- 未覆盖的维度明确标注
- 推断的决策动机可能与实际不符
- 代码风格演化可能导致早期代码与当前约定不一致
Phase 2.5: 提炼确认检查点
展示提炼摘要给用户确认后再构建。
Phase 3: Skill 构建
构建前必须重新读取所有 research 文件（上下文刷新），确保无遗漏。
读取 references/skill-template.md，将 Phase 2 提炼结果组装为可运行的 SKILL.md。
输出格式适配
| 输出目标 | 路径 | 差异 |
|---|---|---|
| Cursor Skill | .cursor/skills/[name]-codebase/ |
frontmatter 用 name + description |
| Claude Code Skill | .claude/skills/[name]-codebase/ |
同结构，直接复制 |
Mermaid 架构图生成（deep 模式）
生成以下 Mermaid 图存入 references/diagrams/：
architecture.mmd：模块依赖关系图data-flow.mmd：核心数据流向图business-flow.mmd：主要业务流程/状态机
在 SKILL.md 中内联引用这些图。
结构化结果持久化
将分析结果同时保存为 analysis.json，包含：
- 架构模式列表（名称、置信度、证据数量）
- 编码DNA规则列表
- 依赖清单及健康状态
- 量化指标
- 分析时间和代码版本
此 JSON 文件用于：增量更新时的差异对比、跨项目模式对比、团队知识库集成。
质量自检
构建完成后，读取 references/extraction-framework.md 末尾的质量自检清单，逐项检查。
Phase 4: 质量验证
生成 Skill 后执行验证：
4.1 还原测试（Reconstruction Check）
选项目中3个关键模块，用 Skill 指导从零描述如何实现。
- 核心架构决策一致 → 模型有效
- 偏离 → 回溯调整
4.2 边缘测试（Edge Case）
假设要新增一个功能，用 Skill 推断应该放在哪个模块、用什么模式。
- 期望：给出明确的、符合项目风格的建议
- 不应该给出与现有架构矛盾的建议
4.3 风格测试（Code DNA Check）
用 Skill 写一段新代码，判断：
- 命名风格一致？
- 抽象层次一致？
- 错误处理方式一致？
4.4 通过标准
| 检查项 | 通过标准 | 不通过信号 |
|---|---|---|
| 架构模型数量 | 3-7个，每个有代码证据 | <3或>10 |
| 业务实体覆盖 | 核心实体 100%，边缘实体 >60% | 遗漏核心实体 |
| 编码DNA辨识度 | 生成的代码风格与项目一致 | 像通用AI代码 |
| 自由度标注 | 每个模式都标注了严格/推荐/灵活 | 全部是同一级别 |
| 陷阱清单 | 至少 3 个具体陷阱 | 没有陷阱或全是泛泛的警告 |
| 诚实边界 | 至少3条具体局限 | 没有标注局限 |
| 技术决策记录 | 主要决策有理由说明 | 只列了什么没说为什么 |
| API 表面 | 公共接口完整列出 | 遗漏关键 API/页面/端点 |
验证通过 → 交付。不通过 → 标注薄弱环节回 Phase 2。 迭代上限：Phase 2→4 最多循环2次。
展示验证结果给用户确认后才算完成。
特殊场景
大型项目（>1000 文件）
- Phase 1 采用采样策略：核心模块全扫，边缘模块抽样
- 优先分析入口文件、核心路由、共享模块、配置文件
- 在诚实边界中标注未覆盖的模块
多语言项目
- 每种语言可能有不同的编码DNA，分别记录
- 跨语言的数据流和接口是重点
Monorepo
- 先识别 package/workspace 结构
- 每个子包可以独立分析，但重点是包间关系
框架项目 vs 业务项目
- 框架/库：侧重 API 设计、扩展点、版本策略
- 业务应用：侧重领域模型、业务流、用户场景
更新已有 Skill
当项目代码更新后：
- 读取现有 SKILL.md 的诚实边界中的分析时间
- 读取
analysis.json获取上次的结构化结果 - 用
git diff+git log识别变更范围 - 只对变更涉及的模块重新启动对应 Agent
- 对比新旧
analysis.json，生成差异报告 - 增量更新 SKILL.md，标注「新增/变更/移除」的模式
品味守则
| 原则 | 一句话 |
|---|---|
| 决策 > 实现 | 为什么用 Zustand 比 Zustand 怎么用更重要 |
| 异常 > 常规 | 偏离框架约定的地方最能揭示设计思想 |
| 矛盾 > 一致 | 代码中的不一致往往暗示了演化历史或设计妥协 |
绝不做的事
- 把框架的通用约定当作项目的「独特设计」
- 忽略技术债务和代码异味
- 在信息不足时强行生成完整模型
- 生成超过项目实际复杂度的架构分析