# Code Alchemy

> 将项目代码炼成可复用的智慧文档。Use PROACTIVELY when: user shares a codebase/repo and wants it explained, analyzed, or documented; user asks "how does this project work", "what are the highlights of this code", "explain this architecture", "how is X implemented"; user invokes /code-Alchemy with or without a focus argument. Produces structured Markdown insight documents in docs/ covering design philosophy, core call chains, key technical implementations with code excerpts, UML/Mermaid diagrams, and transferable insights — written so that an AI reading the output can apply the learned patterns to new projects.

- Skill: `keluojun/code-alchemy` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add keluojun/code-alchemy`
- Raw SKILL.md: https://api.skillmd.com/api/skills/keluojun/code-alchemy/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: KeLuoJun (https://skillmd.com/u/keluojun)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/keluojun/code-alchemy

---


# Code Alchemy · 代码炼金术

> 把项目代码炼成可迁移的智慧。不是注释，不是 README，而是一份让 AI（或人类）读完就能"学到功夫"的洞察文档。
>
> **核心信念**：代码库天然不是为"第一次看到的人"设计的——它首先服务于项目本身的演进，其次才是外部读者的理解。炼金术的价值，正在于跨越这道鸿沟。

---

## 一、调用模式识别（必须先判断）

接收到任务时，**首先判断调用模式**，这决定了分析焦点和文档粒度：

| 调用形态 | 判断信号 | 分析策略 |
|---------|--------|--------|
| `/code-Alchemy`（无参数） | 无附加说明，或泛泛要求"分析/介绍项目" | **全项目鸟瞰** → 见模式 A |
| `/code-Alchemy <用户问题>` | 斜杠命令后跟随具体问题 | **专题聚焦** → 见模式 B |
| **自动触发** | 用户分享代码并问"怎么做到的/有什么亮点/这部分怎么实现的" | 根据问题粒度判断 A 或 B |

**不要跳过此判断直接开始分析。** 模式决定后续一切策略。

---

## 二、分析策略哲学（三层炼金法）

**炼金的本质不是"读懂代码"，而是"提炼可迁移的智慧"。**

```
第一层：表象（What）   → 这里做了什么？
第二层：机制（How）    → 关键代码是怎么实现的？
第三层：哲学（Why）    → 为什么这样设计？解决了什么深层问题？
```

只停在第一层的文档是注释，停在第二层的是教程，**三层兼备才是「智慧」**。

每一个值得记录的亮点，都必须能回答：
> "如果我在另一个项目里遇到同样的问题，这里的做法值得借鉴吗？为什么？"

---

## 三、模式 A · 全项目鸟瞰

> 适用：无参数调用，或用户想全面理解项目

### A-0：先理解，再分析（不可省略的前置步骤）

在开始钻研任何代码细节之前，先用 **10 分钟**建立全局视角，强制回答以下 6 个问题：

**① 项目核心目标**
- 解决什么问题？为谁解决？
- 核心价值主张是什么？（区别于同类项目的独特之处）

**② 主入口定位**
- 这是 CLI / API 服务 / 库 / 框架，哪种形态？
- 启动链路从哪里开始？

**③ 关键模块 vs 配套设施**
- 哪些目录是核心业务逻辑？哪些是工具层、适配层、测试层？
- 从目录结构可以反推出怎样的架构风格？

**④ 一次请求/指令/任务的流动**
- 用户操作如何被接收？如何被解析？
- 核心处理发生在哪一层？最终如何返回结果？

**⑤ 关键抽象与设计动机**
- 项目最核心的数据结构/接口是什么？
- 为什么要这样设计？（答案往往不在注释里，在代码组织方式里）

**⑥ 20% 高价值代码识别**
- 哪些位置决定了项目最有学习价值的部分？
- 参考 `references/analysis-strategies.md` 的高价值代码清单

> ⚠️ **这 6 个问题的答案，是后续分析的锚点。** 全部回答后再进入下一阶段。

---

### A-1：建立项目地图

```bash
# 读懂项目自述
cat README.md CHANGELOG.md ARCHITECTURE.md DESIGN.md 2>/dev/null | head -200

