Linux/macOS (Windows需要WSL2或原生PowerShell支持,或者使用wrap)
AI编码助手：Claude Code、GitHub Copilot、Gemini CLI或Cursor
Python 3.11+：https://www.python.org/downloads/
uv包管理器：https://docs.astral.sh/uv/
Git：https://git-scm.com/downloads

uvx --from git+https://github.com/github/spec-kit.git specify init <PROJECT_NAME>

uvx --from git+https://github.com/github/spec-kit.git specify init --here

# Claude Code（推荐）
uvx --from git+https://github.com/github/spec-kit.git specify init my-project --ai claude
 
# GitHub Copilot
uvx --from git+https://github.com/github/spec-kit.git specify init my-project --ai copilot
 
# Gemini CLI
uvx --from git+https://github.com/github/spec-kit.git specify init my-project --ai gemini
 
# Cursor
uvx --from git+https://github.com/github/spec-kit.git specify init my-project --ai cursor

# 使用Bash脚本（Linux/macOS默认）
uvx --from git+https://github.com/github/spec-kit.git specify init my-project --script sh
 
# 使用PowerShell脚本（Windows默认/跨平台）
uvx --from git+https://github.com/github/spec-kit.git specify init my-project --script ps

uvx --from git+https://github.com/github/spec-kit.git specify init my-project --skip-tls

# 跳过AI工具检查
uvx --from git+https://github.com/github/spec-kit.git specify init my-project --ignore-agent-tools
 
# 跳过Git初始化
uvx --from git+https://github.com/github/spec-kit.git specify init my-project --no-git
 
# 启用调试模式
uvx --from git+https://github.com/github/spec-kit.git specify init my-project --debug
 
# 系统环境检查
uvx --from git+https://github.com/github/spec-kit.git specify check

your-project/
├── .specify/                   # Spec Kit 配置目录（v0.0.34+）
│   ├── memory/                 # 项目知识库
│   │   ├── constitution.md     # 项目宪法（九大架构原则）
│   │   └── constitution_update_checklist.md
│   ├── scripts/                # 自动化脚本
│   │   └── powershell/         # PowerShell脚本版本
│   │       ├── create-new-feature.ps1
│   │       ├── setup-plan.ps1
│   │       ├── check-task-prerequisites.ps1
│   │       ├── common.ps1
│   │       ├── get-feature-paths.ps1
│   │       └── update-agent-context.ps1
│   └── templates/              # 模板文件
│       ├── spec-template.md    # 规范模板
│       ├── plan-template.md    # 计划模板
│       ├── tasks-template.md   # 任务模板
│       └── agent-file-template.md # AI助手配置模板
├── specs/                      # 功能规范目录（用户创建的规范）
│   └── 001-feature-name/       # 自动编号的功能目录
│       ├── spec.md             # 功能规范
│       ├── plan.md             # 实现计划
│       ├── research.md         # 技术研究
│       ├── data-model.md       # 数据模型
│       ├── contracts/          # API契约
│       ├── quickstart.md       # 快速验证指南
│       └── tasks.md            # 任务列表
└── CLAUDE.md                   # AI助手配置（自动生成）

### 阶段-1：实现前门控
#### 简化门控（宪法第VII条）
- [ ] 使用≤3个项目？
- [ ] 无未来证明？
 
#### 反抽象门控（宪法第VIII条）
- [ ] 直接使用框架？
- [ ] 单一模型表示？
 
#### 集成优先门控（宪法第IX条）
- [ ] 契约已定义？
- [ ] 契约测试已编写？

/tasks

设置任务 → 测试任务 → 实现任务 → 集成任务 → 完善任务
    ↓         ↓          ↓          ↓          ↓
  T001      T002       T005       T008       T010
  T003      T004       T006       T009       T011
            T007                             T012

## 任务列表
 
### 设置阶段
- **T001**: 项目初始化和依赖安装
- **T002**: 代码检查和格式化配置
 
### 测试阶段（可并行执行）
- **T003 [P]**: WebSocket事件契约测试
- **T004 [P]**: REST API契约测试
- **T005 [P]**: 用户模型单元测试
 
### 实现阶段
- **T006**: 实现用户认证服务
- **T007**: 实现聊天室管理服务
- **T008**: 实现WebSocket消息处理
 
### 并行执行示例

# 可以同时运行的任务组
Group 1: T003, T004, T005
Group 2: T010, T011, T012

