leanspec-sdd

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

LeanSpec SDD Skill

LeanSpec SDD 技能

Teach agents how to run Spec-Driven Development (SDD) in LeanSpec projects. This skill is an addon: it does not replace MCP or CLI tools.

教Agent如何在LeanSpec项目中运行Spec-Driven Development（SDD，规范驱动开发）。本技能是一个附加组件：它不会替代MCP或CLI工具。

When to Use This Skill

何时使用本技能

Activate this skill when any of the following are true:

The repository contains a specs/ folder or .lean-spec/config.json
The user mentions LeanSpec, specs, SDD, or spec-driven planning
The task requires multi-step changes, breaking changes, or design decisions

当满足以下任一条件时激活本技能：

仓库包含specs/文件夹或.lean-spec/config.json文件
用户提及LeanSpec、specs、SDD或规范驱动规划
任务需要多步骤变更、破坏性变更或设计决策

Core Principles

核心原则

Context Economy: Keep specs under 2000 tokens when possible. Split large specs.
Discovery First: Always run board/search before creating new specs.
Intent Over Implementation: Capture why first, then how.
Progressive Disclosure: Keep SKILL.md concise; use references for details.
No Manual Frontmatter: Use tools to update status, tags, dependencies.
Verify Against Reality: When asked about completion or progress, check the actual codebase, commits, and changes—not just the spec status.

上下文经济性：尽可能将规范控制在2000token以内。拆分大型规范。
优先发现：创建新规范前，始终先运行board（或lean-spec board）进行搜索。
意图优先于实现：先记录“为什么”，再记录“怎么做”。
渐进式披露：保持SKILL.md简洁；使用引用获取详细信息。
禁止手动编写前置元数据：使用工具更新状态、标签和依赖项。
与实际情况验证：当被问及完成情况或进度时，检查实际代码库、提交记录和变更内容——不要仅依赖规范状态。

Core SDD Workflow

核心SDD工作流

1) Discover

1) 发现

Get the project state: run
```
board
```
(or
```
lean-spec board
```
).
Search for related work before creating anything:
```
search
```
(or
```
lean-spec search "query"
```
).

获取项目状态：运行
```
board
```
（或
```
lean-spec board
```
）。
在创建任何内容前，搜索相关工作：
```
search
```
（或
```
lean-spec search "query"
```
）。

2) Design

2) 设计

If a spec is needed, create it with
```
create
```
(or
```
lean-spec create
```
).
Prefer standard templates and keep scope clear.
Validate token count using
```
tokens
```
(or
```
lean-spec tokens
```
).

如果需要规范，使用
```
create
```
（或
```
lean-spec create
```
）创建。
优先使用标准模板，保持范围清晰。
使用
```
tokens
```
（或
```
lean-spec tokens
```
）验证token数量。

3) Implement

3) 实现

Update spec status to
```
in-progress
```
before coding.
Document decisions and progress inside the spec as work happens.
Link dependencies using
```
link
```
/
```
unlink
```
as they are discovered.

编码前将规范状态更新为
```
in-progress
```
（进行中）。
工作开展时，在规范内记录决策和进度。
发现依赖项时，使用
```
link
```
/
```
unlink
```
进行关联。

4) Validate & Complete

4) 验证与完成

Run
```
validate
```
(or
```
lean-spec validate
```
) before completion.
Ensure all checklist items are checked.
Verify actual implementation: When asked about completion status or progress:
- Check git commits and file changes
- Review actual code implementations
- Verify test coverage and results
- Don't rely solely on spec status field
Update status to
```
complete
```
only when both spec criteria and actual implementation are verified.

完成前运行
```
validate
```
（或
```
lean-spec validate
```
）。
确保所有检查项都已勾选。
验证实际实现情况：当被问及完成状态或进度时：
- 检查git提交记录和文件变更
- 审查实际代码实现
- 验证测试覆盖率和结果
- 不要仅依赖规范状态字段
只有当规范标准和实际实现都通过验证后，才将状态更新为
```
complete
```
（已完成）。

Tool Reference

工具参考