# 感知规模（超过 30 个核心文件，触发"大型项目策略"）
find . -type f \( -name "*.py" -o -name "*.ts" -o -name "*.js" \
  -o -name "*.go" -o -name "*.rs" -o -name "*.java" \) \
  | grep -v "node_modules\|\.git\|dist\|build\|__pycache__" | wc -l

# 2层目录结构（感知模块分布）
find . -maxdepth 2 -type d \
  | grep -v "node_modules\|\.git\|dist\|__pycache__\|\.cache" | sort

# 找入口文件
find . \( -name "main.*" -o -name "index.*" -o -name "app.*" \
  -o -name "cli.*" -o -name "server.*" \) \
  | grep -v "node_modules\|\.git" | head -10

# 了解技术栈（依赖 = 技术选型的快照）
cat package.json requirements.txt Cargo.toml go.mod pyproject.toml 2>/dev/null | head -60
```

**脑中构建项目地图**（不用输出，但必须明确）：
```
入口:     [文件路径]
核心层:   [3-5 个最重要的模块/目录]
支撑层:   [工具、配置、数据模型]
外部依赖: [最关键的 2-3 个库，说明选型理由]
代码规模: [行数量级，影响分析深度]
```

---

### A-2：追踪核心调用链

**最有效的理解方式不是按文件顺序读，而是追踪一次完整的任务流动。**

选择项目最典型的一个用户操作/功能场景，追踪完整链路：

```
[用户触发点] → [接收/解析层] → [业务处理层] → [核心逻辑] → [外部调用/数据层] → [结果返回]
```

追踪时，记录每个节点的：
- 文件路径 + 关键函数名
- 该节点做了什么特殊处理
- 为什么流程在这里"转折"

> 这条调用链，将成为文档中 Mermaid sequenceDiagram 的直接素材。

---

### A-3：解析设计决策维度

**优秀项目最值得学的不是语法技巧，而是背后的设计选择。**

围绕以下设计维度，主动向代码提问（详细的提问策略见 `references/analysis-strategies.md`）：

| 设计维度 | 核心提问 |
|---------|--------|
| **信任模型** | 系统在多大程度上信任外部输入/LLM 输出？有哪些校验和兜底？ |
| **状态管理** | 上下文、会话、工具状态分别怎么管理？显式还是隐式？ |
| **扩展机制** | 新能力如何接入？插件化还是硬编码？注册表模式？ |
| **错误处理** | 各类错误（网络/逻辑/外部依赖）分别如何处理？fail-open 还是 fail-closed？ |
| **性能取舍** | 哪里用了缓存？哪里做了懒加载？成本和延迟如何权衡？ |
| **安全边界** | 权限模型是什么？默认策略允许还是拒绝？敏感数据怎么处理？ |

---

### A-4：挖掘工程智慧（补丁与注释）

**这一步是最容易被跳过但价值极高的环节。**

成熟系统里，那些"不完美"的地方——补丁代码、防御性注释、TODO、HACK 标记——恰恰是最有工程学习价值的：

```bash
# 寻找工程"疤痕"：有意识的补丁和权衡
grep -rn "TODO\|FIXME\|HACK\|XXX\|WORKAROUND\|fragile\|brittle" . \
  --include="*.py" --include="*.ts" --include="*.go" \
  | grep -v "node_modules\|\.git" | head -30

# 寻找防御性注释（往往藏着血泪教训）
grep -rn "NOTE:\|WARNING:\|IMPORTANT:\|DANGER:" . \
  --include="*.py" --include="*.ts" --include="*.go" \
  | grep -v "node_modules" | head -20

# 找注释最密集的文件（作者认为最需要解释的地方）
grep -rcn "^#\|^//" . --include="*.py" --include="*.ts" \
  | grep -v "node_modules" | sort -t: -k2 -rn | head -10
