第一原则
"这些不是我们选择的原则——它们是我们发现的约束。"
从三个不可变的约束（物理、生物、经济）中，出现了五个第一原则。它们定义了 LeanSpec 的核心本质，并指导所有决策。
我们发现的约束
LeanSpec 建立在三个不可改变的约束之上：
1. 物理：上下文窗口随长度降级
- AI 模型具有有限的令牌限制（128K-200K 令牌）
- 质量在超过 20-50K 有效令牌后显著降低
- 即使在限制内，更长的上下文 = 更差的性能
- 大上下文增加错误率和"中间丢失"效应
2. 生物：注意力是稀缺资源
- 人类可以在工作记忆中保持约 7 个项目
- 专注阅读的注意力持续时间为 5-10 分钟
- 认知负荷随复杂性而增加
- 注意力，而不是存储，是瓶颈
3. 经济：时间和令牌成本金钱
- 令牌成本迅速累积
- 工程师时间昂贵
- 维护负担随文档大小增长
这些约束是不可改变的。 LeanSpec 不与它们对抗——它在其中工作。
五个第一原则
从这些约束中，出现了五个第一原则：
1. 上下文经济 🧠
规范必须适合工作记忆——人类和 AI 的。
这意味着什么： 这不是关于超过令牌限制（如内存不足）。这是关于注意力和认知能力：
- 即使在令牌限制内，AI 性能在更长的上下文中降低
- 人类一次不能在工作记忆中保持超过约 7 个概念
- 注意力是稀缺资源，而不是存储
为什么是 400 行？
- 600 行 ≈ 15-20K 令牌 = 一个规范的整个有效工作记忆
- 质量在超过 50K 令牌后降低（即使有 200K 限制）
- 需要 >10 分钟阅读（超过注意力持续时间）
- 无法在脑中保持整个规范结构
在实践中：
- 目标：每个规范文件 <300 行
- 警告：300-400 行（考虑简化）
- 问题：>400 行（必须拆分）
测试：
"这可以在 5-10 分钟内阅读和理解吗？您能在脑中保持整个结构吗？"
如果不能，它违反了上下文经济。
示例：
❌ 坏：650 行规范涵盖功能、测试、配置、示例
✅ 好：250 行 README + 150 行 TESTING.md + 100 行 CONFIG.md
为什么这是 #1： 如果规范不适合工作记忆，其他一切都无关紧要。800 行规范中完美的信噪比仍然是无用的。
与信噪比的对比：
- 上下文经济 = 您能在脑中保持所有内容吗？（认知能力）
- 信噪比 = 每个词都告知决策吗？（信息密度）
2. 信噪比最大化 📡
每个词都必须告知决策或被删除。
这意味着什么： 虽然上下文经济问"您能保持所有内容吗？"，信噪比问"每一块都值得保持吗？"
- 令牌成本惩罚冗长（AI 处理）
- 认知负荷惩罚噪音（人类阅读）
- 维护负担增加（保持文档最新）
测试：
"这句话告知什么决策？"
如果答案是"没有"或"可能将来"，删除它。
示例：
❌ 低信噪比：
用户认证系统将使用行业标准安全实践和方法论实现，
将为用户提供安全的机制来认证自己...
✅ 高信噪比：
用户使用电子邮件/密码登录。系统根据数据库验证并返回
JWT 令牌（24 小时过期）。
何时添加细节：
- 解释权衡决策
- 澄清约束
- 定义成功标准
- 显示关键示例
何时删除：
- 对您的受众来说显而易见
- 在其他地方容易发现
- 可能在实现前改变
- "很高兴知道" vs. "需要知道"
3. 意图优于实现 🎯
捕获"为什么"和"是什么"，让"如何做"出现。
约束：
- 意图是稳定的，实现会改变
- AI 需要"为什么"来做出良好决策
- 开发人员需要上下文，而不是处方
在实践中：
- 必须有：问题、意图、成功标准
- 应该有：设计理由、权衡
- 可以有：实现细节、示例
测试：
"理由清楚吗？有人可以在没有我的情况下做出良好决策吗？"
示例：
❌ 坏（仅实现）：
使用 Redis 进行缓存。配置 1GB 最大内存，使用 LRU 驱逐。
✅ 好（意图 + 实现）：
**意图**：仪表板 API 响应低于 100ms。
**约束**：10k+ 用户反复查询相同数据。
**方法**：Redis 缓存使用 LRU 驱逐（减少 DB 负载 90%）。
**权衡**：增加复杂性 vs. 性能要求。
第二个解释了为什么是 Redis，为什么 100ms 很重要，以及我们正在做什么权衡。
4. 弥合差距 🌉
规范的存在是为了使人类意图与机器执行对齐。
约束：
- 人类以目标和上下文思考
- 机器需要清晰、明确的指令
- 它们之间的差距必须弥合
在实践中：
- 对人类：概述、上下文、理由
- 对 AI：清晰的结构、需求、示例
- 两者都需要：自然语言 + 结构化数据
测试：
"人类和 AI 都可以解析并推理这个吗？"
示例：
✅ 好（弥合差距）：
## 目标
将仪表板的 API 延迟降低到 <100ms（目前为 2-3 秒）。
## 为什么重要
用户在 3 秒后放弃。我们正在失去 40% 的流量。
## 技术方法
- 在 Redis 中缓存仪表板数据（TTL：5 分钟）
- 延迟加载小部件，而不是阻塞所有数据
- 对静态资产使用 CDN
## 成功标准
- [ ] 仪表板在 <100ms 内加载（在 p95 测量）
- [ ] 缓存命中率 >80%
- [ ] 2 周后零缓存相关错误
人类看到：为什么重要、目标、方法
AI 看到：清晰的需求、成功标准、技术方法
5. 渐进式披露 📈
从简单开始，仅在感到痛苦时添加结构。
约束：
- 团队随时间演变
- 需求出现，不是预先存在的
- 过早的抽象是浪费
在实践中：
第 1 天（独立开发）：
status: planned
created: 2025-11-01
第 2 周（小团队）：
status: in-progress
created: 2025-11-01
tags: [api, backend]
priority: high
第 3 个月（企业）：
status: in-progress
created: 2025-11-01
tags: [api, backend]
priority: high
assignee: alice
epic: PROJ-123
sprint: sprint-10
reviewer: bob
测试：
"没有这个功能我们会感到痛苦吗？"
如果不会，还不要添加它。
为什么这有效： 您永远不需要重写您的规范。只需在需要时添加字段。
冲突解决框架
当实践冲突时，按优先级顺序应用原则：
- 上下文经济 - 如果它不适合工作记忆，拆分它
- 信噪比 - 如果它不告知决策，删除它
- 意图优于实现 - 捕获为什么，而不仅仅是如何
- 弥合差距 - 人类和 AI 都必须理解
- 渐进式披露 - 在感到痛苦时添加结构
真实世界示例
问："我应该拆分这个 450 行规范吗？"
→ 是（上下文经济在 400 行时覆盖完整性）
问："我应该记录每个边缘情况吗？"
→ 仅当它告知当前决策时（信噪比测试）
问："我应该预先添加自定义字段吗？"
→ 仅当没有它们会感到痛苦时（渐进式披露）
问："我应该在规范中保留实现细节吗？"
→ 仅当理由/约束重要时（意图优于实现）
问："哪个更重要：完整的文档还是保持在 400 行以下？"
→ 保持在 400 行以下（上下文经济是 #1 原则）
底线
这五个第一原则不是任意的指导方针——它们来自不可变的约束：
- 物理（上下文窗口是有限的）
- 生物（工作记忆很小）
- 经济（时间和令牌成本金钱）
按优先级顺序应用它们。当有疑问时，上下文经济总是获胜。