跳到主要内容

常见问题

什么是 LeanSpec？​

LeanSpec 是一个为 AI 辅助开发优化的轻量级规范框架。它是一个 CLI 工具 + markdown 文件，位于您的仓库中，帮助您记录技术决策并指导 AI 编码工具，同时保持规范在 300 行以下以获得最佳性能。

关键功能：

  • 用于轻松引用的编号规范
  • 用于创建、搜索和管理规范的 CLI 工具
  • 用于 AI 工具集成的 MCP 服务器（GitHub Copilot、Claude Code、Cursor 等）
  • 验证以确保规范质量
  • 用于项目可见性的看板和统计
  • 5 分钟设置：**
npm install -g lean-spec
cd your-project
lean-spec init
lean-spec create my-first-spec

无需配置文件，无需数据库，无需服务器。适用于任何编辑器和任何 AI 工具。

为什么使用 LeanSpec？​

在以下情况下使用 LeanSpec：

  • 需要团队在复杂功能上达成一致
  • 需要设计决策的文档
  • 需要上下文以减少 AI 幻觉
  • 需要新团队成员的入职材料

对于以下情况跳过 LeanSpec：

  • 简单的错误修复
  • 一次性原型
  • 具有明确需求的单人项目

哲学： 在最大敏捷性的同时获得 80% 的 vibe 编码速度和 80% 的结构化规范优势。在混乱和官僚主义之间架起桥梁。

为什么有 300 行限制？​

注意力是稀缺资源，而不是存储。

三个原因：

  1. 人类注意力范围 - 在 5-10 分钟内阅读和理解
  2. AI 性能 - 上下文质量在 50K 令牌之后下降
  3. 工作记忆 - 保持规范认知可管理

如果您的规范超过 300 行，请将其拆分为子规范文件（DESIGN.md、IMPLEMENTATION.md、TESTING.md 等）。详见第一原则。

故障排除​

我的规范被 AI 编辑损坏了​

原因： 规范超过上下文窗口，AI 失去了结构跟踪。

修复：

git checkout HEAD -- specs/042-my-spec/  # 从 git 恢复
lean-spec validate                        # 检查问题

预防： 保持规范在 300 行以下（在 300 行时警告，在 400 行时错误）。

lean-spec update 说"找不到规范"​

调试：

lean-spec list          # 查看所有活动规范
lean-spec list --all    # 包括已归档

常见原因：

  • 不在带有 specs/ 目录的 git 仓库中
  • 规范名称/编号拼写错误
  • 规范被归档

前置元数据验证失败​

常见错误：

  • 手动编辑系统管理的字段（status、created_at、transitions 等）
  • 无效的 YAML 语法
  • 字段名称拼写错误

修复：

lean-spec validate      # 查看确切的错误

始终使用 CLI 命令更新元数据：

lean-spec update 042 --status in-progress
lean-spec update 042 --priority high
lean-spec update 042 --tags api,backend

如何恢复已删除的规范？​

规范只是 git 中的文件：

git log --all --full-history -- "specs/042-my-spec/*"
git checkout <commit> -- specs/042-my-spec/

或从已归档恢复：

mv archived/042-my-spec specs/
lean-spec update 042 --status in-progress

CLI 命令不工作​

检查安装：

which lean-spec
lean-spec --version

如果需要，重新安装：

npm install -g lean-spec

验证您在 git 仓库中：

git rev-parse --git-dir

贡献与支持​

如何报告错误或请求功能？​

我可以贡献吗？​

可以！请参见 CONTRIBUTING.md。

常见贡献：

  • 文档改进
  • 错误修复
  • 新模板
  • MCP 服务器增强

我可以在哪里获得帮助？​

许可证是什么？​

MIT 许可证 - 可免费用于商业和个人用途。

更多问题？ 查看完整文档或在 GitHub Discussions 中提问。