跳到主要内容

理解 LeanSpec

LeanSpec 的目标是让人类和 AI 都能在一个文件内理解工作意图。这一页解释结构背后的原因、如何随着复杂度升级结构，以及如何保持Spec长期有效。

核心原则​

LeanSpec 建立在五个关键原则之上，旨在弥合人类意图与 AI 执行之间的差距：

  1. 上下文经济 (Context Economy)：保持Spec小巧（<2,000 Token）以适应工作记忆 (Working Memory)。
  2. 信噪比 (Signal-to-Noise)：每个词都必须为决策提供信息。
  3. 意图优于实现 (Intent Over Implementation)：捕获为什么和什么，让如何涌现。
  4. 跨越鸿沟：为人类理解和 AI 解析而写。
  5. 渐进式披露 (Progressive Disclosure)：从简单开始，仅在感到痛点时增加复杂性。

何时编写Spec​

在以下情况编写或更新Spec：

  • 意图需要澄清或存在多种解释
  • 权衡、约束或成功标准很重要
  • 工作跨越多个文件/系统或影响其他团队
  • AI 代理将实现部分功能
  • 决策应在聊天或会议之外持久存在

**跳过它当：**修复明显的错误、执行机械重构或进行原型设计以学习。

为什么这种结构有效​

LeanSpec 优先保证上下文经济与信噪比：

  • frontmatter 让状态、依赖、优先级对所有仪表盘和 AI 可读。
  • 概述 记录问题、为什么现在做、期望结果，方便新人快速进入状态。
  • 计划/设计 随学习过程逐步丰富；当 README 接近 2,000 Token时，用子 Spec承载额外深度。
  • 验证 告诉每个人何时算完成，也让 AI 更放心地下一个动作。

当主文档超出工作记忆，立刻将细节拆入 DESIGN.md、IMPLEMENTATION.md、TESTING.md 等子文件，让阅读体验保持 5-10 分钟。

从入门到进阶​

阶段关注点何时升级
入门捕获问题、期望结果、完成定义。需要反复解释背景或重复回答问题。
进阶维护准确的状态、依赖、标签，让多Spec协作更顺畅。交接频繁、跨团队上下文容易丢失。
高手使用阶段计划、子 Spec、Token预算协调多周项目。不同受众需要不同深度，或多个 AI 并行协作。

遵循渐进披露：只有在感到痛点时才增加结构。

让Spec保持“活”​

  • 实现一开始或暂停就更新状态——状态描述工作进度，而非写作进度。
  • 在 ## Notes/## Evolution 下记录发现与范围变更，方便后来者理解决策演变。
  • 合并前运行 lean-spec validate 与 lean-spec tokens <spec>，确保元数据完整、内容不过载。
  • 定期检查链接（仪表板、MCP 命令、PR 等）是否仍然有效。

健康检查清单：

  • ☐ 仍小于约 2,000 Token或已拆分
  • ☐ 问题陈述匹配当下认知
  • ☐ 成功标准可测
  • ☐ 依赖与相关Spec准确
  • ☐ 最近发现已记录

与 AI 协作​

  1. 提供Spec路径或让 MCP search_specs 去加载上下文。
  2. 让 AI 回述Spec，确认双方理解一致。
  3. 允许 AI 起草代码、文档、测试，并把偏差记录回Spec，保证下一位执行者能接力。
  4. 按验证章节核对成果后，将状态改为 complete。

延伸阅读​