第一性原理代码优化与工程升级

核心方法论

以马斯克第一性原理为指导思想：拒绝类比思维，拆穿所有"因为一直都这样"的假设，回到问题本质，从第一原理推导最优解。

"第一性原理的思考方式是用物理学的角度看待世界，也就是说一层层拨开事物表象，看到里面的本质，再从本质一层层往上走。" ——埃隆·马斯克

应用到代码世界：不问"这段代码怎么改好"，而是问"这段代码真正在解决什么问题，用最少的复杂度能不能解决它"。

工作流程：Pre-Phase + 四阶段分析法

Pre-Phase：范围对齐（Scope Alignment）

在开始任何分析之前，先完成范围对齐。 这是最容易被跳过但也最关键的一步——盲目分析会浪费 token 并产出用户不关心的内容。

加载 references/scope-alignment.md，根据用户场景选择对齐问题（最多 3-5 个）。

核心原则：

• 不假设：用户说"看看这个项目"≠"全量分析所有代码"
• 确认目标：是"快速扫一眼"还是"系统评估出路线图"？深度完全不同
• 分级裁剪：1000 行项目和 100k 行项目需要完全不同的分析策略
• 每步确认：每完成一个 Phase，给用户一个确认点再继续

范围对齐完成后，确定：

1. 分析深度（浅扫 / 中等 / 深度 / 定向）
2. 重点关注领域（性能 / 安全 / 可维护 / 全部）
3. 分析范围（全量 / 特定模块）

Phase 0：摸底（Reconnaissance）

第一步：运行探索脚本

bash scripts/explore.sh [项目根目录路径]

脚本将自动输出：

• 项目目录结构（前2层）
• 技术栈识别（Node/Python/Go/Java/容器化，含现代框架检测）
• 代码规模估算（行数、文件数）
• Git 历史健康度
• 工程规范快速检查
• 技术债扫描（TODO/FIXME/console.log 等）

第二步：向用户确认发现

将 explore.sh 的关键发现展示给用户（重点呈现 🔴 红色信号和模块复杂度热点）：

"我看到项目用了 X 框架，规模大概 Y，目前没有 CI/CD。最大的文件是 Z（N 行），需要优先关注。这些和你已知的情况一致吗？有没有我需要特别注意的地方？"

用户的回答将直接影响 Phase 1 的聚焦方向。

第三步：补充手动检查：

1. 阅读入口文件（main.ts / app.py / index.js）了解系统启动逻辑
2. 识别核心模块边界（哪些目录/文件是系统的心脏）
3. 如有用户指定的关注模块，优先纳入分析队列

输出：一份项目现状快照，包含技术栈矩阵和初步风险信号。

Phase 0→1 聚焦策略（Focus Strategy）

完成 Phase 0 后，不要对所有模块平等对待。用以下信号确定 Phase 1 的优先分析对象：

优先分析（红灯模块）：

• explore.sh 中标记为 🔴 的工程规范问题所在的模块
• 文件数/行数最多的 3 个目录（最大 = 最复杂 = 最可能有问题的区域）
• 用户在范围对齐阶段提到的痛点区域
• Git 历史中最近频繁修改的文件（git log --oneline -20 重复出现的文件）

次要分析（黄灯模块）：

• 有大量 TODO/FIXME 的区域
• 依赖链较深但缺少测试的模块

可跳过（绿灯模块）：

• 生成代码（generated/、dist/）
• 第三方集成代码（adapters/ 下的薄封装层）
• 变化频率极低的配置/常量模块

Phase 1：解构（Deconstruct）

对聚焦策略筛选出的优先模块，用第一性原理拆解。

加载 references/first-principles-questions.md，根据项目类型使用场景化追问索引。

核心追问（快速版）：

• 这个存在的根本原因是什么？ 它在解决哪个具体问题？
• 如果从零开始，还会这样设计吗？
• 它依赖了哪些假设？这些假设今天还成立吗？
• 删掉它会怎样？ 真的会出问题，还是历史惯性让它留了下来？
• 它的复杂度来自问题本身，还是来自错误的抽象？

常见陷阱识别：

• 过度工程（Over-engineering）：为未来从未到来的需求做的抽象
• 防御性冗余（Defensive Redundancy）：复制粘贴出来的重复代码
• 幽灵依赖（Ghost Dependencies）：没有任何地方调用的模块或工具
• 错位抽象（Misplaced Abstraction）：把业务逻辑放进了基础层，或反之

Phase 2：评审（Audit）

加载 references/code-audit-checklist.md，按项目规模选择审计范围：

• 微型/小型项目：只跑"可读性 + 安全性"维度
• 中型项目：跑"可读性 + 可维护性 + 安全性"维度
• 大型项目：全量 5 维度，但按模块分批跑

