验证
使用 LeanSpec 的内置验证系统确保Spec质量。验证检查结构问题、frontmatter正确性以及Token计数管理，以保持最佳的 AI 理解能力。
验证命令
检查Spec的质量问题：
lean-spec validate
默认验证所有Spec。检查特定Spec：
lean-spec validate <spec-1> <spec-2>
质量检查
Token计数分析
基于 上下文经济 (Context Economy) 原则 - Spec必须适合 AI 工作记忆 (Working Memory)：
- ✅ 优秀：<2,000 个Token - 100% AI 有效性
- 👍 良好：2,000-3,500 个Token - 95% AI 有效性
- ⚠️ 警告：3,500-5,000 个Token - 85% AI 有效性
- 🔴 错误：>5,000 个Token - 70% AI 有效性，应该拆分
理由：
- AI 上下文窗口：有限且昂贵
- 质量下降在 50K Token硬限制之前就开始
- 人类 + AI 工作记忆：约 2-3K Token 以实现最佳理解
- 物理 + 生物 + 经济 = 硬限制
行数支撑： LeanSpec 也检查行数作为安全网（400 行警告 / 500 行最大值），但 Token计数是主要指标,因为它直接测量 AI 工作记忆消耗。
子 Spec验证
检查子 Spec文件（DESIGN.md、TESTING.md、IMPLEMENTATION.md 等）：
- 每个子 Spec也遵循Token限制
- 跟踪总Spec大小（主Spec + 子 Spec）
- 如果任何文件超过阈值，建议拆分
frontmatter验证
确保所需字段存在且有效：
必需字段：
status：必须有效（planned、in-progress、complete 等）priority：必须有效（high、medium、low、none）created：有效日期格式
可选字段（如果存在则验证）：
tags：正确格式depends_on、related：有效的Spec引用- 自定义字段：正确类型
结构验证
检查Spec组织：
- README.md 存在（主Spec文件）
- 子 Spec遵循命名约定
- 没有孤立或重复的内容
验证输出
清洁验证
$ lean-spec validate
✅ 所有Spec有效！
摘要：
• 检查了 45 个Spec
• 0 个错误
• 0 个警告
有警告
$ lean-spec validate
⚠️ 发现警告：
058-docs-overview-polish/README.md
⚠️ Token计数：4,200 个Token（85% AI 有效性）
→ 考虑：简化或拆分为子 Spec
摘要：
• 检查了 45 个Spec
• 0 个错误
• 1 个警告
有错误
$ lean-spec validate
❌ 发现错误：
042-complex-spec/README.md
🔴 Token计数：5,800 个Token（70% AI 有效性）
→ 操作：拆分为子 Spec以提高 AI 理解能力
043-broken-spec/README.md
🔴 无效状态：'in_progress'（应该是 'in-progress'）
🔴 缺少必需字段：'created'
摘要：
• 检查了 45 个Spec
• 3 个错误
• 0 个警告
自定义验证选项
设置自定义阈值
# 更严格的Token阈值
lean-spec validate --warning-threshold 4000
# 更宽松的阈值
lean-spec validate --warning-threshold 6000
# 自定义行数支撑
lean-spec validate --max-lines 500
验证特定方面
# 仅检查复杂性（Token）
lean-spec validate --check complexity
# 仅检查frontmatter
lean-spec validate --check frontmatter
# 仅检查结构
lean-spec validate --check structure
修复验证问题
Token计数违规
问题：Spec超过 5,000 个Token（70% AI 有效性）
解决方案：使用子 Spec拆分
# 之前：单个 5,800 TokenSpec
README.md (5,800 Token) 🔴 - 70% AI 有效性
# 之后：拆分为专注的子 Spec
README.md (2,000 Token) ✅ - 概述、决策、摘要（100% 有效性）
DESIGN.md (1,500 Token) ✅ - 详细设计（100% 有效性）
IMPLEMENTATION.md (1,500 Token) ✅ - 实现计划（100% 有效性）
为什么这样做有效：
- 每个文件保持在 2,000 个Token 以下以实现最佳 AI 理解
- AI 可以一次专注于一个方面
- 人类可以快速导航到相关部分
无效的frontmatter
问题：frontmatter字段无效或缺失
解决方案：使用 lean-spec update 修复：
# 修复状态
lean-spec update <spec> --status in-progress
# 修复优先级
lean-spec update <spec> --priority high
# 修复标签
lean-spec update <spec> --tags feature,api
结构问题
问题：缺少 README.md 或格式错误的子 Spec
解决方案：
- 确保 README.md 作为主Spec文件存在
- 遵循子 Spec命名：DESIGN.md、TESTING.md 等
- 在所有文件中使用正确的frontmatter
验证工作流程
提交前检查
提交前运行：
lean-spec validate
在提交更改之前修复任何错误。
CI/CD 集成
添加到您的 CI 管道：
# .github/workflows/validate.yml
name: Validate Specs
on: [push, pull_request]
jobs:
validate:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- uses: actions/setup-node@v3
- run: npm install -g lean-spec
- run: lean-spec validate
定期审查
每周Spec健康检查：
# 检查整体健康状况
lean-spec validate
# 详细分析
lean-spec stats --full
# 审查大型Spec（Token焦点）
lean-spec tokens --all --include-sub-specs
何时拆分
在以下情况下拆分：
- ✅ Spec超过约 3,500 个Token（上下文经济警告）
- ✅ 多个不同的关注点（不同主题）
- ✅ Spec需要超过 10 分钟阅读
- ✅ 频繁编辑导致混乱
在以下情况下不要拆分：
- ❌ 少于约 2,000 个Token且专注
- ❌ 单一的连贯概念
- ❌ 快速阅读和理解
何时简化
在以下情况下简化：
- 简单功能的过多细节
- 重复信息
- 低信噪比 (Signal-to-Noise)
- 未来推测
何时接受警告
有时警告是可以接受的：
- 在积极开发期间暂时较高
- 需要全面细节的复杂功能
- 拆分会降低清晰度
始终稍后重新评估。
最佳实践
- 尽早验证 - 提交前
- 及时修复警告 - 不要让它们累积
- 在约 3,500 个Token时拆分 - 对复杂功能使用子 Spec
- 自动化 - 添加到 CI/CD 管道
- 定期审查 - 每周健康检查
下一步
参考：请参阅第一性原理了解上下文经济和Token管理背后的理由。