spec-kit-skill

检测项目状态

继续之前，务必检测当前状态：

1. CLI 已安装？

if command -v specify &> /dev/null || [ -x "$HOME/.local/bin/specify" ]; then
  echo "CLI installed"
else
  echo "CLI not installed - guide user through installation"
fi

2. 项目已初始化？

if [ -d ".specify" ] && [ -f ".specify/memory/constitution.md" ]; then
  echo "Project initialized"
else
  echo "Project not initialized - guide user through 'specify init'"
fi

3. 当前功能

# Get latest feature directory
LATEST=$(ls -d .specify/specs/[0-9]* 2>/dev/null | sort -V | tail -1)
echo "Latest feature: $LATEST"

4. 当前阶段

通过检查最新功能中的文件是否存在来检测阶段：

FEATURE_DIR=".specify/specs/001-feature-name"

if [ ! -f ".specify/memory/constitution.md" ]; then
  echo "Phase: constitution"
elif [ ! -d "$FEATURE_DIR" ]; then
  echo "Phase: specify"
elif [ -f "$FEATURE_DIR/spec.md" ] && ! grep -q "## Clarifications" "$FEATURE_DIR/spec.md"; then
  echo "Phase: clarify"
elif [ ! -f "$FEATURE_DIR/plan.md" ]; then
  echo "Phase: plan"
elif [ ! -f "$FEATURE_DIR/tasks.md" ]; then
  echo "Phase: tasks"
elif [ -f "$FEATURE_DIR/tasks.md" ] && grep -q "\\- \\[ \\]" "$FEATURE_DIR/tasks.md"; then
  echo "Phase: implement"
else
  echo "Phase: complete"
fi

章程阶段

确立指导所有开发决策的基础原则。

目的

创建 .specify/memory/constitution.md，其中包含：

• 项目价值观和原则
• 技术标准
• 决策框架
• 代码质量要求
• 架构指南

流程

1. 收集背景信息

   • 了解项目领域
   • 确定关键利益相关者
   • 审查现有标准（如有）

2. 起草章程

   • 核心价值观和原则
   • 技术标准
   • 质量要求
   • 决策标准

3. 结构

# Project Constitution

## Core Values

1. **[Value Name]**: [Description and implications]
2. **[Value Name]**: [Description and implications]

## Technical Principles

### Architecture
- [Principle with rationale]

### Code Quality
- [Standards and expectations]

### Performance
- [Performance criteria]

## Decision Framework

When making technical decisions, consider:
1. [Criterion with priority]
2. [Criterion with priority]

4. 版本管理
   • 章程可以演进
   • 跟踪变更以进行治理
   • 定期审查

内容示例

# Project Constitution

## Core Values

1. **Simplicity Over Cleverness**: Favor straightforward solutions that are easy to understand and maintain over clever optimizations.

2. **User Experience First**: Every technical decision should improve or maintain user experience.

## Technical Principles

### Architecture
- Prefer composition over inheritance
- Keep components loosely coupled
- Design for testability

### Code Quality
- Code reviews required for all changes
- Unit test coverage > 80%
- Documentation for public APIs

### Performance
- Page load < 3 seconds
- API response < 200ms
- Progressive enhancement for slower connections

## Decision Framework

When choosing between approaches:
1. Does it align with our core values?
2. Is it maintainable by the team?
3. Does it scale with our growth?
4. What's the long-term cost?

规范阶段

定义需要构建什么以及为什么，避免涉及具体技术。

脚本用法

# Create new feature
.specify/scripts/bash/create-new-feature.sh --json "feature-name"

# Expected JSON output:
# {"BRANCH_NAME": "001-feature-name", "SPEC_FILE": "/path/to/.specify/specs/001-feature-name/spec.md"}

解析 JSON：提取 BRANCH_NAME 和 SPEC_FILE，用于后续操作。

模板结构

