Sdd Framework

SDD框架

规范驱动开发 -一种用于人工智能辅助软件开发的方法和工具集，其中规范是真理的来源。

  

安装

通过GitLab的pip（推荐）

# Install latest version
pip install git+https://gitlab.com/akercito/sdd-framework.git

# Install specific version
pip install git+https://gitlab.com/akercito/sdd-framework.git@v1.7.0

# Install with MCP server support (Python 3.10+)
pip install "sdd-framework[mcp] @ git+https://gitlab.com/akercito/sdd-framework.git"

来自源头

git clone https://gitlab.com/akercito/sdd-framework.git
cd sdd-framework
pip install -e .

# With MCP support
pip install -e ".[mcp]"

什么是规范驱动开发？

Traditional:  Idea → Code → Tests → Docs (chaos)
SDD:          Spec → Tests → Code → Validate (order)

SDD合同：

1. 没有SPEC的代码
2. 未经测试不得实施
3. 未经验证不得合并

主要特点

快速开始

# Install the framework
pip install sdd-framework

# Initialize SDD in your project
cd /path/to/your/project
sdd init

# Create a new spec
sdd new-spec api users

# Validate all specs
sdd lint-all

# View dependency graph
sdd deps

# Generate task breakdown
sdd decompose specs/api/users.md

替代方案：直接使用脚本

# Clone the framework
git clone https://github.com/akercito/sdd-framework.git
cd sdd-framework

# Copy to your project
cp templates/scripts/sdd.py /path/to/your/project/
cp -r templates/specs /path/to/your/project/

# Use directly
python3 sdd.py init

项目结构

your-project/
├── sdd.py                  # Main SDD automation script
├── CLAUDE.md               # AI assistant instructions
├── specs/
│   ├── OVERVIEW.md         # Project overview spec
│   ├── api/                # API endpoint specs
│   ├── models/             # Data model specs
│   ├── features/           # Feature/business logic specs
│   ├── tasks/              # Task breakdown files
│   └── _templates/         # Spec templates
└── .sdd/
    ├── state.json          # Execution state
    ├── metrics.json        # Performance metrics
    ├── logs/               # Execution logs
    └── reports/            # Generated reports (HTML graphs, coverage)

壳牌完井

为sdd命令启用选项卡完成：

Bash （添加到 ~/.bashrc):

eval "$(sdd completion bash)"

原有的质量 （添加到 ~/.zshrc):

eval "$(sdd completion zsh)"

鱼 （保存到 ~/.config/fish/completions/sdd.fish):

sdd completion fish > ~/.config/fish/completions/sdd.fish

特征：

• 命令名称完成
• 每个命令的选项完成
• 规范文件的文件路径完成
• 规格类型完成 new-spec （模型、api、功能、任务）

命令参考

规格管理

棉绒规格

相关性分析

需求追溯

代码生成

验证和覆盖

CI/CD集成

观看模式

全球旗帜

棉绒规格

门楣根据15条质量规则检查规格：

输出示例：

============================================================
SPEC LINT REPORT
============================================================

Spec: specs/api/users.md
Score: 84/100
Status: ✅ PASSED

Issues (2):
├── SPEC-003: warning - Line 45: Ambiguous word 'should'
└── SPEC-012: info - Consider documenting edge cases

Suggestions:
└── Add ## Edge Cases section

依赖图

分析和可视化规格关系：

# ASCII visualization (default)
python3 sdd.py deps

┌─ API SPECS ─────────────────────
│
├── users
│   ├─ Requirements: 6
│   ├─ Depends on: 1 specs
│   │   → user (model)
│   └─ Referenced by: 2 specs

EXECUTION ORDER (by wave):
  Wave 1: user, config
  Wave 2: users, auth
  Wave 3: api-gateway

# Interactive HTML with Mermaid diagrams
python3 sdd.py deps --html
# Saves to: .sdd/reports/dependency-graph.html

影响分析

在更改规范之前了解波纹效应：

python3 sdd.py impact specs/models/user.md

============================================================
IMPACT ANALYSIS
============================================================

Spec: user.md
Risk Level: HIGH
Total Affected: 5 specs

Direct Dependents:
├── users.md (API)
└── authentication.md (feature)

All Affected (cascade):
├── users.md
├── authentication.md
├── registration.md
├── admin-api.md
└── user-service.md

⚠️  HIGH RISK: Many specs depend on this

基于波动的执行

