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.

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：建立项目地图

# 读懂项目自述
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 标记——恰恰是最有工程学习价值的：

# 寻找工程"疤痕"：有意识的补丁和权衡
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，输出到：

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

四、模式 B · 专题聚焦

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

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

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

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

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

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

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

例如，想理解"工具调用机制"：

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

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

B-2：定位相关代码

# 按功能关键词搜索（先广后窄）
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，输出到：

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 获取详细策略。