跳到主要内容

理解 LeanSpec

"最好的规范是被阅读、理解和执行的规范——无论是人类还是 AI。"

LeanSpec 是一种思维方式和方法论，用于编写在 AI 驱动的开发中实际使用的规范。它建立在不可变的约束（物理、生物、经济）之上，旨在弥合人类意图与机器执行之间的差距。

什么是 LeanSpec？​

LeanSpec 是：

  • 基于约束的方法论，用于编写适合工作记忆的规范
  • 桥梁，连接人类意图和 AI 代理执行
  • 上下文工程实践，用于管理 AI 工作记忆
  • 持久记忆层，为 AI 代理跨会话提供持久化
  • 敏捷方法：从小处开始，迭代，专注于结果

LeanSpec 提供：

  • 用于创建和管理规范的 CLI 工具
  • 用于项目管理的结构化前置元数据（状态、标签、依赖关系）
  • MCP 服务器集成，供 AI 代理访问
  • 用于管理复杂性的子规范文件
  • 验证和项目健康跟踪

LeanSpec 解决的问题​

传统规范失败​

传统规范由于可预测的原因而失败：

  • 太长 → 没人读（违反工作记忆限制）
  • 太详细 → 很快就过时（维护负担）
  • 太僵化 → 无法随着理解的增长而适应（过早的结构）
  • 太正式 → 阻碍协作（摩擦超过价值）

这些不是流程失败——它们是约束违规。

AI 驱动开发的差距​

在 AI 辅助开发中，出现了一个新挑战：

  • 人类以目标和上下文思考（"使仪表板变快"）
  • AI 需要清晰、明确的指令（"使用 Redis 缓存，p95 <100ms"）
  • 必须弥合差距，否则 AI 会产生幻觉、误解或反复询问

传统文档无法弥合这一差距，因为它要么：

  • 对 AI 执行来说太模糊（高层战略文档）
  • 对人类阅读来说太详细（全面的 API 参考）
  • 没有为 AI 检索结构化（没有示例/标准的散文）

为什么现有解决方案不足​

为什么不只使用任务单/问题？

  • 对复杂功能来说太简短（没有理由、约束或权衡）
  • 对 AI 代理没有持久记忆（每个会话都重新开始）
  • 难以在多个问题之间维护上下文

为什么不使用全面的文档？

  • 太长而无法适应 AI 上下文窗口（常见 >10k 行）
  • 太正式和详尽（违反信噪比）
  • 维护负担随规模扩展（变得过时）

为什么不只与 AI 聊天？

  • 上下文是短暂的（会话之间丢失）
  • 没有决策的持久记录
  • 无法扩展到团队协作
  • 需要反复重新解释上下文

LeanSpec 解决方案​

LeanSpec 有效是因为它与人类和 AI 的实际工作方式一致：

1. 尊重基本约束​

基于三个不可变的约束：

  • 物理：上下文窗口是有限的（即使有 1M+ 令牌）
  • 生物：工作记忆很小（~7 项，5-10 分钟注意力）
  • 经济：时间和令牌成本金钱

→ 上下文经济：规范必须适合工作记忆（<400 行）

2. 弥合人类和 AI 的理解​

为两个受众编写规范：

  • 对人类：清晰的问题、理由、权衡（为什么重要）
  • 对 AI：结构化需求、示例、成功标准（要构建什么）
  • 两者都获得：他们可以解析的自然语言 + 结构化数据

→ 弥合差距：使人类意图与机器执行对齐

3. 作为持久记忆​

规范作为 AI 代理的语义记忆：

  • 决策和理由跨会话持久化
  • MCP 服务器实现可靠检索
  • 交叉引用创建知识图谱
  • 更新保持记忆最新

→ AI 代理记忆：超越聊天会话的上下文

4. 应用上下文工程​

主动管理 AI 工作记忆：

  • 分区（当 >400 行时拆分为子规范）
  • 压缩（删除冗余）
  • 压缩（总结已完成的阶段）
  • 隔离（分离不相关的关注点）

→ 上下文工程：在上下文失败发生之前预防它们

5. 拥抱渐进式披露​

从简单开始，仅在感到痛苦时添加结构：

  • 独立开发：仅状态 + 创建日期
  • 小团队：添加标签、优先级
  • 企业：添加受让人、史诗、冲刺

→ 渐进式披露：没有过早的抽象

何时使用 LeanSpec​

LeanSpec 是为 AI 驱动的 SDD（规范驱动开发） 设计的。当它有助于弥合人类意图到机器执行时编写规范。当差距已经清楚时跳过它。

编写规范时...​

🎯 意图需要澄清：

  • 存在多个有效的解释
  • 权衡或约束不明显
  • "为什么"与"是什么"一样重要
  • 需要记录决策

