跳到主要内容

哲学与思维方式

"LeanSpec 是一种思维方式，而不是一种格式。"

除了第一原则之外，有效实践 LeanSpec 还需要采用关于规范应该如何工作的关键心智模型和信念。

AI 协同创作的心智模型​

当 AI 协助编写规范（而不仅仅是根据规范实现）时，三种心智模型指导规范如何融入您的工作流程：

规范作为检查点（主要模型）​

什么是：在开发对话的关键决策点形式化意图。

工作流程：

  1. 与 AI 对话 - 探索选项，澄清需求，迭代设计
  2. 识别检查点 - 当设计足够清晰可以形式化时
  3. 固化为规范 - AI 起草初始规范，人类完善
  4. 从规范继续 - 规范成为实现的契约

何时使用：

  • 与 AI 澄清复杂设计后
  • 开始多阶段实现之前
  • 准备好承诺某种方法时
  • 在继续前进之前捕获决策

示例：您与 AI 讨论 API 设计 15 分钟，澄清约束和权衡，然后在实现开始之前将商定的设计形式化为规范。

规范作为工件（正式文档）​

什么是：持续存在于即时工作之外的持久文档。

目的：

  • 未来修改的参考
  • 新团队成员的入职材料
  • 合规和审计跟踪
  • 机构知识捕获

何时使用：

  • 影响多个系统的架构决策
  • 需要合规文档的功能
  • 其他人将扩展的复杂设计
  • 需要未来参考的工作

示例：支付处理规范，记录安全决策、PCI 合规方法和集成模式，供未来开发人员参考。

规范作为上下文（活文档）​

什么是：随着实现一起发展的演进上下文。

特征：

  • 随着理解的增长迭代更新
  • 反映当前现实，而不仅仅是初始计划
  • 桥接持续的人机协作
  • 捕获学习和完善

何时使用：

  • SDD 风格的迭代开发
  • 具有新兴需求的复杂功能
  • 具有多次迭代的长期工作
  • 当规范作为活跃项目记忆时

示例：重构规范随着您发现新模式而演变，在您做出决策时记录它们，并捕获什么有效与什么无效。

选择您的心智模型​

大多数规范经历这些阶段：

  1. 从检查点开始 - 将对话形式化为规范
  2. 演变为上下文 - 随着实现教给您的东西而更新
  3. 结束为工件 - 归档为参考文档

关键见解：这些不是单独的方法——它们是规范生命周期的阶段。从简单开始（检查点），自然演变（上下文），完成为文档（工件）。

对于 AI 辅助创作：

  • AI 帮助起草检查点（构建您的想法）
  • AI 帮助维护上下文（在您学习时更新）
  • 人类确保工件质量（完善以提高清晰度）

LeanSpec 思维方式​

要有效实践 LeanSpec，请采用这些核心态度：

从为什么开始​

每个规范都应该回答："为什么这项工作存在？"

  • 我们在解决什么问题？
  • 为什么这很重要？
  • 为什么是现在？

没有明确的答案，这项工作可能不值得做。

拥抱"足够好"​

完美主义是精益规范的敌人。

  • 快速发布"足够好"的规范
  • 从实际工作中获得反馈
  • 根据学到的东西进行完善
  • 持续迭代

一个永远不写的完美规范是毫无价值的。一个推动工作前进的不完美规范是有价值的。

质疑每个词​

在写任何东西之前，问："这增加了清晰度吗？"

如果没有，就不要写。

  • 冗长的解释 → 简短、清晰的陈述
  • 详尽的边缘情况 → 仅关键场景
  • 学术形式 → 对话清晰度
  • 全面的参考 → 基本链接

将其视为活文档​

规范不是刻在石头上的契约。它们是不断发展的活指南。

  • 随着学习更新规范
  • 在做出决策时捕获它们
  • 反映现实，而不仅仅是计划
  • 工作完成后归档

过时的规范比没有规范更糟糕。

为扫描而设计​

人们（和 AI 代理）在阅读之前先扫描。

构建规范以便快速理解：

  • 使用清晰的标题
  • 保持章节简短
  • 使用要点
  • 突出显示关键信息
  • 在有帮助的地方添加视觉元素（表情符号、徽章）

如果有人不能在 2 分钟内理解您的规范，它可能太长了。

核心信念​

LeanSpec 方法由四个基础信念指导：

1. 文档是手段，而不是目的​

目标不是创建全面的文档。目标是实现有效的行动。

  • 规范的存在是为了促进理解和决策
  • 如果没有人阅读或使用规范，它就失败了——无论它有多彻底
  • 交付给用户的价值 > 文档的完整性

