# Vibe Coding 哲学方法论提效工具箱（Python）

> 目标：把"vibe（探索）"系统化为"可验证、可迭代、可收敛"的工程产出。
> 每个方法给出：用途 / 落地动作 / Python工具 / 可复制提示词。

## 目录

- [总体作业流](#总体作业流)
- [推荐底座](#推荐底座python)
- [方法论](#方法论)
  - [1. 现象学还原](#1-现象学还原悬置假设)
  - [2. 正反合](#2-正反合三段迭代)
  - [3. 可证伪主义](#3-可证伪主义波普尔)
  - [4. 形式化方法](#4-形式化方法轻量形式化)
  - [5. 奥卡姆剃刀](#5-奥卡姆剃刀最小复杂度)
  - [6. 实用主义](#6-实用主义以指标为准)
  - [7. 系统论/整体论](#7-系统论整体论边界与反馈回路)
  - [8. 诠释学](#8-诠释学语境澄清)
  - [9. 钢人化原则](#9-钢人化原则最强版本理解)
  - [10. 决策论/机会成本](#10-决策论机会成本可逆优先)
  - [11. 反事实推理](#11-反事实推理counterfactuals)
  - [12. 溯因推理](#12-溯因推理abduction最佳解释)
  - [13. 贝叶斯式信念更新](#13-贝叶斯式信念更新与溯因配合)
  - [14. 反思平衡](#14-反思平衡reflective-equilibrium)
  - [15. 概念分析/概念工程](#15-概念分析--概念工程)
  - [16. 方法论怀疑](#16-方法论怀疑笛卡尔式)
  - [17. 视角三角测量](#17-视角三角测量triangulation)
  - [18. 机制解释](#18-机制解释mechanistic-explanation)
  - [19. 错误认识论](#19-错误认识论error-epistemology)
  - [20. 实验哲学](#20-实验哲学x-phi)
  - [21. 计算哲学](#21-计算哲学computational-philosophy)
  - [22. 自然化认识论](#22-自然化认识论naturalized-epistemology)
  - [23. 贝叶斯认识论](#23-贝叶斯认识论bayesian-epistemology)
- [附录](#附录)
- [使用指南](#使用指南)

---

## 总体作业流

建议默认流程：

1. **现象卡片**（现象/意图/情境/边界）→ 清零脑补
2. **规格化**（类型+schema+错误语义+不变式）→ 可机器检查
3. **检查器**（单测+性质测试+lint+类型检查+关键断言）→ 可证伪
4. **最小实现**（main path）→ 快速跑通
5. **反例驱动**（Hypothesis/边界/差分/基准）→ 找到失败模式
6. **收敛重构**（删复杂度、固化概念、稳定接口、补文档）→ 可维护

---

## 推荐底座（Python）

```text
ruff + black + pyright(或 mypy) + pytest + hypothesis + pydantic(msgspec可替代)
```

---

## 方法论

### 1. 现象学还原（悬置假设）

**用途**：需求含糊、模型脑补、Bug难复现时，先把"解释/偏好"清零，回到可观察事实与可复现结构。

**落地动作**：

- 先写四件套：现象(实际) / 意图(期望) / 情境(环境约束) / 边界(明确不做)
- 输出最小可复现体 MRE：最小输入 + 最小脚本 + 复现步骤 + 预期vs实际
- 把抽象词降维：快/稳/好用 → 指标&验收用例

**Python工具**：`pytest`（MRE脚本）、日志、最小数据样例

**提示词**：

```text
先做现象学还原：不要推测原因。输出：现象/意图/情境/边界/未确定项/MRE；然后再给最小修复与测试。
```

---

### 2. 正反合（三段迭代）

**用途**：把一次性"写到完美"替换为可控三轮：快速可用 → 反例打脸 → 收敛为工程版本。

**落地动作**：

- **正**：只做 main path，让它跑通
- **反**：列失败模式（边界/空值/并发/权限/超时/性能），用测试与基准逼出反例
- **合**：重构接口/收敛依赖/补文档与回归，形成下一轮稳定起点

**Python工具**：`pytest` + `hypothesis` + `ruff/black` + profiling/benchmark

**提示词**：

```text
按正反合输出：1)最小可运行实现 2)反例与失败模式+测试 3)综合后的重构方案与最终代码。
```

---

### 3. 可证伪主义（波普尔）

**用途**：把"看起来对"变成"暂时无法证伪"；显著降低隐藏 bug。

**落地动作**：

- 每个关键断言都要配一个能让它失败的测试（边界/随机/反例）
- 优先性质测试而非只写示例测试

**Python工具**：`hypothesis`（性质/模糊）、`pytest`

**提示词**：

```text
为该实现列出 5 个可证伪点，并为每个点写一个最小测试（优先 Hypothesis 性质测试）。
```

---

### 4. 形式化方法（轻量形式化）

**用途**：减少非法状态、约束模型输出、让行为可检查可累积。

**落地动作**：

- **先规格**：类型 + schema + 不变式 + 错误集合（异常或 error object）+ 复杂度约束（可选）
- **再检查器**：类型检查 + 运行时校验 + 断言/契约 + 性质测试
- **最后实现**：逐条映射规格（谁保证哪条约束）

**Python工具**：

- `typing`（Literal/NewType/Protocol/TypedDict/Annotated）
- `pyright/mypy`
- `pydantic/msgspec`（输入输出校验）
- `assert` / `icontract` / `deal`
- `pytest` + `hypothesis`

**提示词**：

```text
先输出形式化规格（类型/schema/不变式/错误语义），再给至少 3 条 Hypothesis 性质测试，最后写实现并逐条说明满足关系。
```

---

### 5. 奥卡姆剃刀（最小复杂度）

**用途**：避免模型引入不必要框架/抽象；提升可维护性与迭代速度。

**落地动作**：

- 要求两套方案：常规版 vs 简化版；以测试为准删复杂度
- 优先标准库、减少依赖、减少可变状态、减少层级

**Python工具**：`ruff`（复杂度/风格）、依赖审计（requirements最小化）

**提示词**：

```text
在满足全部测试与验收的前提下，把实现复杂度删掉 30%：减少依赖、状态和抽象层，并解释删减理由。
```

---

### 6. 实用主义（以指标为准）

**用途**：避免"优化方向漂移"；每轮明确一个可量化目标。

**落地动作**：

- 先定义成功指标（P95延迟/错误率/成本/内存/可维护性）
- 每轮只优化一个指标；其余保持不退化（用基准/回归锁住）

**Python工具**：`pytest-benchmark` 或简单计时；日志与指标；回归测试

**提示词**：

```text
把需求转成指标与验收阈值，并给出测量方法；本轮只优化 X 指标，保证其它指标不退化。
```

---

### 7. 系统论/整体论（边界与反馈回路）

**用途**：复杂系统容易在耦合点失控；缩短反馈回路提效最大。

**落地动作**：

- 先画数据流/依赖边界：I/O 放边缘，核心逻辑保持纯函数
- 优先解耦高耦合点；把慢依赖换成桩/模拟以加速测试

**Python工具**：依赖注入（轻量）、`pytest fixtures`、纯函数设计

**提示词**：

```text
画出数据流与依赖边界，指出最高耦合点与最短反馈回路改造方案；给出可测试的纯函数核心与 I/O 适配层。
```

**扩展阅读**：

- [`控制论与科学方法论`](./控制论与科学方法论.md) - 用“可能性空间/反馈/信息/黑箱/可证伪”解释从试错到收敛的机制

---

### 8. 诠释学（语境澄清）

**用途**：需求文本有歧义，模型与人对同一词理解不同。

**落地动作**：

- 先复述需求 + 歧义清单 + 默认选择（必须显式）
- 默认选择写入 docstring/README/类型定义

**Python工具**：docstring、类型与 schema 固化默认

**提示词**：

```text
先复述需求并列出所有歧义点；对每个歧义给默认策略与理由；确认后再写实现与测试。
```

---

### 9. "钢人化"原则（最强版本理解）

**用途**：减少无效争论/误解；让重构建议更贴近原意图。

**落地动作**：

- 先把现有方案表达成最强版本（目标、约束、权衡）
- 再提出改进（保留其优势，指出代价）

**Python工具**：PR描述结构化（优点/风险/替代方案）

**提示词**：

```text
先钢人化现有实现：列出它的最佳解释与优点；再给改进方案并明确代价与风险。
```

---

### 10. 决策论/机会成本（可逆优先）

**用途**：避免过早做不可逆技术决策（换框架/改数据模型）。

**落地动作**：

- 标注决策：可逆 vs 不可逆；优先做可逆高价值项
- 先写接口+测试桩+适配层，延后绑定外部系统

**Python工具**：抽象边界、adapter、in-memory 实现

**提示词**：

```text
把方案拆成可逆/不可逆决策；先给可逆路径的 MVP，实现通过测试；不可逆部分只给接口与占位实现。
```

---

### 11. 反事实推理（Counterfactuals）

**用途**：系统性覆盖异常路径，降低线上事故。

**落地动作**：

- 问"如果 X 不成立会怎样"：超时、乱序、重复、空值、弱网、权限缺失、时钟漂移
- 把反事实转成测试矩阵与降级策略

**Python工具**：`pytest` 参数化、`hypothesis` 生成器、超时与重试控制

**提示词**：

```text
列出 15 个反事实场景并按风险排序；为 Top5 写测试与降级/错误语义。
```

---

### 12. 溯因推理（Abduction，最佳解释）

**用途**：debug/性能退化时，比穷举更快定位"最可能原因"。

**落地动作**：

- 列候选原因 → 为每个原因写最便宜的区分性实验（日志点/开关/最小基准）
- 用证据淘汰而不是凭感觉改代码

**Python工具**：结构化日志、trace、最小 benchmark、feature flag

**提示词**：

```text
给出候选原因列表，并为每个原因提供一个最低成本、最高区分度的验证实验与预期观察。
```

---

### 13. 贝叶斯式信念更新（与溯因配合）

**用途**：在不确定下理性分配排查时间。

**落地动作**：

- 给假设先验（高/中/低）→ 实验后更新后验排序
- 只对后验最高的 1-2 个假设投入修改成本

**Python工具**：同 12；加一张"假设-证据"表

**提示词**：

```text
按先验排序原因；给最信息增益实验；根据可能结果更新排序并给下一步。
```

---

### 14. 反思平衡（Reflective equilibrium）

**用途**：当用例、原则、约束冲突时收敛规范（尤其 API 语义、错误处理、兼容性）。

**落地动作**：

- 三层对齐：具体用例 ↔ 一般原则 ↔ 系统约束
- 用测试固化：回归用例（具体判断）+ 性质测试（原则）

**Python工具**：`pytest` + `hypothesis`；规范文档（错误模型/幂等语义）

**提示词**：

```text
列出用例/原则/约束三集，指出冲突点；给两轮调整方案，每轮说明要改哪些用例、原则或实现以达成一致。
```

---

### 15. 概念分析 / 概念工程

**用途**：防止术语漂移导致返工；把领域概念固化进代码。

**落地动作**：

- 概念表：术语/定义/边界/不变量/转换关系
- 概念工程：用 Enum/Literal/NewType/dataclass(frozen) 与 schema 固化边界；禁止混用

**Python工具**：`Enum`、`Literal`、`NewType`、`pydantic` 校验

**提示词**：

```text
先产出概念表；再映射成 Python 类型与 schema；给 5 个应被拒绝的反例输入，并写对应测试。
```

---

### 16. 方法论怀疑（笛卡尔式）

**用途**：把不可靠前提当事实是 vibe coding 常见事故源。

**落地动作**：

- 对关键前提标注：是否可验证
- 不可验证 → 必须加运行时校验/超时/重试/降级；并写会失败的测试

**Python工具**：`assert`/校验器、超时、重试、容错分支测试

**提示词**：

```text
列出该方案依赖的所有前提，并标注可验证性；对不可验证前提添加防线（校验/超时/降级）与对应测试。
```

---

### 17. 视角三角测量（Triangulation）

**用途**：减少单一证据的误判；提升结论可靠性。

**落地动作**：

- 同一结论至少两种证据：单测/性质测试 + 日志/指标；或差分测试 + fuzz

**Python工具**：`pytest`/`hypothesis` + metrics/logging；差分对照

**提示词**：

```text
对关键行为给出至少两种独立验证方式，并说明各自盲区与如何互补。
```

---

### 18. 机制解释（Mechanistic explanation）

**用途**：把"能跑"变成"可解释可维护"；降低未来修改风险。

**落地动作**：

- 要求输出数据流：输入 → 中间状态 → 输出
- 对中间状态写不变式/断言；把解释与代码结构对齐

**Python工具**：`assert`、类型收窄、分层函数、docstring

**提示词**：

```text
给出机制解释：数据在系统中如何流动；列出每个中间状态的不变式，并在代码中用断言或类型保证。
```

---

### 19. 错误认识论（Error epistemology）

**用途**：系统化"我们会如何错"，比事后补洞更省。

**落地动作**：

- 先做失败模式清单（空值/乱序/重复/并发/权限/超时/编码/浮点等）
- 每类至少一个测试；明确错误语义（raise / error object / log+metric）

**Python工具**：`pytest` 参数化 + `hypothesis`；统一 error 模型

**提示词**：

```text
生成失败模式清单并按风险排序；为 Top N 写测试；统一错误模型并给出示例响应/异常层级。
```

---

### 20. 实验哲学（x-phi）

**用途**：交互与默认策略别靠直觉，用数据决定。

**落地动作**：

- 把争议点改成可测实验（A/B 默认值、错误文案、重试策略）
- 指标：误用率、重试率、成功率、工单率、完成时间

**Python工具**：埋点/日志、简单 A/B 分组、配置开关

**提示词**：

```text
把该设计争议转成实验：分组、指标、样本、持续时间、判定阈值；给出埋点字段与分析方法。
```

---

### 21. 计算哲学（Computational philosophy）

**用途**：复杂状态与规则用"可运行模型/仿真/搜索"代替纯讨论。

**落地动作**：

- reference 实现（慢但清晰）作为 oracle
- optimized 实现（快/工程化）用差分测试锁死行为
- 用仿真/生成器自动探索边界

**Python工具**：`hypothesis`、差分测试、状态机测试（Hypothesis stateful）

**提示词**：

```text
先写 reference（清晰）+ optimized（高效）；写差分测试与状态机/性质测试自动找反例并修复。
```

---

### 22. 自然化认识论（Naturalized epistemology）

**用途**：承认人类/模型都有系统性偏误，用流程与工具把偏误外包给检查器。

**落地动作**：

- 默认自动化：lint+format+类型检查+测试
- 高风险路径：必须性质测试/模糊测试/运行时校验
- 结论至少双证据（测试+指标）

**Python工具**：`ruff`/`black`/`pyright`/`pytest`/`hypothesis`/`pydantic`

**提示词**：

```text
列出该任务最常见的误判点，并为每个误判点给一个自动化防线（检查器/测试/断言/埋点）。
```

---

### 23. 贝叶斯认识论（Bayesian epistemology）

**用途**：在多个方案/原因间理性分配注意力与试错预算。

**落地动作**：

- 先验 → 实验 → 后验 → 下一步；把排查变成序列决策问题

**Python工具**：同 12/13；记录表

**提示词**：

```text
用贝叶斯式流程组织排查：先验排序、信息增益最高的实验、更新后的行动计划。
```

---

## 附录

### 通用"性质测试"提示（可复用）

| 性质 | 说明 |
|:---|:---|
| 非负性/有界性 | 结果不越界 |
| 幂等性 | `f(f(x)) == f(x)` |
| 单调性 | 输入增大输出不违反预期 |
| 守恒性 | 长度/集合元素/总和按规则变化 |
| 互逆性 | `decode(encode(x)) == x`（或近似） |
| 稳定性 | 排序/去重等操作满足稳定条件 |
| 交换/结合 | 满足代数性质的操作应通过 |

### 建议的项目框架（最小）

```text
src/           # 纯逻辑与 I/O 分离
tests/         # 示例+性质+差分
pyproject.toml # ruff/pytest/pyright
README.md      # 概念表/错误语义/验收指标
```

---

## 使用指南

| 场景 | 推荐方法组合 |
|:---|:---|
| 需求不清 | 1（现象学）+ 8（诠释学）+ 15（概念工程） |
| 质量不稳 | 3（可证伪）+ 4（形式化）+ 19（错误认识论） |
| 排错提效 | 12（溯因）+ 13/23（贝叶斯更新）+ 17（三角测量） |
| 复杂系统 | 7（系统论）+ 21（计算哲学）+ 14（反思平衡） |
| 交互默认争议 | 20（x-phi）+ 6（实用主义指标） |