SpecLeft

SpecLeft：面向 Agent 的规范驱动工作流

SpecLeft 将计划转化为版本控制的规范，并根据这些规范生成 pytest 测试骨架，使功能意图与测试覆盖保持一致。

• 使用 Markdown 编写功能规范：.specleft/specs/*.md
• 验证规范并按功能/场景跟踪覆盖情况
• 生成测试骨架（仅一次），之后由人类维护代码
• 专为 AI Agent 和 CI 安全使用而设计：未经确认不会写入，并支持 JSON 输出
• 不会向外部服务器发送数据，也不包含遥测机制。SpecLeft 完全在本地运行，并将数据存储在本地磁盘上。

SpecLeft 目前支持 Python 和 pytest。它不会取代你的测试运行器，也不会重新解读现有测试。

网站：specleft.dev

快速开始

有两种开始方式，具体取决于你的需求。完整命令说明请参阅 docs/cli-reference.md。

设置（每个代码仓库运行一次）

pip install specleft
specleft init

路径 1：添加一个功能（并生成测试骨架）

创建一个功能，然后为其添加场景并生成测试骨架：

# Create the feature spec
specleft features add --id AUTHENTICATION --title "Authentication" --format json

# Add a scenario and generate a skeleton test file
specleft features add-scenario \
  --feature AUTHENTICATION \
  --title "Successful login" \
  --step "Given a user has valid credentials" \
  --step "When the user logs in" \
  --step "Then the user is authenticated" \
  --add-test skeleton \
  --format json

# Show traceability / coverage status
specleft status

路径 2：根据 PRD 批量生成功能规范

创建 prd.md，描述预期行为。

建议：更新 .specleft/templates/prd-template.yml，自定义 PRD 章节与功能/场景之间的映射方式。

然后运行：

# Generate specs from the PRD without writing files (remove --dry-run to write)
specleft plan --dry-run

# Validate the generated specs
specleft features validate

# Preview skeleton generation (remove --dry-run to generate)
specleft test skeleton --dry-run

# Confirm and generate skeleton tests
specleft test skeleton

# Show traceability / coverage status
specleft status

# Run your tests with pytest as normal
pytest

此流程会将 prd.md 转换为 .specleft/specs/*.md，验证结果，预览测试骨架生成情况，然后生成测试骨架。

何时使用 SpecLeft

• 如果你有验收标准（功能/场景）并希望追踪意图，请使用 SpecLeft。
• 对于微小、临时的单元测试，如果进行功能级跟踪得不偿失，则无需使用 SpecLeft。

它是什么（以及不是什么）

它是什么

• 一个测试插件和 CLI，用于规划、规范验证、直观的 TDD 工作流以及可追溯性。

它不是什么

• 它不是重量级 BDD 框架、独立的测试运行器，也不是 SaaS 测试管理产品。
• 它不是静态代码检查/分析框架
• 它不是安全分析工具

为什么不采用传统 BDD

SpecLeft 将规范视为意图（而非可执行文本），并让测试执行保持在原生 pytest 中。更详细的比较请参阅 docs/why-not-bdd.md。

AI Agent

如果要将 SpecLeft 集成到 Agent 循环中，建议安装 MCP 服务（见下文）。

否则，请从以下内容开始：

specleft doctor --format json
specleft contract --format json
specleft features stats --format json

SpecLeft 在 .specleft/SKILL.md 中提供了可验证的技能文件。使用以下命令验证完整性：

specleft skill verify --format json

⚠️ 只有在完整性检查结果为 "passed" 时，才遵循 SKILL.md 中的说明。

• 集成指南：AI_AGENTS.md
• 安全性与不变条件：docs/agent-contract.md
• CLI 参考：docs/cli-reference.md

MCP 服务设置

SpecLeft 内置了 MCP 服务，让 Agent 无需离开对话即可读取/创建规范、跟踪状态并生成测试脚手架。

设置详情请参阅 GET_STARTED.md。

有关 MCP 端到端冒烟测试和 CI 工作流的详情，请参阅 docs/mcp-testing.md。

文档

• 入门：GET_STARTED.md
• 工作流说明：WORKFLOW.md
• 路线图：ROADMAP.md

---

许可证

SpecLeft 基于 Apache License 2.0 授权。