获得最佳并行执行顺序：

python3 sdd.py waves

============================================================
EXECUTION WAVES
============================================================

Total Specs: 8
Total Waves: 3
Max Parallelism: 4 specs

Wave 1 (4 parallel):
  • user-model
  • config
  • errors
  • constants

Wave 2 (3 parallel):
  • user-service
  • auth-service
  • logger

Wave 3 (1 serial):
  • api-gateway

✓ No circular dependencies

需求追溯

跟踪从规范到测试再到实施的要求：

# Trace a single spec
python3 sdd.py trace specs/api/users.md

============================================================
REQUIREMENT TRACEABILITY: users.md
============================================================

Summary:
   Total Requirements: 6
   Fully Traced: 6 (100.0%)
   Has Tests: 6 (100.0%)
   Has Implementation: 6 (100.0%)

Requirements:
┌─────────┬──────────────────────────────┬──────────┬────────────┬───────┬──────┐
│ ID      │ Description                  │ Priority │ Status     │ Tests │ Impl │
├─────────┼──────────────────────────────┼──────────┼────────────┼───────┼──────┤
│ REQ-001 │ POST /api/users creates user │ Must     │ ✅ complete │ 3     │ 2    │
│ REQ-002 │ GET /api/users/:id returns   │ Must     │ ✅ complete │ 2     │ 1    │
│ REQ-003 │ PUT /api/users/:id updates   │ Should   │ ⚠️ missing_test │ 0  │ 1    │
└─────────┴──────────────────────────────┴──────────┴────────────┴───────┴──────┘

# Generate HTML report
python3 sdd.py trace specs/api/users.md --html
# Saves to: .sdd/reports/trace-users.html

# Trace all specs in project
python3 sdd.py trace-all

======================================================================
PROJECT REQUIREMENT TRACEABILITY
======================================================================

📊 Summary:
   Specs analyzed: 5
   Total requirements: 44
   Fully traced: 44 (100.0%)
   Has tests: 44 (100.0%)
   Has implementation: 44 (100.0%)

✅ OVERVIEW.md - 9/9 traced (100.0%)
✅ analytics.md - 11/11 traced (100.0%)
✅ short-url.md - 7/7 traced (100.0%)
✅ urls.md - 6/6 traced (100.0%)

Overall Health: 🟢 Healthy (100.0% average coverage)
======================================================================

# Find orphan code (no spec references)
python3 sdd.py orphans

============================================================
ORPHAN CODE DETECTION
============================================================

⚠️  Found orphan code files:

Tests without spec references:
├── tests/unit/utils.test.ts
│   └── Lines: 15, 42, 78
└── tests/e2e/helpers.test.ts
    └── Lines: 23

Source without spec references:
├── src/utils/helpers.ts
│   └── Lines: 10, 45
└── src/services/legacy.ts
    └── Lines: 8, 22, 56

Suggestion: Add @spec annotations to link to relevant specs
============================================================

注释格式

跟踪器识别这些注释格式：

在测试文件中：

/**
 * @spec specs/api/users.md
 * @requirement REQ-001
 */
describe('User creation', () => { ... });

// Or in describe names
describe('REQ-001: User creation works', () => { ... });

在实施文件中：

/**
 * @implements REQ-001
 * @spec specs/api/users.md
 */
export function createUser() { ... }

CI/CD集成

为您的CI/CD管道设置自动质量门。

快速设置

# Generate CI configuration files
python3 sdd.py ci-setup --platform both --pre-commit

这将创建：

• .github/workflows/sdd-check.yml -GitHub操作工作流
• .gitlab-ci-sdd.yml -GitLab CI配置
• .pre-commit-config.yaml -预提交挂钩

运行CI检查

# Run all checks
python3 sdd.py ci-check

# With custom thresholds
python3 sdd.py ci-check --lint-threshold 80 --coverage-threshold 90

# JSON output for CI systems
python3 sdd.py ci-check --json

# JUnit XML for test reporters
python3 sdd.py ci-check --junit

退出代码

环境变量

GitHub操作示例

- name: Run SDD Checks
  run: python3 sdd.py ci-check --lint-threshold 70 --coverage-threshold 80

GitLab CI示例

include: '.gitlab-ci-sdd.yml'

variables:
  SDD_LINT_THRESHOLD: "80"
  SDD_COVERAGE_THRESHOLD: "90"

观看模式

实时监控规格文件，并自动验证更改：