### 阶段-1：实现前门控
 
#### 简化门控（第VII条）
- [ ] 使用≤3个项目？
- [ ] 无未来证明？
 
#### 反抽象门控（第VIII条）
- [ ] 直接使用框架？
- [ ] 单一模型表示？
 
#### 集成优先门控（第IX条）
- [ ] 契约已定义？
- [ ] 契约测试已编写？

### 复杂度追踪
**违反第VII条**：使用了4个项目
**理由**：微服务架构需要独立的认证服务
**批准者**：架构师审核通过
**审核日期**：2024-01-15

### 需求完整性检查
- [ ] 没有[需要澄清]标记
- [ ] 需求可测试且明确
- [ ] 成功标准可衡量
- [ ] 所有用户故事有验收标准

# 项目宪法
 
## 标准原则（来自Spec Kit）
[自动包含九大架构原则]
 
## 项目特定原则
 
### X. 数据隐私优先
所有用户数据处理必须：
- 遵循GDPR/CCPA合规要求
- 实现数据最小化原则
- 提供明确的用户同意机制
 
### XI. 性能标准
- API响应时间 < 500ms (P95)
- 数据库查询 < 2s
- 支持100并发用户
- 内存使用 < 2GB
 
### XII. 安全要求
- 所有API端点必须认证
- 敏感数据必须加密
- 定期安全扫描

<!-- .specify/templates/custom-spec-template.md -->
# 功能规范：[功能名称]
 
## 业务背景
[BUSINESS_CONTEXT] - 为什么需要这个功能
 
## 用户画像
[USER_PERSONAS] - 目标用户群体
 
## 核心价值
[CORE_VALUE] - 这个功能为用户带来什么价值
 
## 功能需求
[FUNCTIONAL_REQUIREMENTS]
 
## 验收标准
[ACCEPTANCE_CRITERIA]
 
## [需要澄清]项目
- [需要澄清：认证方式 - OAuth、SAML还是简单密码？]
- [需要澄清：数据保留政策 - 保存多长时间？]

/specify 构建一个照片管理应用，帮助我将照片整理到单独的相册中。相册按日期分组，可以在主页面上通过拖拽重新排序。相册永远不会嵌套在其他相册中。在每个相册内，照片以磁贴界面预览。

/plan 应用使用Vite构建，尽量减少库的使用。尽可能使用原生HTML、CSS和JavaScript。图片不上传到任何地方，元数据存储在本地SQLite数据库中。

/tasks

### 设置阶段
- T001: 初始化Vite项目和SQLite数据库
- T002: 配置开发环境和构建工具
 
### 测试阶段（可并行执行）
- T003 [P]: 相册管理API契约测试
- T004 [P]: 照片元数据API契约测试
- T005 [P]: 拖拽功能集成测试
 
### 实现阶段
- T006: 实现SQLite数据库模型
- T007: 实现相册管理功能
- T008: 实现照片导入和预览
- T009: 实现拖拽排序功能

/specify 开发Taskify，一个团队生产力平台。允许用户创建项目，添加团队成员，分配任务，评论并在看板风格的板块间移动任务。在这个初始阶段，我们要有多个用户但用户是预定义的。我需要5个用户分为两个类别，一个产品经理和四个工程师。让我们创建三个不同的示例项目。我们要有标准的看板列，如"待办"、"进行中"、"审查中"和"完成"。应用没有登录功能，这只是第一个测试版本。

/plan 使用.NET Aspire生成，使用Postgres作为数据库。前端应使用Blazor服务器，具有拖放任务板和实时更新。应创建REST API，包括项目API、任务API和通知API。

#### 简化门控（第VII条）
- [x] 使用≤3个项目？（Web应用 + API + 数据库）
- [x] 无未来证明？（仅实现当前需求）
 
#### 反抽象门控（第VIII条）
- [x] 直接使用框架？（直接使用Blazor和.NET Aspire）
- [x] 单一模型表示？（统一的任务和项目模型）

/tasks

### 测试优先阶段
- T001: 编写项目管理API契约测试
- T002: 编写任务CRUD操作契约测试
- T003: 编写看板拖拽行为集成测试
- T004: 获得用户对测试场景的确认
- T005: 验证所有测试均失败（红色阶段）
 
