Skip to content

Commit e623751

Browse files
phodalphodal
committed
docs(spec): add documentation for Spec Driven Development
Add new documentation covering Spec-Kit and Claude Skills integration, usage, and workflow for spec-driven development in AutoDev.
1 parent 6a4c117 commit e623751

File tree

3 files changed

+417
-0
lines changed

3 files changed

+417
-0
lines changed

‎docs/spec/claude-skill.md‎

Lines changed: 186 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,186 @@
1+
---
2+
layout: default
3+
title: Claude Skill
4+
nav_order: 2
5+
parent: Spec Driven Development
6+
permalink: /spec/github-spec-kit
7+
---
8+
9+
10+
## Claude Skills 集成
11+
12+
### 什么是 Claude Skills？
13+
14+
[Anthropic Claude Skills](https://github.com/anthropics/skills) 是包含指令、脚本和资源的文件夹，Claude 动态加载以提高专业任务的性能。
15+
16+
**主要特征：**
17+
- 自包含的技能模块
18+
- 用于元数据的 YAML 前置元数据
19+
- 用于 AI 代理的 Markdown 指令
20+
- 可包含脚本、模板和资源
21+
22+
### AutoDev 如何集成 Claude Skills
23+
24+
AutoDev 从多个位置发现 Claude Skills：
25+
26+
**发现位置：**
27+
28+
1. **项目级技能**：项目根目录中包含 `SKILL.md` 的目录
29+
2. **用户级技能**：`~/.claude/skills/` 目录
30+
3. **嵌套技能**：技能目录中的子目录
31+
32+
**发现过程：**
33+
34+
1. AutoDev 扫描配置的位置查找 `SKILL.md` 文件
35+
2. 解析 YAML 前置元数据获取技能元数据
36+
3. 将技能注册为 `/skill.<名称>` 命令
37+
4. 提供带描述的智能提示
38+
39+
**技能结构：**
40+
41+
```
42+
my-skill/
43+
├── SKILL.md # 主技能定义
44+
├── examples/ # 示例文件（可选）
45+
├── templates/ # 模板文件（可选）
46+
└── scripts/ # 辅助脚本（可选）
47+
```
48+
49+
### 技能定义格式
50+
51+
```markdown
52+
---
53+
name: my-skill-name
54+
description: 清晰描述此技能的功能和使用时机
55+
version: 1.0.0
56+
author: 你的名字
57+
tags:
58+
- 类别1
59+
- 类别2
60+
---
61+
62+
# 我的技能名称
63+
64+
## 目的
65+
66+
[解释此技能的作用和使用时机]
67+
68+
## 指令
69+
70+
[AI 代理的详细指令]
71+
72+
## 示例
73+
74+
### 示例 1：基本用法
75+
```
76+
输入：...
77+
输出：...
78+
```
79+
80+
### 示例 2：高级用法
81+
```
82+
输入：...
83+
输出：...
84+
```
85+
86+
## 指南
87+
88+
- 指南 1：...
89+
- 指南 2：...
90+
- 指南 3：...
91+
92+
## 限制
93+
94+
- 限制 1：...
95+
- 限制 2：...
96+
```
97+
98+
### Anthropic 提供的示例技能
99+
100+
#### 文档技能
101+
102+
```devin
103+
# 创建带修订跟踪的 Word 文档
104+
/skill.docx 创建项目提案，包含：
105+
- 执行摘要
106+
- 技术方法
107+
- 时间表和里程碑
108+
- 预算明细
109+
启用修订跟踪以供审查
110+
111+
# 从 PDF 提取数据
112+
/skill.pdf 从 invoice.pdf 提取所有表单字段并输出为 JSON
113+
114+
# 创建 PowerPoint 演示文稿
115+
/skill.pptx 创建关于我们 Q4 结果的 10 张幻灯片演示，包含：
116+
- 标题幻灯片
117+
- 执行摘要
118+
- 收入图表
119+
- 关键指标
120+
- 未来展望
121+
122+
# 分析 Excel 电子表格
123+
/skill.xlsx 分析 sales-data.xlsx 并创建：
124+
- 按地区的数据透视表
125+
- 月度趋势图
126+
- 前 10 产品表
127+
```
128+
129+
#### 开发技能
130+
131+
```devin
132+
# 构建 React 工件
133+
/skill.artifacts-builder 创建仪表板，包含：
134+
- 实时数据可视化
135+
- 使用 Tailwind 的响应式布局
136+
- 深色模式支持
137+
- shadcn/ui 组件
138+
139+
# 测试 Web 应用
140+
/skill.webapp-testing 测试 http://localhost:3000 的登录流程：
141+
- 验证表单验证
142+
- 测试成功登录
143+
- 测试错误处理
144+
- 检查响应式设计
145+
146+
# 创建 MCP 服务器
147+
/skill.mcp-builder 为 GitHub API 创建 MCP 服务器，功能包括：
148+
- 列出仓库
149+
- 创建问题
150+
- 管理拉取请求
151+
- 处理身份验证
152+
```
153+
154+
#### 创意技能
155+
156+
```devin
157+
# 生成算法艺术
158+
/skill.algorithmic-art 使用以下方式创建生成艺术：
159+
- 流场算法
160+
- 1000 个粒子的粒子系统
161+
- 种子随机性（种子：42）
162+
- 调色板：蓝色和紫色
163+
164+
# 设计画布
165+
/skill.canvas-design 为我们的产品发布创建极简海报：
166+
- 尺寸：1920x1080
167+
- 品牌颜色
168+
- 简洁排版
169+
- 导出为 PNG 和 PDF
170+
```
171+
172+
## 协同工作方式
173+
174+
Spec-Kit 和 Claude Skills 在 AutoDev 中完美互补：
175+
176+
### Spec-Kit：流程与方法论
177+
- 提供结构化开发工作流
178+
- 从需求到实施的指导
179+
- 确保一致性和质量
180+
- 项目特定、面向工作流
181+
182+
### Claude Skills：能力与工具
183+
- 提供专业能力
184+
- 处理特定文件格式和任务
185+
- 跨项目可重用
186+
- 任务特定、面向能力

‎docs/spec/github-spec-kit.md‎

Lines changed: 158 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,158 @@
1+
---
2+
layout: default
3+
title: Github Spec Kit
4+
nav_order: 2
5+
parent: Spec Driven Development
6+
permalink: /spec/github-spec-kit
7+
---
8+
9+
## GitHub Spec-Kit 集成
10+
11+
### 什么是 Spec-Kit？
12+
13+
[GitHub Spec-Kit](https://github.com/github/spec-kit) 是一个开源工具包，支持**规范驱动开发** - 一种规范可执行、直接生成工作实现的方法论。
14+
15+
**核心理念：**
16+
- 规范在代码之前定义"做什么"
17+
- 使用护栏和组织原则创建丰富的规范
18+
- 多步骤细化而非一次性代码生成
19+
- 充分利用高级 AI 模型能力
20+
21+
### AutoDev 如何集成 Spec-Kit
22+
23+
AutoDev 自动从项目的 `.github/prompts/` 目录发现并加载 SpecKit 命令，使其可作为 DevIns 命令使用。
24+
25+
**发现过程：**
26+
27+
1. AutoDev 扫描 `.github/prompts/` 查找匹配 `speckit.*.prompt.md` 的文件
28+
2. 每个文件成为一个命令：`/speckit.<子命令>`
29+
3. 解析命令的 YAML 前置元数据和模板内容
30+
4. 在 DevIns 编辑器中提供完整的智能提示支持
31+
32+
**文件结构：**
33+
34+
```
35+
your-project/
36+
└── .github/
37+
└── prompts/
38+
├── speckit.constitution.prompt.md
39+
├── speckit.specify.prompt.md
40+
├── speckit.plan.prompt.md
41+
├── speckit.tasks.prompt.md
42+
└── speckit.implement.prompt.md
43+
```
44+
45+
### 可用的 SpecKit 命令
46+
47+
#### 核心工作流命令
48+
49+
1. **`/speckit.constitution`** - 建立项目原则
50+
- 创建或更新项目治理原则
51+
- 定义开发指南和标准
52+
- 设置质量、测试和性能要求
53+
54+
2. **`/speckit.specify`** - 定义需求
55+
- 创建功能规范
56+
- 定义用户故事和需求
57+
- 关注"做什么"和"为什么"，而非技术栈
58+
59+
3. **`/speckit.plan`** - 创建实施计划
60+
- 生成技术实施细节
61+
- 指定技术栈和架构
62+
- 创建详细的组件分解
63+
64+
4. **`/speckit.tasks`** - 生成任务分解
65+
- 创建可执行的任务列表
66+
- 按依赖关系排序任务
67+
- 标记并行执行机会
68+
69+
5. **`/speckit.implement`** - 执行实施
70+
- 按顺序执行所有任务
71+
- 如果指定则遵循 TDD 方法
72+
- 提供进度更新
73+
74+
#### 质量与验证命令
75+
76+
6. **`/speckit.clarify`** - 澄清需求
77+
- 结构化提问工作流
78+
- 基于覆盖率的澄清
79+
- 在规范中记录答案
80+
81+
7. **`/speckit.analyze`** - 分析一致性
82+
- 跨工件一致性检查
83+
- 覆盖率分析
84+
- 差距识别
85+
86+
8. **`/speckit.checklist`** - 生成质量检查清单
87+
- 创建验证检查清单
88+
- 确保完整性和清晰度
89+
- "英语的单元测试"
90+
91+
### 模板变量与前置元数据
92+
93+
SpecKit 命令支持 YAML 前置元数据以实现高级模板功能：
94+
95+
```markdown
96+
---
97+
variables:
98+
- name: project_name
99+
type: string
100+
description: 项目名称
101+
- name: tech_stack
102+
type: file
103+
path: .github/tech-stack.md
104+
---
105+
106+
# ${project_name} 的实施计划
107+
108+
使用技术栈：
109+
${tech_stack}
110+
111+
用户需求：
112+
$ARGUMENTS
113+
```
114+
115+
**支持的变量类型：**
116+
- `string` - 简单字符串值
117+
- `file` - 从文件路径加载内容
118+
- `project` - 项目级元数据
119+
120+
**内置变量：**
121+
- `$ARGUMENTS` - 用户提供的命令参数
122+
- `${project.name}` - 当前项目名称
123+
- `${project.basePath}` - 项目根目录
124+
125+
### 示例：完整的规范驱动工作流
126+
127+
```devin
128+
# 步骤 1：建立原则
129+
/speckit.constitution 创建关注以下方面的原则：
130+
- 代码质量和可维护性
131+
- 全面测试（单元、集成、端到端）
132+
- 用户体验一致性
133+
- 性能要求（< 100ms 响应时间）
134+
135+
# 步骤 2：定义要构建的内容
136+
/speckit.specify 构建一个相册应用，具有以下功能：
137+
- 按日期自动组织照片
138+
- 支持拖放重新组织
139+
- 以瓷砖式界面显示照片
140+
- 相册之间永不嵌套
141+
- 每个相册显示 5-15 张照片
142+
143+
# 步骤 3：澄清需求
144+
/speckit.clarify
145+
146+
# 步骤 4：创建技术计划
147+
/speckit.plan 使用：
148+
- React 18 with TypeScript
149+
- Vite 作为构建工具
150+
- SQLite 用于本地元数据存储
151+
- 最少的外部依赖
152+
153+
# 步骤 5：生成任务
154+
/speckit.tasks
155+
156+
# 步骤 6：实施
157+
/speckit.implement
158+
```

0 commit comments

Comments
 (0)