跳到主要内容

哲学与心态

"LeanSpec 是一种心态，而非格式。"

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

AI 协作创造的心智模型​

当 AI 协助编写Spec时（不仅仅是从Spec实施），三种心智模型指导Spec如何融入您的工作流：

Spec作为检查点（Spec-as-Checkpoint，主要模型）​

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

** 工作流：**

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

** 何时使用：**

  • 在与 AI 澄清复杂设计后
  • 在开始多阶段实施之前
  • 当准备提交到某种方法时
  • 在向前推进之前捕获决策

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

Spec作为工件（Spec-as-Artifact，正式文档）​

** 它是什么：** 超越即时工作持续存在的持久性文档。

** 目的：**

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

** 何时使用：**

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

** 示例：** 记录安全决策、PCI 合规方法和未来开发人员集成模式的支付处理Spec。

Spec作为上下文（Spec-as-Context，活文档）​

** 它是什么：** 随实施一起增长的演进上下文。

** 特征：**

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

** 何时使用：**

  • SDD 风格的迭代开发
  • 需求出现的复杂功能
  • 多次迭代的长期工作
  • 当Spec作为活跃项目记忆时

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

选择您的心智模型​

大多数Spec经历这些阶段：

  1. ** 作为检查点开始 ** - 将对话正式化为Spec
  2. ** 作为上下文演进 ** - 随着实施教会您事情而更新
  3. ** 作为工件结束 ** - 归档作为参考文档

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

** 对于 AI 辅助编写：**

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

LeanSpec 心态​

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

从为什么开始​

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

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

没有清晰的答案，工作可能不值得做。

拥抱"足够好"​

完美主义是精简Spec的敌人。

  • 快速交付"足够好"的Spec
  • 从实际工作中获得反馈
  • 根据您学到的内容进行完善
  • 持续迭代

永远不会编写的完美Spec是无价值的。让工作推进的不完美Spec是有价值的。

质疑每个字​

在编写任何内容之前，问："这会增加清晰度吗？"

如果不会，就不要写。

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

把它想成活文档​

Spec不是刻在石头上的契约。它们是演变的活指南。

  • 随着您学习更新Spec
  • 在做出决策时捕获决策
  • 反映现实，而非仅计划
  • 工作完成时归档

过时的Spec比根本没有Spec更糟糕。

为扫描而设计​

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

构建Spec以便快速理解：

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

如果有人无法在 2 分钟内理解您的Spec，它可能太长了。

核心信念​

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

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

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

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

2. 上下文胜过全面性​

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

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

3. Spec应该减轻负担，而非制造负担​

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

LeanSpec Spec应该：

  • 花几分钟阅读
  • 易于保持最新
  • 随项目演进
  • 邀请协作

4. AI 改变一切​

在 AI 辅助开发时代，Spec有双重目的：

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

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

平衡精简和完整​

目标不是写得尽可能少。目标是写 ** 必要的内容 **。

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

何时添加更多细节​

在以下情况下添加细节：

  • 复杂性要求它
  • 歧义会导致问题
  • 需要跨团队协调
  • 技术约束至关重要
  • 失败有高后果

何时削减细节​

在以下情况下削减细节：

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

AI 辅助的Spec编写​

AI 可以帮助编写Spec，而不仅仅是从Spec实施。这创造了一个协作工作流：

** 人类提供：**

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

** AI 提供：**

  • 初始结构和草稿
  • 将简短笔记扩展为部分
  • 示例和测试用例
  • 格式和组织

** 结果：** 更快的Spec创建，同时仍保持对重要内容的人类判断。AI 处理结构，人类确保清晰度和意图。

** 关键：** 第一性原理在 AI 辅助编写中 ** 更 ** 重要。没有人类审查，AI 倾向于冗长（违反信噪比 (Signal-to-Noise)）和实现焦点（违反意图优于实现 (Intent Over Implementation)）。您的角色是确保Spec保持精简和有目的。

成功标准​

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

自我检查问题​

** 上下文经济 (Context Economy)：**

  • 有人能在 5-10 分钟内阅读这个Spec吗？
  • 每个Spec文件是否少于 400 行？
  • 如果不是，是否拆分为聚焦的子 Spec？

** 信噪比：**

  • 每个句子都提供决策信息吗？
  • 我能解释每个部分实现什么决策吗？
  • 我是否削减了"好知道"与"需要知道"？

** 意图优于实现：**

  • "为什么"清晰吗？
  • 权衡是否解释了？
  • 有人能在没有我的情况下做出良好决策吗？

** 弥合差距 (Bridge the Gap)：**

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

** 渐进式披露 (Progressive Disclosure)：**

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

如果满足以下条件，您的Spec是成功的：​

✅ ** 它们被阅读 ** - 人们实际阅读它们（一直到底）
✅ ** 它们被使用 ** - 它们为实际开发工作提供信息
✅ ** 它们保持最新 ** - 随着项目演进而更新
✅ ** 它们实现自主 ** - 开发人员可以在没有持续澄清的情况下工作
✅ ** 它们促进 AI ** - AI 代理可以从中实施功能
✅ ** 它们经得起时间考验 ** - 即使在实施后仍然有用

如果满足以下条件，您的Spec正在失败：​

❌ 人们说"太长了；没读"（TL;DR）
❌ 开发人员忽略它们并请求澄清
❌ 它们很快就过时了
❌ 它们产生的问题多于答案
❌ AI 代理误解它们
❌ 初始审查后从未被引用

底线​

LeanSpec 是一种 ** 心态 **，而非格式。

专注于：

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

如果您的Spec帮助人（和 AI 代理）更快地构建更好的软件，您就在正确地做 LeanSpec。

** 下一步 **：在 AI 辅助的Spec编写 中探索实用的日常技术，或了解 LeanSpec 中的 何时编写Spec。