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