Use MCP tools when available. Use CLI as fallback.

Action	MCP Tool	CLI Command
Project status	`board`	`lean-spec board`
List specs	`list`	`lean-spec list`
Search specs	`search`	`lean-spec search "query"`
View spec	`view`	`lean-spec view <spec>`
Create spec	`create`	`lean-spec create <name>`
Update status	`update`	`lean-spec update <spec> --status <status>`
Dependencies	`deps`	`lean-spec deps <spec>`
Relationships	`relationships`	`lean-spec rel <spec>`
Link / unlink (deprecated)	`link` / `unlink`	`lean-spec link/unlink <spec> --depends-on <other>`
Token count	`tokens`	`lean-spec tokens <spec>`
Validate	`validate`	`lean-spec validate`

优先使用MCP工具，CLI作为备选。

操作	MCP工具	CLI命令
项目状态	`board`	`lean-spec board`
列出规范	`list`	`lean-spec list`
搜索规范	`search`	`lean-spec search "query"`
查看规范	`view`	`lean-spec view <spec>`
创建规范	`create`	`lean-spec create <name>`
更新状态	`update`	`lean-spec update <spec> --status <status>`
依赖项	`deps`	`lean-spec deps <spec>`
关系	`relationships`	`lean-spec rel <spec>`
关联/取消关联（已废弃）	`link` / `unlink`	`lean-spec link/unlink <spec> --depends-on <other>`
Token计数	`tokens`	`lean-spec tokens <spec>`
验证	`validate`	`lean-spec validate`

Best Practices (Summary)

最佳实践（摘要）

Keep AGENTS.md project-specific only; put SDD methodology here.
Never create spec files manually; use
```
create
```
.
Keep specs short and focused; split when >2000 tokens.
Always check dependencies and link specs that block each other.
Document trade-offs and decisions as they happen.

仅在AGENTS.md中保留项目特定内容；SDD方法论放在此处。
永远不要手动创建规范文件；使用
```
create
```
命令。
保持规范简短且聚焦；当超过2000token时进行拆分。
始终检查依赖项，并关联相互阻塞的规范。
随着工作推进，记录权衡方案和决策。

Choosing Relationship Type

选择关系类型

Parent/Child = Decomposition (organizational)

"This spec is a piece of that umbrella's scope"
Spec doesn't make sense without the parent context
Parent completes when all children complete

Depends On = Blocking (technical)

"This spec needs that spec done first"
Specs are independent work items
Could be completely unrelated areas

Rule: Never use both parent AND depends_on for the same spec pair.

Test: If the other spec didn't exist, would your spec still make sense?

NO → Use parent (it's part of that scope)
YES → Use depends_on (it's just a blocker)

See detailed guidance in:

references/WORKFLOW.md
references/BEST-PRACTICES.md
references/EXAMPLES.md
references/COMMANDS.md

父/子 = 分解（组织层面）

“本规范是总括性规范范围的一部分”
脱离父规范上下文，本规范无意义
所有子规范完成后，父规范才算完成

依赖于 = 阻塞（技术层面）

“本规范需要先完成另一规范”
规范是独立的工作项
可能属于完全不相关的领域

规则：不要对同一对规范同时使用父级和依赖于关系。

测试方法：如果另一规范不存在，你的规范是否仍然有意义？

否 → 使用父级关系（它属于该范围的一部分）
是 → 使用依赖于关系（它只是一个阻塞项）

详细指南请参阅：

references/WORKFLOW.md
references/BEST-PRACTICES.md
references/EXAMPLES.md
references/COMMANDS.md

Compatibility Notes

兼容性说明

Works with any Agent Skills-compatible tool (Claude, Cursor, Codex, Letta, Factory).
Requires either LeanSpec MCP tools or CLI access to manage specs.
This skill is additive and does not change existing LeanSpec tooling.

可与任何兼容Agent Skills的工具配合使用（Claude、Cursor、Codex、Letta、Factory）。
需要LeanSpec MCP工具或CLI权限来管理规范。
本技能是附加组件，不会更改现有LeanSpec工具。