### 实现阶段（仅在测试通过后）
- T006: 实现项目管理服务使T001通过
- T007: 实现任务服务使T002通过
- T008: 实现前端拖拽使T003通过

# 5分钟：创建功能规范
/specify 实时聊天系统，支持消息历史和用户在线状态
 
# 5分钟：生成实现计划
/plan WebSocket实时消息，PostgreSQL历史，Redis在线状态
 
# 5分钟：生成可执行任务
/tasks
 
# 结果：完整的项目规范、技术计划、API契约、数据模型、任务列表

# 阶段1：核心MVP
/specify 用户认证和基本任务管理
 
# 阶段2：协作功能
/specify 任务评论和团队通知
 
# 阶段3：高级功能
/specify 项目分析和报告功能

# 功能分支命名自动化
/specify → 自动创建 003-user-management-system
 
# 合并策略
git checkout main
git merge 003-user-management-system  # 包含完整规范和计划

### 可并行执行的功能
- 001-user-authentication [开发团队A]
- 002-product-catalog [开发团队B]
- 003-order-processing [开发团队C]
 
### 依赖关系
- 003依赖001（订单需要用户认证）
- 共享的数据模型需要协调

传统问题：规范与代码逐渐偏离
SDD解决方案：规范是代码生成的唯一来源
 
变更流程：
需求变化 → 更新规范 → 重新生成计划 → 更新任务 → 重新实现

特征：每日多次部署，需求变化极快
建议：可以使用简化的SDD流程，专注/specify阶段

特征：目标不明确，大量试错
建议：等研究结果稳定后再应用SDD

特征：<100行代码，单一功能
建议：直接编码比规范编写更高效

# Linux/macOS
curl -LsSf https://astral.sh/uv/install.sh | sh
 
# Windows
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
 
# 验证安装
uv --version

# 检查Python版本
python --version  # 需要 >= 3.11
 
# 使用pyenv管理Python版本
pyenv install 3.11.0
pyenv global 3.11.0

# 检查CLAUDE.md是否正确生成
ls -la CLAUDE.md
 
# 重新初始化项目
uvx --from git+https://github.com/github/spec-kit.git specify init --here --ai claude
 
# 确认AI助手配置
cat CLAUDE.md | grep -A 5 "specify\|plan\|tasks"

# ✅ 改进输入描述示例
/specify 构建一个团队任务管理系统。产品经理需要能够创建项目和分配任务给开发人员，开发人员需要能够更新任务状态并添加进度评论，团队负责人需要能够查看项目整体进度和团队工作负载。系统应该支持5-50人的团队规模，任务状态包括待办、进行中、审查中、已完成。用户界面应该直观易用，适合技术和非技术人员使用。
 
# ❌ 避免的输入方式
/specify 用React做个看板系统，有拖拽功能，用MongoDB存数据

# 检查并修复常见违规
#### 简化门控失败
问题：生成了超过3个项目
解决：合并相关项目，如将API网关和业务服务合并
 
#### 反抽象门控失败
问题：创建了过多的抽象层
解决：直接使用框架特性，移除中间包装层
 
#### 测试优先门控失败
问题：没有契约测试计划
解决：在contracts/目录添加API规范，生成对应测试

# 检查输入文档质量
ls specs/001-feature-name/
# 确保存在：plan.md, data-model.md, contracts/
 
# 手动调整任务顺序
# 编辑 specs/001-feature-name/tasks.md
# 遵循：设置 → 测试 → 实现 → 集成 → 完善

# 分模块处理
每个功能独立一个分支和规范目录
001-user-management/
002-product-catalog/
003-order-processing/
 
# 清理旧的规范文件
find specs/ -name "*.md" -mtime +30 -type f

# 检查Git状态
git status
git branch -a
 
# 清理未完成的功能分支
git branch -D 001-incomplete-feature
 
# 重新开始功能开发
git checkout main
/specify [新的功能描述]

# .github/workflows/sdd-pipeline.yml
name: Spec-Driven Development Pipeline
on: [push, pull_request]
 
jobs:
  validate-specs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
 
      - name: Install Spec Kit
        run: |
          pip install uv
          uvx --from git+https://github.com/github/spec-kit.git specify check
 
      - name: Validate Specification Quality
        run: |
          # 检查所有[需要澄清]是否已解决
          if grep -r "\[需要澄清" specs/; then
            echo "ERROR: Found unresolved clarification markers"
            exit 1
          fi
 
      - name: Constitutional Compliance Check
        run: |
          # 验证宪法合规性
          python scripts/check-constitution-compliance.py
 
      - name: Generate Implementation Report
        run: |
          # 基于规范生成实现报告
          uvx --from git+https://github.com/github/spec-kit.git specify generate-report