为每个维度标注 🔴红/🟡黄/🟢绿 信号，聚焦红色信号的根本原因。

Phase 3：重构路线图（Roadmap）

加载 references/upgrade-patterns.md 获取常见升级模式。 加载 references/decision-framework.md 获取改与不改的决策依据。

优先级矩阵：

渐进原则（绞杀者模式）：

• 不做"大爆炸重写"，采用绞杀者（Strangler Fig）模式逐步替换
• 每次改动保持系统可运行，回归测试保底
• 优先建立测试覆盖，再动核心逻辑

路线图确认：产出初版路线图后，与用户讨论确认优先级，调整后再定稿。

输出物规范

面向技术 Leader / 工程师（详细技术报告）

## 项目现状快照
- 技术栈矩阵：语言 / 框架 / 关键依赖
- 代码规模：X 个文件，Y 行代码，Z 个贡献者
- 初步风险信号：（来自 explore.sh 输出）

## 第一性原理发现
- 核心问题（不超过3个，附根因分析）
- 被错误保留的假设（每条说明为何质疑）

## 代码审计结果
- 🔴 红色信号（共 X 项）：...
- 🟡 黄色信号（共 X 项）：...
- 🟢 绿色信号（共 X 项）：...
- Top 5 优化机会（附预期收益）

## 重构路线图
- P0（立即）：...
- P1（本迭代）：...
- P2（下里程碑）：...
- P3（专项推进）：...
- 建议切入点：[最小可落地的第一步，附理由]

面向 PM / 业务方（非技术摘要）

## 项目健康度总结

**当前状态**：[用一句话定性，如"整体稳定，存在3处需优先处理的风险"]

**需要立即关注的问题**（P0）：
- [问题 1]：[业务影响描述，如"可能导致用户数据泄露"]
- [问题 2]：...

**近期建议投入**（P1/P2）：
- [工作项]：预计耗时 X 天，收益：[用业务语言描述]

**不建议现在做的事**：
- [原因：ROI 不划算 / 时机不成熟 / 风险过高]

**如果不处理，X 个月后可能发生**：[风险预测]

面向团队整体对齐会（技术 + 业务混合场景）

## 项目现状与优化计划

### 一句话总结
[技术健康度定性 + 对业务的影响]

### 做得好的地方
- [亮点 1]：[为什么好，业务价值]
- [亮点 2]：...

### 需要关注的问题（按优先级）
| 优先级 | 问题 | 业务影响 | 建议时间 |
|--------|------|----------|----------|
| P0 | ... | ... | 本周 |
| P1 | ... | ... | 本月 |

### 建议行动方案
- **近期（1-2 周）**：[具体行动]
- **中期（1-2 月）**：[具体行动]
- **需要讨论的决定**：[列出需要团队投票/PM拍板的事项]

### 预期收益
- [定量]：性能提升 X%、Bug 减少 Y%、开发效率提升 Z%
- [定性]：[用户体验改善、团队满意度提升等]

交互节奏

scope-alignment → 确认范围
explore.sh → 展示快照，用户确认
Phase 1 → 核心发现，用户补充上下文
Phase 2 → 审计结果，讨论优先级
Phase 3 → 路线图初稿 → 用户确认 → 定稿

与用户协作的注意事项

• 拒绝一次性全量重写：总是提出渐进方案，保护线上稳定性
• 先理解再质疑：给历史决策以合理解释的机会，再判断是否应该改变
• 量化收益：每个重构建议附上预期收益（性能提升 X%、减少 Y 行维护代码）
• 识别边界：工程升级不是目的，业务目标才是，避免为升级而升级
• 优先测试覆盖：在没有测试覆盖的代码上做重构，等于在没有安全网的高空走钢丝
• 区分受众：对工程师说技术细节，对 PM/业务方用业务语言，使用上方对应模板
• 不假设用户意图：拿不准时问，不要猜。一个对齐问题比 50 行错方向的分析有价值得多

参考资源

• scripts/explore.sh — 项目摸底自动化脚本（Phase 0 第一步必须执行）
• references/scope-alignment.md — 范围对齐策略，Pre-Phase 必读
• references/first-principles-questions.md — 第一性原理追问完整清单（25 条）+ 场景化索引（Phase 1）
• references/code-audit-checklist.md — 代码审计清单，各维度详细检查项（Phase 2）
• references/upgrade-patterns.md — 工程升级模式库，常见迁移路径与策略（Phase 3）
• references/decision-framework.md — 重构决策框架，改与不改的判断依据（Phase 3）

踩坑经验

每次经过 2 次及以上尝试才得出正确结果时，在此处记录。格式：场景：经验要点 此区域由 AI 在实际项目分析中自动积累，请勿手动删除。

（暂无记录，随使用积累）