加载 .specify/templates/spec-template.md 以了解必需的章节，然后在 SPEC_FILE 指定的位置创建规范。

规范内容

侧重于功能需求：

# Feature Specification: [Feature Name]

## Problem Statement

[What problem are we solving?]

## User Stories

### Story 1: [Title]

As a [role]
I want [capability]
So that [benefit]

**Acceptance Criteria:**
- [ ] [Specific, testable criterion]
- [ ] [Specific, testable criterion]

### Story 2: [Title]

[Continue...]

## Non-Functional Requirements

- Performance: [Specific metrics]
- Security: [Requirements]
- Accessibility: [Standards]
- Scalability: [Expectations]

## Success Metrics

- [Measurable outcome]
- [Measurable outcome]

## Out of Scope

[Explicitly state what's NOT included]

核心原则

• 技术无关：不要指定“使用 React”或“MySQL”
• 关注结果：描述用户能实现什么，而不是如何实现
• 可测试：验收标准必须可验证
• 完整：涵盖边缘情况和错误场景

Git 集成

脚本会自动：

• 创建新的功能分支（例如，001-feature-name）
• 切换到该分支
• 初始化规范文件

澄清阶段

通过有针对性的提问，解决定义不充分的部分。

目的

在规划实现之前，确保规范完整且没有歧义。

1. 分析规范

   • 通读 spec.md
   • 找出模糊之处、缺漏和假设
   • 记录存在多种有效解释的部分

2. 生成问题（最多 5 个）

   • 优先处理影响重大的事项
   • 聚焦影响架构的决策
   • 询问边缘情况和错误处理

3. 问题格式

## Clarifications

### Q1: [Clear, specific question]

**Context**: [Why this matters]
**Options**: [If multiple approaches exist]

### Q2: [Clear, specific question]

**Context**: [Why this matters]
**Impact**: [What decisions depend on this]

4. 更新规范
   • 在 spec.md 中添加“## Clarifications”部分
   • 记录问题和答案
   • 根据答案更新相关部分
   • 迭代，直至所有关键问题都得到解答

指南

• 每轮最多 5 个问题
• 具体而非笼统：“应如何处理并发编辑？”而非“应该如何运作？”
• 以决策为导向：提出有助于确定技术选择的问题
• 循序渐进：可进行多轮澄清

示例问题

## Clarifications

### Q1: How should the system handle conflicts when two users edit the same document simultaneously?

**Context**: This affects data model design and user experience.
**Options**:
- Last-write-wins (simple, may lose data)
- Operational transforms (complex, preserves all edits)
- Locked editing (simple, limits collaboration)

**Answer**: [User provides answer]

### Q2: What's the maximum number of concurrent users we need to support?

**Context**: Affects infrastructure planning and architecture decisions.
**Impact**: Determines caching strategy, database choices, and scaling approach.

**Answer**: [User provides answer]

计划阶段

基于已明确的规范，制定技术实施策略。

脚本用法

# Setup plan phase
.specify/scripts/bash/setup-plan.sh --json

# Expected JSON output:
# {"FEATURE_SPEC": "/path/spec.md", "IMPL_PLAN": "/path/plan.md", "SPECS_DIR": "/path/specs", "BRANCH": "001-feature"}

要创建的文档

1. 主计划（plan.md）

# Implementation Plan: [Feature Name]

## Technology Stack

### Frontend
- Framework: [Choice with rationale]
- State Management: [Choice with rationale]
- Styling: [Choice with rationale]

### Backend
- Language/Framework: [Choice with rationale]
- Database: [Choice with rationale]
- API Style: [REST/GraphQL/etc with rationale]

## Architecture

### System Overview

```mermaid
graph TD
    A[Client] --> B[API Gateway]
    B --> C[Service Layer]
    C --> D[Data Layer]

组件设计

组件 1：[名称]

• 职责：[功能说明]
• 接口：[提供的 API]
• 依赖项：[所需内容]

[为所有组件继续编写...]

设计模式

• [模式]：[使用位置和原因]

安全注意事项

• 身份验证：[方案]
• 授权：[方案]
• 数据保护：[方案]

性能策略

• 缓存：[策略]
• 优化：[重点领域]

错误处理

• 错误类型和处理策略
• 日志记录和监控方案

#### 2. Data Model (`data-model.md`)

```markdown
# Data Model

## Entity Relationship

```mermaid
erDiagram
    USER ||--o{ DOCUMENT : creates
    USER {
        string id
        string email
        string role
    }
    DOCUMENT {
        string id
        string title
        string content
    }

架构

用户

interface User {
  id: string;
  email: string;
  role: 'admin' | 'editor' | 'viewer';
  createdAt: Date;
}

[为所有实体继续编写...]

#### 3. API Contracts (`contracts/`)

Create API specifications:
- `api-spec.json` (OpenAPI/Swagger)
- `signalr-spec.md` (if using SignalR)
- Other contract definitions

#### 4. Research (`research.md`) - Optional

Document technology investigations:

```markdown
# Research: [Topic]

## Options Evaluated

### Option 1: [Technology]
**Pros**: [Benefits]
**Cons**: [Drawbacks]
**Fit**: [How well it matches our needs]

### Option 2: [Technology]
[Same structure...]

## Recommendation

[Chosen option with rationale]

## References

- [Source 1]
- [Source 2]

5. 快速入门（quickstart.md）- 可选

为开发者提供设置说明。

一致性检查

最终定稿前：

• ✅ 计划是否涵盖所有需求？
• ✅ 是否遵循章程原则？
• ✅ 技术选择是否有充分依据？
• ✅ 是否已识别依赖项？
• ✅ 是否可实施？

任务阶段

生成按依赖关系排序、可执行的实施任务。

前置条件脚本

# Check prerequisites
.specify/scripts/bash/check-prerequisites.sh --json [--require-tasks] [--include-tasks]

# Output: {"FEATURE_DIR": "/path", "AVAILABLE_DOCS": ["spec.md", "plan.md", ...]}

任务生成

创建 .specify/specs/NNN-feature/tasks.md：

# Implementation Tasks: [Feature Name]

## Phase 1: Foundation

- [ ] 1.1 Set up project structure
  - Create directory layout per architecture doc
  - Configure build tools
  - Initialize testing framework
  - **Depends on**: None
  - **Requirement**: R1.1

- [ ] 1.2 [P] Configure development environment
  - Set up linters and formatters
  - Configure CI/CD pipeline basics
  - **Depends on**: 1.1
  - **Requirement**: R1.2

## Phase 2: Core Implementation

- [ ] 2.1 Implement User model and persistence
  - Create User entity with validation
  - Implement repository pattern
  - Write unit tests
  - **Depends on**: 1.1
  - **Requirement**: R2.1, R2.3

- [ ] 2.2 [P] Implement Document model
  - Create Document entity
  - Define relationships with User
  - Write unit tests
  - **Depends on**: 1.1
  - **Requirement**: R2.2

- [ ] 2.3 Implement API endpoints
  - Create REST controllers
  - Add request/response validation
  - Write integration tests
  - **Depends on**: 2.1, 2.2
  - **Requirement**: R3.1, R3.2

[Continue with all phases...]

## Phase N: Integration & Testing

- [ ] N.1 End-to-end testing
  - Write E2E test scenarios
  - Test critical user paths
  - **Depends on**: [all previous]
  - **Requirement**: All

## Notes

- `[P]` indicates tasks that can be parallelized
- Always check dependencies before starting
- Reference requirements for acceptance criteria

任务特征

每项任务都应：

• 具体且可执行
• 引用需求（R1.1、R2.3 等）
• 列出依赖项
• 可在 1-4 小时内完成
• 具备明确的验收标准

任务类型：

• 实施任务（编写代码）
• 测试任务（编写测试）
• 配置任务（设置工具）
• 集成任务（连接组件）

不包括：

• 部署任务
• 用户培训
• 营销活动
• 非编码工作

依赖标记

• 无：可立即开始
• 1.1：必须先完成任务 1.1
• 1.1、2.2：必须先完成这两项
• [P]：可与同级任务并行执行

分析阶段

跨文档的一致性和质量验证（只读）。

目的

实施前，验证：

• 所有需求均由任务覆盖
• 计划与章程一致
• 文档之间没有冲突
• 没有遗漏依赖项

分析流程

1. 阅读所有文档

   • 章程
   • 规范
   • 计划
   • 数据模型
   • 任务

2. 覆盖检查

# Extract requirements
grep -E "R[0-9]+\.[0-9]+" spec.md | sort -u > requirements.txt

# Extract referenced requirements in tasks
grep -E "Requirement.*R[0-9]+" tasks.md | sort -u > covered.txt

# Compare
comm -23 requirements.txt covered.txt

3. 一致性检查

章程一致性：

• 计划是否遵循既定原则？
• 架构选择是否依据章程进行了论证？

需求覆盖：

• 任务是否涵盖每项需求？
• 验收标准是否可测试？

技术一致性：

• 数据模型是否满足规范要求？
• API 契约是否与计划一致？
• 依赖项是否合理？

任务依赖关系：

• 所有依赖项是否有效？
• 是否已识别关键路径？
• 是否存在循环依赖？

4. 报告发现

# Analysis Report

## ✅ Passing Checks

- All requirements covered
- Constitution alignment verified
- No circular dependencies

## ⚠️ Warnings

- Requirement R3.4 has no corresponding task
- Task 5.2 references undefined dependency

## 🔴 Critical Issues

None found

## Recommendations

1. Add task for Requirement R3.4
2. Clarify dependency for task 5.2
3. Consider breaking task 6.1 into smaller tasks (estimated 8 hours)

指南

• 只读：不要修改文档
• 客观：报告事实，而非观点
• 可执行：提供具体建议
• 优先排序：先处理关键问题

实施阶段

系统地执行任务，并遵循依赖关系和测试驱动开发。

实施策略

1. 分阶段执行

   • 完成阶段 1 的所有任务后，再开始阶段 2
   • 遵循任务依赖关系
   • 利用并行标记 [P]

2. 任务执行模式

# For each task:
# 1. Read context
cat .specify/specs/001-feature/spec.md
cat .specify/specs/001-feature/plan.md
cat .specify/specs/001-feature/data-model.md

# 2. Check dependencies
# Verify all depends-on tasks are complete

# 3. Implement
# Write code per task description

# 4. Test
# Write and run tests

# 5. Validate
# Check against requirements

# 6. Mark complete
# Update tasks.md: - [x] task completed

3. 测试驱动方法

对于每项任务：

• 先编写测试（如适用）
• 实施代码以通过测试
• 在保持测试通过的同时进行重构
• 在连接组件时进行集成测试

4. 质量检查

标记任务完成前：

• 代码符合计划架构
• 已编写测试且测试通过
• 符合验收标准
• 没有明显的错误
• 已与之前的工作集成

错误处理

如果实施过程中发现问题：

1. 设计问题：返回计划阶段，更新计划
2. 需求缺口：返回需求编写／澄清阶段，更新规范
3. 技术阻碍：记录并上报给用户

进度跟踪

随时更新 tasks.md：

- [x] 1.1 Set up project structure ✓ Complete
- [x] 1.2 [P] Configure development environment ✓ Complete
- [ ] 2.1 Implement User model ← Currently here
- [ ] 2.2 [P] Implement Document model

完成标准

满足以下条件时，功能即为完成：

• 所有任务均已标记为完成
• 所有测试均已通过
• 所有需求均已验证
• 代码已审查（如适用）
• 文档已更新