# scripts/spec-review.sh
#!/bin/bash
 
echo "🔍 自动规范审查..."
 
# 检查规范完整性
for spec_file in specs/*/spec.md; do
    if ! grep -q "验收标准" "$spec_file"; then
        echo "❌ $spec_file 缺少验收标准"
        exit 1
    fi
done
 
echo "✅ 所有规范通过基本检查"

enterprise-workspace/
├── shared/
│   ├── constitution.md          # 企业统一宪法
│   ├── templates/               # 共享模板库
│   └── standards/               # 编码标准
├── frontend-app/                # 前端项目
├── backend-api/                 # 后端API
├── mobile-app/                  # 移动应用
└── data-pipeline/               # 数据管道

# 创建企业工作区
mkdir enterprise-workspace
cd enterprise-workspace
 
# 设置共享资源
mkdir shared/{templates,standards}
 
# 初始化各个项目并链接共享资源
for project in frontend-app backend-api mobile-app data-pipeline; do
    uvx --from git+https://github.com/github/spec-kit.git specify init $project --ai claude
    ln -sf ../shared/constitution.md $project/memory/constitution.md
    ln -sf ../shared/templates/* $project/templates/
done

<!-- shared/templates/enterprise-api-spec.md -->
# 企业API规范模板
 
## 业务上下文
[BUSINESS_VALUE] - 这个API为业务带来什么价值
 
## 安全要求
- OAuth 2.0认证 (企业标准)
- 所有端点必须HTTPS
- 敏感数据字段加密
 
## 性能标准
- P95响应时间 < 500ms
- 支持1000 QPS
- 99.9%可用性
 
## 合规要求
- GDPR数据保护
- SOX审计跟踪
- PCI DSS安全标准 (如涉及支付)

# 创建可重用的架构模式
shared/patterns/
├── microservices-pattern.md     # 微服务架构模式
├── event-driven-pattern.md      # 事件驱动模式
├── auth-pattern.md              # 认证授权模式
└── data-consistency-pattern.md  # 数据一致性模式

# scripts/spec-analytics.py
"""
分析历史规范质量，提供改进建议
"""
 
def analyze_spec_quality(spec_path):
    """分析规范质量指标"""
    metrics = {
        'clarity_score': calculate_clarity(spec_path),
        'completeness_score': check_completeness(spec_path),
        'testability_score': assess_testability(spec_path),
        'compliance_score': verify_constitution(spec_path)
    }
    return metrics
 
def suggest_improvements(metrics):
    """基于指标提供改进建议"""
    suggestions = []
    if metrics['clarity_score'] < 0.8:
        suggestions.append("建议增加更多业务上下文和用户价值说明")
    if metrics['testability_score'] < 0.7:
        suggestions.append("验收标准需要更具体和可量化")
    return suggestions

# 定期更新模板基于项目反馈
# scripts/template-optimization.sh
 
#!/bin/bash
echo "📊 分析规范质量数据..."
 
# 收集过去30天的规范数据
find specs/ -name "spec.md" -mtime -30 > recent_specs.txt
 
# 生成质量报告
python scripts/spec-analytics.py recent_specs.txt > quality_report.json
 
# 更新模板
python scripts/update-templates.py quality_report.json
 
echo "✨ 模板已根据质量数据优化"

# .github/workflows/spec-review.yml
name: Specification Review
on:
  pull_request:
    paths: ['specs/**']
 
jobs:
  auto-review:
    runs-on: ubuntu-latest
    steps:
      - name: Constitutional Compliance
        run: scripts/check-constitution.py
 
      - name: Business Logic Review
        run: scripts/business-review.py
 
      - name: Technical Feasibility
        run: scripts/tech-review.py
 
      - name: Request Human Review
        if: failure()
        run: |
          gh pr review --request-reviewer=architect-team
          gh pr comment --body "🚨 自动审查发现问题，需要人工审查"

# 检查跨项目API依赖
python scripts/check-api-dependencies.py \
  --consumer specs/frontend-app/contracts/ \
  --provider specs/backend-api/contracts/ \
  --report dependency-report.json