```

这些发现揭示：
- 生产系统不是教科书里的理想模型
- 每个"补丁"背后都有一个真实的踩坑经历
- 技术债务是有意识的选择，不是无知的产物

---

### A-5：文档撰写

使用 `references/doc-template.md` 中的**模板 A**，输出到：

```bash
mkdir -p docs
# 命名：docs/code-alchemy-{项目名}-{YYYYMMDD}.md
```

---

## 四、模式 B · 专题聚焦

> 适用：用户提出具体问题，如"项目是如何实现 X 的"、"提示词设计有什么亮点"

### B-0：问题解构（先做这一步）

用 3W 框架拆解用户问题：

```
What  → 用户想理解的技术现象是什么？（精确命名）
Where → 这个现象对应项目中哪些文件/模块？（先定位，再分析）
Why   → 用户为什么想理解这个？学习/复现/改进？（影响洞察侧重）
```

**不要在没有明确 Where 的情况下开始分析。**

---

### B-1：从一个小功能点出发

**专题分析最有效的切入方式：选定一个最典型的功能实例，跑完它的完整生命周期。**

例如，想理解"工具调用机制"：
1. 找到一次真实工具调用的触发入口
2. 追踪：指令解析 → 工具选择逻辑 → 参数拼装 → 执行调度 → 结果回填
3. 在关键节点记录：做了什么 + 为什么在这里做

> 跑完一条功能链路，沿途经过的模块关系就自然理清了。
> 沿途暴露的模块，比"按目录扫描"更能说明设计意图。

---

### B-2：定位相关代码

```bash
# 按功能关键词搜索（先广后窄）
grep -rn "{关键词}" . \
  --include="*.py" --include="*.ts" --include="*.go" \
  | grep -v "node_modules\|\.git" | head -30

# 按文件名/目录名搜索
find . -name "*{feature}*" -o -name "*{keyword}*" \
  | grep -v "node_modules\|\.git" | head -15

# 找到最被引用的相关符号（高引用 = 高重要性）
grep -rn "{FunctionOrClass}" . --include="*.py" --include="*.ts" \
  | grep -v "node_modules" | wc -l
```

---

### B-3：调用链精确追踪

```
触发点（用户操作 / API 调用 / 事件）
  ↓ [记录：文件:行号，函数名]
接收/路由层
  ↓ [记录：如何分发，为什么这样分发]
核心处理层
  ↓ [记录：关键算法或决策逻辑]
数据层 / 外部调用
  ↓ [记录：I/O 边界在哪里]
结果处理与返回
```

---

### B-4：文档撰写

使用 `references/doc-template.md` 中的**模板 B**，输出到：

```bash
mkdir -p docs
# 命名：docs/code-alchemy-{主题关键词}-{YYYYMMDD}.md
```

---

## 五、输出质量检查清单

一份合格的 Code Alchemy 文档，必须满足：

- [ ] **一句话定位**：项目是什么、解决什么问题（全项目必须）
- [ ] **Mermaid 图**：架构图或核心调用链时序图（至少一张）
- [ ] **代码佐证**：每个亮点附带代码片段（路径 + 行号范围）
- [ ] **Why 解释**：每个设计决策有"为什么"的解释，不只是 What/How
- [ ] **工程补丁**：至少提及一处有价值的 TODO/HACK/注释（全项目必须）
- [ ] **可迁移洞察**：明确写出"如何在新项目中复用这个思路"
- [ ] **长度适中**：全项目 2000-4500 字；专题 800-2000 字

---

## 六、特殊场景处理

**代码量巨大（核心文件 >50 个）**：
激活"20% 策略"——只深入以下高价值位置：启动入口、核心调度循环、工具/插件机制、状态管理层、与外部系统的交互边界。其余文件一律跳过，文档中注明"未覆盖区域"。

**项目无文档**：
从测试文件逆向理解意图——测试往往比实现代码更直接说明"这个模块应该做什么"。

**专题模式问题模糊**（如"有什么亮点"）：
自动升级为模式 A，文档开头注明"基于全项目扫描的亮点提炼"。

**遇到无法理解的代码**：
诚实标注 `> ⚠️ [待深入]`，不猜，可注明"需运行时日志才能验证"。

---

加载此文件后，继续读取 `references/doc-template.md` 获取输出模板。
分析大型项目时，同步读取 `references/analysis-strategies.md` 获取详细策略。