qoder-config/skills/repo-analyzer/references/analysis-guide.md

分析哲学与思维框架

核心立场

分析的目标是让读者学到东西、产生思考，而不是获得一份代码说明书。好的分析像一位资深工程师在白板前讲解——有观点、有推理、有对比，读完后读者能参与架构讨论。

每个评价都需要：代码依据、对比基准、推理过程。"代码质量不错"不是评价，"项目在错误处理上采用了统一的 Result 类型而非异常，这让错误路径在类型层面可见，代价是增加了调用方的样板代码——对于这个强调可靠性的基础设施项目来说，这个权衡是合理的"才是评价。

从项目特征中发现值得深挖的点

不要套用模板。每个项目都有自己的"有趣之处"，发现它们的方法：

追问设计动机：看到一个设计选择时，问"为什么不用更常见的方案？"如果答案是"没有特别原因"，这可能是一个改进点；如果答案揭示了深层约束，这就是值得展开的洞察。

寻找张力点：好的架构是在矛盾需求之间找平衡。寻找项目中的张力——性能 vs 可读性、灵活性 vs 简单性、一致性 vs 自治性。这些张力点往往是最有分析价值的地方。

识别设计哲学：大多数成熟项目有贯穿始终的设计风格（"约定优于配置"、"零成本抽象"、"显式优于隐式"）。识别这个哲学，然后检验它是否被一致地贯彻——不一致的地方往往有故事。

关注边界：模块边界、抽象层边界、系统边界——边界的设计往往比内部实现更能体现架构思考。一个模块内部可以随时重写，但边界一旦确定就很难改。

如何发现真正的设计亮点

亮点是在特定约束下做出的聪明权衡，不是"代码整洁"或"注释完善"这种泛泛之谈。

发现方法

对比法："如果是我来设计，我会怎么做？"——如果你的第一反应方案和项目的方案不同，深入比较两者的权衡，往往能发现项目方案的精妙之处。

追问法："这个设计解决了什么不明显的问题？"——表面上看起来过度设计的地方，可能是在防御一个你还没注意到的边界情况。

场景法："在极端场景下会怎样？"——高并发、网络分区、数据量暴增、下游服务挂掉——好的设计在极端场景下优雅降级，差的设计在极端场景下崩溃。

演进法："这个设计是如何演变到现在的？"——git 历史和代码中的注释有时能揭示设计演进的故事，当前的"复杂"设计可能是多次踩坑后的智慧结晶。

亮点的层次

层次	示例	分析价值
架构级	独特的模块化策略、创新的扩展机制	高——值得深入展开
设计模式级	巧妙的状态管理、优雅的错误传播	中——值得一段解释
实现级	精巧的算法选择、高效的数据结构	视情况——只有当它体现设计思想时才值得展开

如何写出有启发性的分析

对比式思考

每个设计决策都存在于一个选择空间中。好的分析不只描述"选了什么"，还要说明"没选什么以及为什么"。

❌ 该项目使用事件驱动架构进行模块间通信。

✅ 模块间通信选择了事件总线而非直接调用。直接调用更简单、调试更容易，但会让模块间产生编译期依赖——任何模块的接口变更都会波及调用方。事件总线的代价是运行时才能发现通信错误，但换来了模块可以独立开发和部署。对于这个插件化架构来说，这个权衡是合理的。

反事实推理

"如果不这样做会怎样"是检验设计必要性的利器。如果去掉一个设计元素后系统仍然正常工作，那它可能是过度设计；如果会导致严重问题，那就值得深入解释。

设计权衡三角

大多数架构决策涉及三个维度的权衡。找到这三个维度并说明项目在哪个方向上做了倾斜，比简单说"好"或"不好"有价值得多。

常见的权衡三角：

• 简单性 / 灵活性 / 性能
• 一致性 / 可用性 / 分区容忍
• 开发速度 / 运行时安全 / 学习曲线

全局关联

每个局部分析都必须连接到项目整体设计哲学。 这是区分"代码说明书"和"架构分析"的关键。

做法：

• 分析一个模块时，先说明它在整个系统中扮演什么角色
• 解释一个设计决策时，说明它如何服务于项目的整体设计哲学
• 发现一个问题时，评估它对整个系统的影响范围
• 描述模块间协作时，解释这种协作模式是否与项目其他部分一致

反面教材：孤立地分析每个模块，最后拼在一起——这样的报告读起来像一堆独立的代码审查，缺乏整体叙事。

叙事连贯

