tradecatlabs
25 KiB
方法论工具箱
现象学还原、正反合、可证伪主义、形式化方法等提效工具。
目标：把"vibe（探索）"系统化为"可验证、可迭代、可收敛"的工程产出。 每个方法给出：用途 / 落地动作 / Python工具 / 可复制提示词。
目录定位
philosophy/ 存放哲学方法论、思维模型、编程哲学和底层认知模型。它回答的不是“下一步命令是什么”，而是“为什么这样判断、如何减少幻觉、如何让复杂问题可描述、可推理、可验证”。
适合：
- 需要提升问题抽象、系统理解和长期工程判断的人。
- 需要为 AI Agent 提供更稳定认知框架的任务。
- 已经掌握入门流程，希望把经验沉淀成可迁移方法的人。
怎么选
| 目标 | 先读 |
|---|---|
| 想快速获得可复用认知工具 | 思维模型 |
| 想描述复杂系统的对象、状态和变化 | 组合描述模型 |
| 想理解代码、结构、状态和复杂度 | 编程之道 |
| 想理解真实工程里的需求、维护、质量、权衡和协作 | 软件工程的朴素真理 |
| 想把探索过程变成可验证工程流程 | 本文件的方法论工具箱 |
相关文档
- 思维模型 - 第一性原理、奥卡姆剃刀、网络效应、多阶思维、状态空间等可复用认知工具。
- 编程之道 - 用更抽象的方式理解代码、结构、状态、复杂度与工程判断。
- 软件工程的朴素真理 - 用底层常识理解代码、复杂度、需求、维护、质量、架构与团队。
- 组合描述模型 - 对象、状态、快照、序列、过程、变换、同一/差异与关系。
目录
总体作业流
建议默认流程：
- 现象卡片（现象/意图/情境/边界）→ 清零脑补
- 规格化（类型+schema+错误语义+不变式）→ 可机器检查
- 检查器（单测+性质测试+lint+类型检查+关键断言）→ 可证伪
- 最小实现（main path）→ 快速跑通
- 反例驱动（Hypothesis/边界/差分/基准）→ 找到失败模式
- 收敛重构（删复杂度、固化概念、稳定接口、补文档）→ 可维护
推荐底座（Python）
ruff + black + pyright(或 mypy) + pytest + hypothesis + pydantic(msgspec可替代)
方法论
1. 现象学还原（悬置假设）
用途：需求含糊、模型脑补、Bug难复现时，先把"解释/偏好"清零，回到可观察事实与可复现结构。
落地动作：
- 先写四件套：现象(实际) / 意图(期望) / 情境(环境约束) / 边界(明确不做)
- 输出最小可复现体 MRE：最小输入 + 最小脚本 + 复现步骤 + 预期vs实际
- 把抽象词降维：快/稳/好用 → 指标&验收用例
Python工具：pytest（MRE脚本）、日志、最小数据样例
提示词：
先做现象学还原：不要推测原因。输出：现象/意图/情境/边界/未确定项/MRE；然后再给最小修复与测试。
2. 正反合（三段迭代）
用途：把一次性"写到完美"替换为可控三轮：快速可用 → 反例打脸 → 收敛为工程版本。
落地动作：
- 正：只做 main path，让它跑通
- 反：列失败模式（边界/空值/并发/权限/超时/性能），用测试与基准逼出反例
- 合：重构接口/收敛依赖/补文档与回归，形成下一轮稳定起点
Python工具：pytest + hypothesis + ruff/black + profiling/benchmark
提示词：
按正反合输出：1)最小可运行实现 2)反例与失败模式+测试 3)综合后的重构方案与最终代码。
3. 可证伪主义（波普尔）
用途：把"看起来对"变成"暂时无法证伪"；显著降低隐藏 bug。
落地动作：
- 每个关键断言都要配一个能让它失败的测试（边界/随机/反例）
- 优先性质测试而非只写示例测试
Python工具：hypothesis（性质/模糊）、pytest
提示词：
为该实现列出 5 个可证伪点，并为每个点写一个最小测试（优先 Hypothesis 性质测试）。
4. 形式化方法（轻量形式化）
用途：减少非法状态、约束模型输出、让行为可检查可累积。
落地动作：
- 先规格：类型 + schema + 不变式 + 错误集合（异常或 error object）+ 复杂度约束（可选）
- 再检查器：类型检查 + 运行时校验 + 断言/契约 + 性质测试
- 最后实现：逐条映射规格（谁保证哪条约束）
Python工具：
typing（Literal/NewType/Protocol/TypedDict/Annotated）pyright/mypypydantic/msgspec（输入输出校验）assert/icontract/dealpytest+hypothesis
提示词：
先输出形式化规格（类型/schema/不变式/错误语义），再给至少 3 条 Hypothesis 性质测试，最后写实现并逐条说明满足关系。
5. 奥卡姆剃刀（最小复杂度）
用途：避免模型引入不必要框架/抽象；提升可维护性与迭代速度。
落地动作：
- 要求两套方案：常规版 vs 简化版；以测试为准删复杂度
- 优先标准库、减少依赖、减少可变状态、减少层级
Python工具：ruff（复杂度/风格）、依赖审计（requirements最小化）
提示词：
在满足全部测试与验收的前提下，把实现复杂度删掉 30%：减少依赖、状态和抽象层，并解释删减理由。
6. 实用主义（以指标为准）
用途：避免"优化方向漂移"；每轮明确一个可量化目标。
落地动作：
- 先定义成功指标（P95延迟/错误率/成本/内存/可维护性）
- 每轮只优化一个指标；其余保持不退化（用基准/回归锁住）
Python工具：pytest-benchmark 或简单计时；日志与指标；回归测试
提示词：
把需求转成指标与验收阈值，并给出测量方法；本轮只优化 X 指标，保证其它指标不退化。
7. 系统论/整体论（边界与反馈回路）
用途：复杂系统容易在耦合点失控；缩短反馈回路提效最大。
落地动作：
- 先画数据流/依赖边界：I/O 放边缘，核心逻辑保持纯函数
- 优先解耦高耦合点；把慢依赖换成桩/模拟以加速测试
Python工具：依赖注入（轻量）、pytest fixtures、纯函数设计
提示词：
画出数据流与依赖边界，指出最高耦合点与最短反馈回路改造方案；给出可测试的纯函数核心与 I/O 适配层。
扩展阅读：
- 控制论与科学方法论 - 用“可能性空间/反馈/信息/黑箱/可证伪”解释从试错到收敛的机制
8. 诠释学（语境澄清）
用途：需求文本有歧义，模型与人对同一词理解不同。
落地动作：
- 先复述需求 + 歧义清单 + 默认选择（必须显式）
- 默认选择写入 docstring/README/类型定义
Python工具：docstring、类型与 schema 固化默认
提示词：
先复述需求并列出所有歧义点；对每个歧义给默认策略与理由；确认后再写实现与测试。
9. "钢人化"原则（最强版本理解）
用途：减少无效争论/误解；让重构建议更贴近原意图。
落地动作：
- 先把现有方案表达成最强版本（目标、约束、权衡）
- 再提出改进（保留其优势，指出代价）
Python工具：PR描述结构化（优点/风险/替代方案）
提示词：
先钢人化现有实现：列出它的最佳解释与优点；再给改进方案并明确代价与风险。
10. 决策论/机会成本（可逆优先）
用途：避免过早做不可逆技术决策（换框架/改数据模型）。
落地动作：
- 标注决策：可逆 vs 不可逆；优先做可逆高价值项
- 先写接口+测试桩+适配层，延后绑定外部系统
Python工具：抽象边界、adapter、in-memory 实现
提示词：
把方案拆成可逆/不可逆决策；先给可逆路径的 MVP，实现通过测试；不可逆部分只给接口与占位实现。
11. 反事实推理（Counterfactuals）
用途：系统性覆盖异常路径，降低线上事故。
落地动作：
- 问"如果 X 不成立会怎样"：超时、乱序、重复、空值、弱网、权限缺失、时钟漂移
- 把反事实转成测试矩阵与降级策略
Python工具：pytest 参数化、hypothesis 生成器、超时与重试控制
提示词：
列出 15 个反事实场景并按风险排序；为 Top5 写测试与降级/错误语义。
12. 溯因推理（Abduction，最佳解释）
用途：debug/性能退化时，比穷举更快定位"最可能原因"。
落地动作：
- 列候选原因 → 为每个原因写最便宜的区分性实验（日志点/开关/最小基准）
- 用证据淘汰而不是凭感觉改代码
Python工具：结构化日志、trace、最小 benchmark、feature flag
提示词：
给出候选原因列表，并为每个原因提供一个最低成本、最高区分度的验证实验与预期观察。
13. 贝叶斯式信念更新（与溯因配合）
用途：在不确定下理性分配排查时间。
落地动作：
- 给假设先验（高/中/低）→ 实验后更新后验排序
- 只对后验最高的 1-2 个假设投入修改成本
Python工具：同 12；加一张"假设-证据"表
提示词：
按先验排序原因；给最信息增益实验；根据可能结果更新排序并给下一步。
14. 反思平衡（Reflective equilibrium）
用途：当用例、原则、约束冲突时收敛规范（尤其 API 语义、错误处理、兼容性）。
落地动作：
- 三层对齐：具体用例 ↔ 一般原则 ↔ 系统约束
- 用测试固化：回归用例（具体判断）+ 性质测试（原则）
Python工具：pytest + hypothesis；规范文档（错误模型/幂等语义）
提示词：
列出用例/原则/约束三集，指出冲突点；给两轮调整方案，每轮说明要改哪些用例、原则或实现以达成一致。
15. 概念分析 / 概念工程
用途：防止术语漂移导致返工；把领域概念固化进代码。
落地动作：
- 概念表：术语/定义/边界/不变量/转换关系
- 概念工程：用 Enum/Literal/NewType/dataclass(frozen) 与 schema 固化边界；禁止混用
Python工具：Enum、Literal、NewType、pydantic 校验
提示词：
先产出概念表；再映射成 Python 类型与 schema；给 5 个应被拒绝的反例输入，并写对应测试。
16. 方法论怀疑（笛卡尔式）
用途：把不可靠前提当事实是 vibe coding 常见事故源。
落地动作：
- 对关键前提标注：是否可验证
- 不可验证 → 必须加运行时校验/超时/重试/降级；并写会失败的测试
Python工具：assert/校验器、超时、重试、容错分支测试
提示词：
列出该方案依赖的所有前提，并标注可验证性；对不可验证前提添加防线（校验/超时/降级）与对应测试。
17. 视角三角测量（Triangulation）
用途：减少单一证据的误判；提升结论可靠性。
落地动作：
- 同一结论至少两种证据：单测/性质测试 + 日志/指标；或差分测试 + fuzz
Python工具：pytest/hypothesis + metrics/logging；差分对照
提示词：
对关键行为给出至少两种独立验证方式，并说明各自盲区与如何互补。
18. 机制解释（Mechanistic explanation）
用途：把"能跑"变成"可解释可维护"；降低未来修改风险。
落地动作：
- 要求输出数据流：输入 → 中间状态 → 输出
- 对中间状态写不变式/断言；把解释与代码结构对齐
Python工具：assert、类型收窄、分层函数、docstring
提示词：
给出机制解释：数据在系统中如何流动；列出每个中间状态的不变式，并在代码中用断言或类型保证。
19. 错误认识论（Error epistemology）
用途：系统化"我们会如何错"，比事后补洞更省。
落地动作：
- 先做失败模式清单（空值/乱序/重复/并发/权限/超时/编码/浮点等）
- 每类至少一个测试；明确错误语义（raise / error object / log+metric）
Python工具：pytest 参数化 + hypothesis；统一 error 模型
提示词：
生成失败模式清单并按风险排序；为 Top N 写测试；统一错误模型并给出示例响应/异常层级。
20. 实验哲学（x-phi）
用途：交互与默认策略别靠直觉，用数据决定。
落地动作：
- 把争议点改成可测实验（A/B 默认值、错误文案、重试策略）
- 指标：误用率、重试率、成功率、工单率、完成时间
Python工具：埋点/日志、简单 A/B 分组、配置开关
提示词：
把该设计争议转成实验：分组、指标、样本、持续时间、判定阈值；给出埋点字段与分析方法。
21. 计算哲学（Computational philosophy）
用途：复杂状态与规则用"可运行模型/仿真/搜索"代替纯讨论。
落地动作：
- reference 实现（慢但清晰）作为 oracle
- optimized 实现（快/工程化）用差分测试锁死行为
- 用仿真/生成器自动探索边界
Python工具：hypothesis、差分测试、状态机测试（Hypothesis stateful）
提示词：
先写 reference（清晰）+ optimized（高效）；写差分测试与状态机/性质测试自动找反例并修复。
22. 自然化认识论（Naturalized epistemology）
用途：承认人类/模型都有系统性偏误，用流程与工具把偏误外包给检查器。
落地动作：
- 默认自动化：lint+format+类型检查+测试
- 高风险路径：必须性质测试/模糊测试/运行时校验
- 结论至少双证据（测试+指标）
Python工具：ruff/black/pyright/pytest/hypothesis/pydantic
提示词：
列出该任务最常见的误判点，并为每个误判点给一个自动化防线（检查器/测试/断言/埋点）。
23. 贝叶斯认识论（Bayesian epistemology）
用途：在多个方案/原因间理性分配注意力与试错预算。
落地动作：
- 先验 → 实验 → 后验 → 下一步；把排查变成序列决策问题
Python工具：同 12/13；记录表
提示词：
用贝叶斯式流程组织排查：先验排序、信息增益最高的实验、更新后的行动计划。
附录
通用"性质测试"提示（可复用）
| 性质 | 说明 |
|---|---|
| 非负性/有界性 | 结果不越界 |
| 幂等性 | f(f(x)) == f(x) |
| 单调性 | 输入增大输出不违反预期 |
| 守恒性 | 长度/集合元素/总和按规则变化 |
| 互逆性 | decode(encode(x)) == x（或近似） |
| 稳定性 | 排序/去重等操作满足稳定条件 |
| 交换/结合 | 满足代数性质的操作应通过 |
建议的项目框架（最小）
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（实用主义指标） |
现象学还原用于 Vibe Coding
核心目的：把“我以为需求是这样”从对话里剥离出去，只留下可观察、可复现、可检验的事实与体验结构，让模型在更少臆测的前提下产出可用代码。
工程语境下的三个动作：
- 悬置：暂时不采纳任何原因解释、业务推断或最佳实践偏好，只记录发生了什么、期望是什么、约束是什么。
- 还原：把问题还原到“给定输入 -> 经过过程 -> 得到输出”的最小结构，先不谈架构、模式、技术栈优雅与否。
- 意向性：明确这个功能是为谁、在什么情境下、要达成什么体验；不要停在“做个登录”，要落到“用户在弱网下也能在 2 秒内完成登录并得到明确反馈”。
适用场景：
- 需求描述充满抽象词：快、稳定、像某某一样、智能、顺滑。
- 模型开始自带设定：自己补产品逻辑、乱选框架、擅自加复杂度。
- Bug 复现困难：偶发、环境相关、输入边界不清。
操作流程：
- 先清空解释，只保留现象：现象、意图、情境、边界。
- 产出最小可复现体：最小输入、最小代码片段、明确复现步骤、预期 vs 实际。
- 把抽象词降维成可测指标：快 -> P95 延迟，稳定 -> 错误率，好用 -> 交互反馈与可恢复性。
可复制提示词：
请先做“现象学还原”：不要推测原因、不要引入额外功能。
只根据我给的信息，输出：
1) 现象（可观察事实）
2) 意图（我想要的可观察结果）
3) 情境（环境/约束）
4) 未确定项（必须问清或需要我补的最小信息）
5) 最小可复现步骤（MRE）
然后再给出最小修复方案与对应测试。
口诀：先悬置解释，再固定现象；先写验收标准，再让模型写实现。
辩证法用于 Vibe Coding：正反合
把辩证法的“正反合”用于 Vibe Coding，就是把每次写代码都当成一轮可控的三段论。
正：当前状态，先跑通
- 让模型按直觉快速给出最顺的实现。
- 目标只有一个：尽快跑通主路径。
反：审计与调优，再打脸
- 立刻站在挑刺者视角反驳它。
- 列出失败模式、边界条件、性能与安全隐患。
- 用测试、类型、lint、基准把反驳落地。
合：根据审核修正，再收敛
- 把速度与约束合起来。
- 重构接口、收敛依赖、补齐测试与文档。
- 形成下一轮更稳定的起点。
实践口诀：先顺写 -> 再打脸 -> 再收敛。
一句话：Vibe 负责生成可能性，正反合负责把可能性变成工程确定性。
控制论与科学方法论
控制论视角下，工程实践不是一次性生成，而是通过信息、反馈和约束持续收缩可能性空间。
核心要点：
- 控制的逻辑起点是被控对象存在多种可能状态；控制的本质是通过选择手段，让可能性空间朝目标状态收缩。
- 改造世界的实践，本质是在多维可能性空间中选择物质、条件和时机，最终把低概率组合实现为确定结果。
- 控制能力可以理解为控制前后可能性空间大小之比；任何工具或方法都有能力上限。
- 负反馈通过比较现状与目标的差距并采取行动缩小差距，把有限的单次控制能力累积放大。
- 正反馈会自我增强，使状态持续偏离初始平衡点，可能导致增长、演化、崩溃或恶性循环。
- 信息是对系统不确定性的减少；控制要实现，必须先获得足够信息。
- 控制与信息是一体两面：信息改变认知状态，控制改变现实状态。
- 组织是一种结构状态，组织化程度越高，结构中包含的信息量越高。
- 复杂系统的因果关系常常是概率因果、反馈环和因果网络，而不是单一线性链条。
- 有效分析必须建立“相对孤立系统”，把无限问题切成有限问题。
- 拥有内部反馈回路的系统会趋向稳态结构，用动态平衡抵御外部随机干扰。
- 系统演化通常是旧稳态被破坏，经过不稳定过渡，落入新稳态。
- 自组织系统会在没有外部指令时，由内部相互作用从无序涌现出宏观有序。
- 质变可以是渐变，也可以是飞跃；关键不在变化速度，而在中间状态是否稳定。
- 黑箱认识依赖输入控制与输出观察，理论就是对黑箱内部结构的模型。
- 认识过程是“实践 -> 理论 -> 实践”的负反馈循环，用模型预测与现实输出的差异修正模型。
- 认识反馈能否收敛，取决于理论是否可证伪、反馈速度是否足够快、反馈幅度是否不过度、实践结果是否能可靠判别理论真伪。
- 科学规律的本质是变量之间的约束关系；掌握规律，就是把不可控随机变量转成可预测、可控制的确定结果。
用于 AI 编程时，这套方法可以压缩成一句话：
先把目标写成可检验状态，再用测试、日志、反馈、约束和迭代，把模型输出从可能性空间中逐步收缩到可验收结果。