leanspec

LeanSpec — 规格编码技能

教 Agent 规格编码：将规格视为推动开发的持久工件，而不是转瞬即逝的规划笔记。LeanSpec 提供方法论和 leanspec CLI；每种适配器（markdown、GitHub Issues、ADO、Jira 等）都使用其后端的原生语言。此技能刻意与适配器无关——不要在此处硬编码状态值、优先级名称或字段键。

每次会话都从能力发现开始

在读取、编写或关联任何规格之前，运行：

leanspec capabilities -o json

输出是事实依据。它会告诉你：

• 当前适配器的名称（markdown、github、ado 等）。
• 存在哪些元数据字段，以及它们的类型／枚举值。
• 此适配器上哪些字段分别承担各个语义角色（status、priority、tags、assignee、due_date）。
• 后端支持哪些链接类型（parent、depends_on 等）。

返回的枚举值是唯一有效的词汇。如果你想将规格转入“进行中”状态，请查找语义字段 status，选择适配器称为“工作正在进行”的值，并发送该值——不要假设它叫 in-progress。

核心原则

1. 规格是持久工件。 它们会在会话结束后继续存在，可供审查，并且与代码关联。它们不是规划模式下的临时草稿。
2. 关注方法论，而非机制。 以下五个阶段适用于任何后端，无论它是 markdown 文件夹、GitHub 仓库还是 Jira 项目。
3. 先发现。 在编写任何新内容之前，务必先阅读现有内容。
4. 先明确意图，再实现。 先记录为什么，再记录如何做。
5. 根据实际情况验证。 不要只相信状态字段——还要检查代码、提交、测试和 CI。
6. 使用适配器的词汇。 不要硬编码字段名称或值。

五个阶段

1. 发现

在动手之前，了解项目的当前状态。

1. 运行 leanspec capabilities -o json（会话开始时）。
2. 运行 leanspec board，查看项目的当前概况。
3. 运行 leanspec search "<keywords>"，查找相关条目。
4. 如果存在高度匹配的条目，请考虑扩展该条目或与其建立链接，而不是创建新条目。

2. 创建

将意图记录为新的持久工件。

1. 在一次调用中使用所有已知字段运行 leanspec create <short-name>（标题、正文、状态／优先级等语义字段、标签、父项、依赖项）。不要先创建空条目，再对其进行修改。
2. 按以下结构编写正文：
   • 概述——此项要解决什么问题，以及为何重要。
   • 需求——可独立验证的条目清单。
   • 非目标——明确不在范围内的内容。
   • 验收标准——可衡量的完成定义。
3. 随着关系逐渐明确，建立关联。使用适配器声明的链接类型（通常用 parent 表示层级关系，用 depends_on 表示阻塞关系——通过 capabilities 确认）。

3. 细化

在开始编码之前，让规格达到可直接实施的程度。

1. 定位规格中提到的文件、模块和 API，并确认它们确实存在。
2. 找出可复用的现有模式，并在规格中注明具体路径和函数签名。
3. 验证依赖项是否可用。
4. 准入条件：不存在阻塞性未知因素；每个清单条目都具体且可执行。

4. 实施

按照细化后的规格执行。

1. 阅读规格（leanspec view <id>），包括父项、子项和依赖项。
2. 使用适配器声明的状态值，通过 leanspec update <id> 将规格转入“工作正在进行”状态。
3. 按顺序处理清单；遵守范围边界；及时在规格中记录决策和发现。
4. 如果发现范围外的工作，请创建一个新规格并建立关联，而不是扩大当前规格的范围。

5. 验证

根据实际情况完成闭环，而不是依据状态。

1. 运行项目的质量检查（测试、类型检查、lint、构建）。
2. 重新阅读规范的验收标准，只有在能指出证明它的提交、测试或文件时，才勾选该标准。
3. 将规范转换为适配器声明的“已完成”状态，并附上简短的实现说明。
4. 如果有任何失败，保持进行中状态，修复原因并重新运行。

关系类型

关系类型由适配器声明。检查 capabilities.link_types。最常见的两种形式：

• 父级 / 子级 — 一个总项分解为多个子项。子项脱离父项便没有意义；所有子项完成后，父项才算完成。
• 依赖 — 阻塞关系。两个事项是独立工作，只是其中一个必须先交付。

决策流程图：

1. 事项 B 是否属于事项 A 的范围？→ 父级 / 子级。
2. 事项 B 是否只需要等事项 A 完成？→ 依赖。
3. 同一对事项之间绝不要同时使用两种关系。

试金石：“如果事项 A 不存在，事项 B 仍然有意义吗？” 否 → B 是 A 的子项。是 → B 依赖于 A。

管理不断演进的工作

• 内容变更 — 使用 leanspec update --content 或编辑事项正文。
• 元数据变更 — 对适配器声明的字段，使用受支持的 leanspec update 标志（--status、--priority、--assignee、--add-tags、--remove-tags 等）。每个标志都接受适配器功能中声明的值。该技能绝不会直接写入 frontmatter 或 YAML。
• 范围蔓延 — 拆分。创建一个同级规范并建立关联；更新原规范的非目标，以引用拆分出的规范。
• 过时的工作 — 转换为适配器的“已关闭 / 已归档”状态，而不是删除；历史记录很重要。

上下文精简

• 每个事项控制在约 2000 个 token 以下。超过则拆分。
• 优先使用项目符号列表，而非散文。
• 使用外部文档作为参考，而不是复制其内容。
• 清单仅用于可执行事项；其他内容使用普通列表。

最佳实践 — 一览

• 绝不要手动创建事项。 始终使用 leanspec create。
• 绝不要直接编辑元数据。 使用 leanspec update。
• 始终先探索。 在 create 前运行 board / search。
• 使用 create 时始终传入所有已知字段。 不要先创建空项，再补充字段。
• 关闭前始终进行验证。 测试、类型检查、lint、构建。
• 遵循适配器的词汇。 如果有任何不明确之处，重新运行 capabilities。

参考资料

• references/adapters.md — 适配器的工作方式，以及如何基于它们编写 SOP。
• references/workflow.md — 包含示例的五阶段工作流。
• references/commands.md — CLI 参考。
• references/best-practices.md — 详细模式与反模式。
• references/examples.md — 基于 Markdown、GitHub Issues 和 Azure DevOps 后端的端到端场景。