模块分析不是独立章节的拼接，而是一条有逻辑的叙事线。

好的模块叙事像一本书的章节——每章结尾自然引出下一章的主题。读者不需要目录就能理解为什么先讲 A 再讲 B。

常见的叙事主线：

• 数据流驱动：跟随一个请求从进入系统到返回响应的完整路径，沿途讲解每个模块的职责。适合 Web 框架、API 网关等请求驱动的系统
• 分层驱动：从最底层的基础设施讲到最上层的用户接口，每层依赖下层的能力。适合操作系统、编译器等分层架构
• 问题驱动：从核心业务问题出发，逐步引入解决每个子问题的模块。适合领域复杂的业务系统

反面教材：按目录结构或字母顺序排列模块——这样的报告读起来像一本字典，不像一篇分析。

过渡句示例：

✅ Gateway 完成了请求的认证和路由分发，但它只负责"谁可以进来"，不负责"进来之后能做什么"。这个行为控制的职责，由沙箱运行时的策略引擎承担。

❌ 接下来我们分析策略引擎模块。

深度标准

有深度的分析长这样

路由系统选择了基数树（radix tree）而非哈希表。哈希表查找是 O(1)，但不支持参数路由（/users/:id）和通配符——要支持这些就得退化为线性扫描。基数树在静态路由上接近 O(1)，同时天然支持前缀匹配，让参数路由和通配符成为一等公民。代价是实现复杂度高、内存占用略大，但对于一个以路由性能为卖点的框架来说，这个投入是值得的。值得注意的是，Fastify 和 Hono 也做了同样的选择，这已经成为高性能路由的事实标准。

特征：有具体的技术推理、有量化的权衡、有业界对比、有"为什么适合这个项目"的判断。

没有深度的分析长这样

路由系统采用了高效的数据结构来存储和匹配路由，支持参数路由和通配符匹配，性能表现优秀。

特征：泛泛而谈、没有具体技术细节、没有推理过程、换一个项目也能用。

批判性思考指引

如何诚实评价

• 有代码依据：每个评价都要指向具体的代码证据，不能凭印象
• 有对比基准：说"好"或"不好"时，对比的是什么？业界最佳实践？同类项目？项目自身的设计目标？
• 区分"不同"和"不好"：非主流的设计选择不等于错误，可能是在不同约束下的合理权衡

如何与业界对比

• 选择真正可比的项目（同领域、同规模、同目标用户）
• 对比设计选择而非实现质量——不同项目有不同的成熟度
• 承认各自的约束差异——一个 2 人项目和一个 200 人项目面对的问题不同

如何指出问题而不流于吹毛求疵

• 只指出架构级别的问题，不纠结命名风格或代码格式
• 解释问题的实际影响——"这会导致什么具体后果"
• 如果可能，提供改进方向（不需要完整方案）
• 承认项目的约束——有些"问题"在特定约束下是合理的妥协

如何识别真正的问题

问题是对系统产生实际影响的架构缺陷，不是命名风格或代码格式。

影响面分析：这个问题影响多少模块？影响的是核心路径还是边缘场景？影响面越大，问题越值得指出。

演进风险：这个问题现在可能不严重，但随着项目增长会恶化吗？"技术债务"的本质是利息——现在不还，将来要付更多。

替代方案可行性：指出问题时，心里要有一个可行的改进方向。如果你想不到更好的方案，那可能不是问题，而是在当前约束下的合理妥协。

问题的层次

层次	示例	如何表述
架构级	循环依赖、职责混乱、单点瓶颈	详细分析影响 + 改进方向
设计级	抽象泄漏、过度设计、状态管理混乱	说明具体后果 + 对比更好的做法
工程级	测试策略缺失、可观测性不足	简要指出 + 建议

评价的诚实性

• 项目质量高就多写亮点，不需要凑问题
• 项目有明显缺陷就直说，不需要找补
• 承认不确定性——"从代码来看可能是 X，但也可能有我没看到的约束"
• 区分"设计选择"和"设计缺陷"——非主流不等于错误

综合评价维度

不使用固定评分表，但评价应覆盖以下维度（根据项目特征选择最相关的）：

• 架构设计：模块化程度、关注点分离、扩展性
• 设计哲学一致性：项目是否贯彻了自己的设计理念
• 工程成熟度：测试、文档、错误处理、可观测性
• 生态适应性：在目标生态中的定位是否合理
• 演进健康度：技术债务水平、架构是否支持未来演进

每个维度的评价都要有具体依据，不要给出没有论证的分数。