# Start watch mode (all checks)
python3 sdd.py watch

# Watch with specific checks only
python3 sdd.py watch --lint-only
python3 sdd.py watch --deps-only
python3 sdd.py watch --trace-only

# Disable specific checks
python3 sdd.py watch --no-lint --no-deps

# Auto-open HTML reports on failures
python3 sdd.py watch --open

# Custom debounce interval
python3 sdd.py watch --debounce 1000

# Force polling (instead of native file watching)
python3 sdd.py watch --poll

# Don't clear screen on changes
python3 sdd.py watch --no-clear

监视模式输出：

============================================================
  SDD WATCH MODE
============================================================

  Watching: /path/to/specs
  Checks: lint, deps, trace
  Debounce: 500ms

  Press Ctrl+C to stop

------------------------------------------------------------

[12:34:56] Changes detected:
  • OVERVIEW.md
  • users.md

Results: (took 125ms)

  ✅ Lint: score 85/100
  ✅ Dependencies: OK
  ✅ Traceability: 95.5% coverage

------------------------------------------------------------
  ✅ ALL CHECKS PASSED
------------------------------------------------------------

  Watching for changes...

规范格式

每个规范都遵循以下结构：

# [Name] Specification

> Spec ID: `TYPE-001`
> Version: 1.0.0
> Status: Draft | Approved | Implemented

## Overview
Brief description of what this spec defines.

## Requirements
| ID | Requirement | Priority |
|----|-------------|----------|
| REQ-001 | Description | Must/Should/Could |

## Schema/Interface
Data structures with types.

## Behavior
Expected behavior for normal and edge cases.

## Error Handling
How errors are handled.

## Examples
Concrete input/output examples.

## Acceptance Criteria
- [ ] REQ-001: Checklist item
- [ ] REQ-002: Another item

## Changelog
| Version | Date | Changes |
|---------|------|---------|
| 1.0.0 | 2025-01-09 | Initial |

与Claude Code集成

这 CLAUDE.md 文件指示AI助手：

1. 先检查规格 -在实施之前验证规范是否存在
2. 先生成测试 -在代码之前创建测试（TDD）
3. 严格遵循规格 -实现与规范完全匹配
4. 添加可追溯性 -将代码链接到要求
5. 运行验证 -完工前进行全面检查

用于AI集成的MCP服务器

SDD框架包括一个MCP（模型上下文协议）服务器，该服务器公开了所有SDD工具，供Claude和其他AI助手使用。

快速设置

# Install dependencies
pip install mcp pydantic

# Configure Claude Code (~/.config/claude-code/settings.json):
{
  "mcpServers": {
    "sdd": {
      "command": "python3",
      "args": ["/path/to/sdd-framework/mcp-server/sdd_mcp_server.py"]
    }
  }
}

可用的MCP工具

看 mcp服务器/README.md 详细文档。

工作流示例

# 1. Create spec
python3 sdd.py new-spec api orders

# 2. Edit with your requirements
vim specs/api/orders.md

# 3. Lint the spec
python3 sdd.py lint specs/api/orders.md

# 4. Check impact
python3 sdd.py impact specs/api/orders.md

# 5. Check execution order
python3 sdd.py waves

# 6. Generate tasks for parallel execution
python3 sdd.py decompose specs/api/orders.md

# 7. Auto-execute with Claude Code
python3 sdd.py auto-execute specs/api/orders.md

# 8. Verify coverage
python3 sdd.py coverage

文档

• 快速入门指南 -5分钟后开始
• 用户手册 -完整的文档
• 规范模板 -模板参考

配置

创建 sdd.config.json 在您的项目中：

{
  "validation": {
    "requireSpecForCode": true,
    "requireTestsBeforeImpl": true,
    "coverageThreshold": 80,
    "strictMode": true
  },
  "linting": {
    "errorOnWarning": false,
    "minScore": 70
  },
  "testing": {
    "runner": "pytest",
    "patterns": ["tests/**/*.py", "test_*.py"]
  }
}

测试转轮自动检测

SDD会根据项目文件自动检测您的测试运行器：

覆盖 testing.runner 在配置中。

贡献

1. 分叉存储库
2. 创建要素分支
3. 编写新功能的规格（SDD也适用于此！）
4. 提交拉取请求

许可证

MIT许可证

更新日志

看 更改日志.md 查看详细的发行说明。

______________________________________________________________________

记住：规范是真理的来源。如有疑问，请阅读说明书。