🤖 AI 将实现：

  • AI 代理需要可执行的上下文
  • 成功标准必须明确
  • 约束无法从代码推断
  • 实现路径需要缩小

🏗️ 工作很重要：

  • 触及系统的多个部分
  • 架构或结构性变化
  • 破坏性变化或重大重构
  • 跨系统依赖

📚 需要捕获知识：

  • 研究发现和权衡
  • 技术探索或实验
  • 回顾（什么有效，什么无效）
  • 未来参考的决策

示例：

  • 使用 AI 实现的新功能
  • 影响多个使用者的 API 设计
  • 架构决策（微服务 vs 单体）
  • 重大重构（不是简单的重命名）
  • 记录发现的研究尖峰

跳过规范时...​

✂️ 意图不言自明：

  • 明显的错误修复（明确的原因，明确的修复）
  • 琐碎的重构（重命名、提取函数、格式化）
  • 已在代码/注释中有良好记录
  • 变化纯粹是机械的

🔬 工作是探索性的：

  • 快速原型以发现需求
  • 尝试多种方法
  • 高度不确定性，可能会丢弃
  • 通过实践学习更快

注意：在原型设计后编写规范以捕获学习

📄 不适合的工具：

  • API 参考文档（使用自动生成的文档）
  • 用户手册（使用专用工具）
  • 具有特定格式的合规文档（使用所需格式）
  • 依赖更新（标准版本升级）

示例：

  • 单行错误修复
  • 简单的重命名或代码格式化
  • 标准依赖版本升级
  • 实验性原型（如果有效则在之后记录）

核心问题​

"规范会帮助弥合人类意图到机器执行，还是差距已经清楚？"

如果是 → 编写它（保持 <300 行）
如果否 → 跳过它或使用代码/注释

应用第一原则来指导判断。

LeanSpec 在实践中的工作方式​

SDD 工作流​

  1. 发现 - 使用 lean-spec list 检查现有规范
  2. 计划 - 在需要时使用 lean-spec create <name> 创建规范
  3. 实现 - 编写代码，随着学习保持规范同步
  4. 更新 - 使用 lean-spec update <spec> --status <status> 标记进度
  5. 完成 - 完成时标记完成，如果完成则归档

对于独立开发​

  • 从最小开始（仅状态 + 创建日期）
  • 随着需求的出现添加结构
  • 对您会忘记的复杂功能使用规范
  • 让 AI 代理从规范实现

对于团队开发​

  • 规范提供共同理解
  • 依赖跟踪协调需求
  • 看板视图显示项目健康状况
  • MCP 实现跨团队的 AI 协作

对于 AI 驱动的开发​

规范具有双重目的：

  • 人类-AI 桥梁：将意图转化为可执行的上下文
  • AI 记忆：跨会话持久化决策和理由

AI 可以帮助编写规范：

  • 人类提供意图、约束、成功标准
  • AI 起草结构、示例、格式
  • 人类改进以提高清晰度和精简原则

三种规范创建模式：

  1. 人类编写，AI 实现 - 您编写规范，AI 从中构建
  2. AI 起草，人类改进 - AI 从您的意图起草规范，您审查/改进
  3. 共同迭代创建 - 通过对话一起构建规范

所有三种模式都是有效的。根据上下文选择。

AI 辅助的规范编写决策：

当 AI 帮助规范编写时，决策从 "AI 是否需要这个来执行？" 转变为：

"将意图形式化为规范是否比继续对话增加价值？"

编写规范（在 AI 协助下）时：

  • ✅ 意图需要持久化（决策、参考、入职）
  • ✅ 对话已经澄清了要构建什么（~5+ 轮）
  • ✅ 多个利益相关者需要对齐
  • ✅ 复杂性需要结构（在聊天中会漂移）
  • ✅ 需要合规或审计跟踪

跳过规范，继续对话时：

  • ❌ 仍在发现要构建什么（继续探索）
  • ❌ 没有歧义的快速功能（直接实现）
  • ❌ 一次性原型或实验
  • ❌ 代码库中已经清楚的上下文

检查点模型： 大多数规范从对话开始 → 准备好时结晶为规范 → 从规范实现。规范成为您工作中的形式化检查点。

了解更多： 使用 AI 编写规范涵盖工作流、模式和最佳实践。

AI 从规范实现：

  • 清晰的需求减少幻觉
  • 示例显示预期模式
  • 成功标准定义"完成"
  • 约束防止错误路径

底线​

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

它有效是因为它与现实对齐：

  • 上下文窗口是有限的（物理）
  • 工作记忆很小（生物）
  • 时间成本金钱（经济）

专注于：

  • 为什么而不是什么
  • 清晰度而不是完整性
  • 行动而不是文档
  • 演变而不是完美

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

了解更多​

核心概念（为什么）：

入门（如何）：

参考：