2. 上下文胜过全面性​

捕获某事为什么重要比详尽记录它是什么更有价值。

  • 理解问题比详细说明解决方案更重要
  • "为什么"很少改变，但"如何"不断发展
  • 上下文实现良好决策；详尽的细节很快过时

3. 规范应该减轻负担，而不是制造负担​

传统规范通常成为负担（太长无法阅读，太复杂无法维护，太僵化无法适应）。

LeanSpec 规范应该：

  • 只需几分钟就能阅读
  • 易于保持最新
  • 随项目发展
  • 邀请协作

4. AI 改变了一切​

在 AI 辅助开发时代，规范具有双重目的：

  • 人类沟通：协调团队理解
  • AI 上下文：为 AI 编码代理提供清晰方向

AI 代理从与人类相同的品质中受益：清晰、简洁的写作，具有具体示例、明确边界和可测试标准。

在精益和完整之间取得平衡​

目标不是尽可能少写。目标是写必要的量。

有些功能很复杂，需要详细的规范。这没关系。问题不是"我能把这个写得多短？"而是"理解所必需的是什么？"

何时添加更多细节​

在以下情况下添加细节：

  • 复杂性需要它
  • 模糊会导致问题
  • 需要跨团队协调
  • 技术约束至关重要
  • 失败的后果很严重

何时削减细节​

在以下情况下削减细节：

  • 对您的受众来说很明显
  • 很容易在其他地方发现
  • 在工作开始前可能会改变
  • 与核心目标无关
  • 是以后的实现细节

AI 辅助规范创作​

AI 可以帮助编写规范，而不仅仅是根据规范实现。这创建了一个协作工作流程：

人类提供：

  • 意图和上下文（"我们为什么要这样做？"）
  • 约束和权衡（"存在哪些限制？"）
  • 成功标准（"我们如何知道它完成了？"）
  • 完善和编辑（执行 LeanSpec 原则）

AI 提供：

  • 初始结构和草稿
  • 将简要说明扩展为章节
  • 示例和测试用例
  • 格式化和组织

结果：更快的规范创建，同时仍然保持人类对重要事项的判断。AI 处理结构，人类确保清晰度和意图。

关键：第一原则在 AI 辅助创作中更加重要。没有人类审查，AI 倾向于冗长（违反信噪比）和实现焦点（违反意图优于实现）。您的角色是确保规范保持精益和有目的。

成功标准​

您如何知道自己是否有效地实践 LeanSpec？

自我检查问题​

上下文经济：

  • 有人能在 5-10 分钟内阅读这个规范吗？
  • 每个规范文件是否少于 400 行？
  • 如果没有，它是否被分成了重点子规范？

信噪比：

  • 每个句子都告知一个决策吗？
  • 我能解释每个部分启用什么决策吗？
  • 我是否已经削减了"很高兴知道"与"需要知道"？

意图优于实现：

  • "为什么"清楚吗？
  • 权衡解释了吗？
  • 没有我，有人能做出好决定吗？

桥接差距：

  • 人类和 AI 都能理解这个吗？
  • 是否有清晰的结构 + 自然语言？
  • 需要的地方是否包含示例？

渐进式披露：

  • 我是否只添加了我现在需要的？
  • 我是否在解决当前的痛苦，而不是未来的"假设"？
  • 这能自然增长而不需要重写吗？

您的规范成功如果：​

✅ 它们被阅读 - 人们实际上（全程）阅读它们
✅ 它们被使用 - 它们为实际开发工作提供信息
✅ 它们保持最新 - 随着项目发展而更新
✅ 它们实现自主 - 开发人员可以在没有持续澄清的情况下工作
✅ 它们促进 AI - AI 代理可以从中实现功能
✅ 它们老化良好 - 即使在实现后仍然有用

您的规范失败如果：​

❌ 人们说"太长；没读"（too long; didn't read）
❌ 开发人员忽略它们并要求澄清
❌ 它们很快过时
❌ 它们产生的问题多于答案
❌ AI 代理误解它们
❌ 在初始审查后从未被引用

底线​

LeanSpec 是一种思维方式，而不是一种格式。

专注于：

  • 为什么优于什么
  • 清晰度优于完整性
  • 行动优于文档
  • 演变优于完美

如果您的规范帮助人们（和 AI 代理）更快地构建更好的软件，您就做对了 LeanSpec。

下一步：探索编写 AI 可执行的规范中的实用日常技术，或了解何时使用 LeanSpec。