Initial commit
This commit is contained in:
Zhongwei Li
559
commands/spec.md
Normal file
559
commands/spec.md
Normal file
@@ -0,0 +1,559 @@
|
||||
## Spec
|
||||
|
||||
**「在編寫代碼之前赋予結構」** - 完全遵循 Kiro 的規格驅動開發
|
||||
|
||||
與傳統代碼生成工具不同，實現 Kiro 的規格驅動開發，重點是為開發的混沌赋予結構。從最少的需求輸入，逐步展開到產品經理級別的詳细規格和可實施的設計，**從原型到生產環境**保證一致的質量。
|
||||
|
||||
### 使用方法
|
||||
|
||||
```bash
|
||||
# 請求 Claude 的 Spec Mode(最少需求輸入)
|
||||
「創建[功能描述]的 spec」
|
||||
|
||||
# Kiro 式分阶段展開：
|
||||
# 1. 簡單需求 → 自動生成詳细用戶故事
|
||||
# 2. 使用 EARS 記法的結構化需求描述
|
||||
# 3. 通過分阶段對話精细化規格
|
||||
# 4. 生成 3 個独立文件：
|
||||
# - requirements.md: EARS 記法的需求定義
|
||||
# - design.md: 包含 Mermaid 圖、TypeScript 接口的設計
|
||||
# - tasks.md: 自動應用最佳實践的實施計劃
|
||||
```
|
||||
|
||||
### 實證效果 (Kiro 實績)
|
||||
|
||||
**2 天完成安全文件共享應用**
|
||||
|
||||
```bash
|
||||
「創建文件共享系統 (支持加密) 的 spec」
|
||||
→ 2 天完成生產級別的加密文件共享應用
|
||||
→ 自動應用安全最佳實践
|
||||
→ 無需额外提示
|
||||
```
|
||||
|
||||
**新手一晚開發遊戲**
|
||||
|
||||
```bash
|
||||
「創建 2D 益智遊戲的 spec」
|
||||
→ 遊戲開發新手的開源開發者
|
||||
→ 一晚完成遊戲創建
|
||||
→ 實現邏輯由 Kiro 處理，開發者專注創造性
|
||||
```
|
||||
|
||||
**週末從原型到生產**
|
||||
|
||||
```bash
|
||||
「創建電商網站商品管理系統的 spec」
|
||||
→ 一個週末從概念到可運行的原型
|
||||
→ 從原型到生產環境的一致質量
|
||||
→ 通過 spec-driven development 的結構化方法
|
||||
```
|
||||
|
||||
### 基本示例
|
||||
|
||||
```bash
|
||||
# 新功能的 spec 創建 (最少輸入)
|
||||
「商品評論系統
|
||||
- 星級評分功能
|
||||
- 評論發布
|
||||
- 圖片上傳」
|
||||
|
||||
# 系統功能的 spec 創建
|
||||
「用戶認證
|
||||
- OAuth 支持
|
||||
- 多因素認證」
|
||||
|
||||
# API 功能的 spec 創建
|
||||
「支付系統 API
|
||||
- Stripe 集成
|
||||
- 重視安全性」
|
||||
```
|
||||
|
||||
### 與 Claude 配合
|
||||
|
||||
```bash
|
||||
# 復杂功能 spec
|
||||
「創建聊天功能的 spec。包括 WebSocket、實時通知、歷史管理」
|
||||
|
||||
# 數據庫關聯功能 spec
|
||||
「創建電商網站庫存管理功能的 spec。包括商品添加、庫存更新、警報功能」
|
||||
|
||||
# 前端功能 spec
|
||||
「創建 React 儀表板的 spec。包括圖表顯示、筛選器、導出功能」
|
||||
|
||||
# 後端功能 spec
|
||||
「創建 RESTful API 的 spec。包括認證、驗證、日誌記錄」
|
||||
```
|
||||
|
||||
### Spec Mode 的特點
|
||||
|
||||
**分阶段對話工作流**
|
||||
|
||||
- 完全再現 Kiro 的核心價值——分阶段讨論
|
||||
- 在各阶段與用戶合作精细化規格
|
||||
- 經過疑問解決、選項讨論、批準流程後生成文件
|
||||
|
||||
**3 阶段的交互式展開**
|
||||
|
||||
- **Phase 1**: Requirements Discovery → 讨論 → 批準 → 生成 `requirements.md`
|
||||
- **Phase 2**: Design Exploration → 讨論 → 批準 → 生成 `design.md`
|
||||
- **Phase 3**: Implementation Planning → 讨論 → 批準 → 生成 `tasks.md`
|
||||
|
||||
**動態規格制定**
|
||||
|
||||
- 通過對話解決需求的模糊性
|
||||
- 提示和讨論技術選項
|
||||
- 說明權衡並確認判斷
|
||||
|
||||
### 詳细示例
|
||||
|
||||
```bash
|
||||
# 復杂系統功能
|
||||
「創建在線支付系統的 spec。包括 Stripe 集成、安全性、錯誤處理」
|
||||
|
||||
# 前端功能
|
||||
「創建 React 組件的 spec。包括狀態管理、属性設計、測試」
|
||||
|
||||
# 後端功能
|
||||
「創建 GraphQL API 的 spec。包括 Schema 設計、解析器、認證」
|
||||
|
||||
# DevOps 功能
|
||||
「創建 CI/CD 管道的 spec。包括測試自動化、部署、監控」
|
||||
```
|
||||
|
||||
### 分阶段對話工作流 (Phase by Phase)
|
||||
|
||||
#### Phase 1: Requirements Discovery & Discussion
|
||||
|
||||
**1. 從最少輸入自動擴展 (Kiro 式)**
|
||||
|
||||
```text
|
||||
用戶：「用戶管理系統
|
||||
- 登錄功能
|
||||
- 個人資料編輯
|
||||
- 管理员權限」
|
||||
|
||||
Claude：「從需求生成詳细用戶故事。
|
||||
這個理解正確吗？
|
||||
|
||||
自動生成的用戶故事：
|
||||
- 用戶注冊和認證功能 (支持 OAuth)
|
||||
- 個人資料管理功能 (头像、設置)
|
||||
- 權限管理功能 (RBAC)
|
||||
- 密碼重置功能
|
||||
- 安全審計日誌
|
||||
|
||||
已補充未明確的细节。還需要其他功能吗？」
|
||||
```
|
||||
|
||||
**2. 使用 EARS 記法的結構化需求描述**
|
||||
|
||||
```text
|
||||
Claude：「使用 Kiro 的 EARS 記法結構化需求：
|
||||
|
||||
EARS 記法需求定義：
|
||||
|
||||
WHEN 用戶尝試登錄時
|
||||
GIVEN 輸入正確的郵箱和密碼
|
||||
THEN 系統確認認證
|
||||
AND 成功時重定向到儀表板
|
||||
|
||||
WHILE 用戶在個人資料編輯页面時
|
||||
THE SYSTEM SHALL 實時執行驗證
|
||||
AND 預覽顯示更改內容
|
||||
|
||||
WHERE 需要管理员權限的功能
|
||||
IS 尝試訪問時
|
||||
THE SYSTEM SHALL 確認權限級別
|
||||
AND 不足時拒绝訪問」
|
||||
```
|
||||
|
||||
**3. 邊緣情况和安全需求的自動補充**
|
||||
|
||||
```text
|
||||
Claude：「基于 Kiro 的最佳實践，還考虑了以下情况：
|
||||
|
||||
安全需求 (自動補充)：
|
||||
- 暴力攻擊對策
|
||||
- 會話管理和超時
|
||||
- CSRF 保護和 XSS 對策
|
||||
- 密碼強度要求
|
||||
|
||||
邊緣情况 (自動檢測)：
|
||||
- 同時登錄限制
|
||||
- 账戶鎖定功能
|
||||
- 數據遷移時的一致性保證
|
||||
- 大量請求時的負載均衡
|
||||
|
||||
這些需求合適吗？」
|
||||
```
|
||||
|
||||
**5. Phase 1 完成和批準**
|
||||
|
||||
```text
|
||||
Claude：「Requirements Phase 已完成。
|
||||
可以生成 requirements.md 吗？」
|
||||
→ 「繼續」→ 生成 requirements.md
|
||||
```
|
||||
|
||||
#### Phase 2: Design Exploration & Discussion
|
||||
|
||||
**1. 代碼庫分析 + 自動設計建議 (Kiro 式)**
|
||||
|
||||
```text
|
||||
Claude：「分析現有代碼庫，提出最佳架構：
|
||||
|
||||
代碼庫分析結果：
|
||||
- 認證：JWT + Express.js(v4.18.x)
|
||||
- 數據庫：PostgreSQL(v14+)
|
||||
- 前端：React + TypeScript(v18+)
|
||||
- 現有模式：Repository 模式、Service 層分離
|
||||
|
||||
Kiro 推薦架構：
|
||||
- 符合 Clean Architecture
|
||||
- Domain-Driven Design 元素
|
||||
- 部分應用 CQRS 模式
|
||||
- 自動化的安全最佳實践
|
||||
|
||||
使用這個設計吗？」
|
||||
```
|
||||
|
||||
**2. 使用 Mermaid 圖的可視化設計**
|
||||
|
||||
```text
|
||||
Claude：「自動生成系統設計的 Mermaid 圖：
|
||||
|
||||
自動生成的架構圖：
|
||||
|
||||
graph TB
|
||||
Client[React Client] --> API[Express API Gateway]
|
||||
API --> Auth[Auth Service]
|
||||
API --> User[User Service]
|
||||
API --> Profile[Profile Service]
|
||||
|
||||
Auth --> AuthDB[(Auth Database)]
|
||||
User --> UserDB[(User Database)]
|
||||
Profile --> ProfileDB[(Profile Database)]
|
||||
|
||||
Auth --> JWT[JWT Service]
|
||||
Auth --> OAuth[OAuth Provider]
|
||||
|
||||
還需要生成數據流圖吗？」
|
||||
```
|
||||
|
||||
**3. TypeScript 接口自動生成**
|
||||
|
||||
```text
|
||||
Claude：「基于設計自動生成 TypeScript 接口：
|
||||
|
||||
自動生成的 TypeScript 接口：
|
||||
|
||||
// Domain entities
|
||||
interface User {
|
||||
readonly id: UserId;
|
||||
readonly email: Email;
|
||||
readonly profile: UserProfile;
|
||||
readonly auth: AuthSettings;
|
||||
readonly permissions: Permission[];
|
||||
readonly createdAt: Date;
|
||||
readonly updatedAt: Date;
|
||||
}
|
||||
|
||||
interface UserProfile {
|
||||
readonly displayName: string;
|
||||
readonly avatar: AvatarUrl;
|
||||
readonly preferences: UserPreferences;
|
||||
}
|
||||
|
||||
interface AuthSettings {
|
||||
readonly passwordHash: PasswordHash;
|
||||
readonly mfaEnabled: boolean;
|
||||
readonly lastLoginAt: Date;
|
||||
readonly failedAttempts: number;
|
||||
}
|
||||
|
||||
// Use cases
|
||||
interface UserRepository {
|
||||
findById(id: UserId): Promise<User | null>;
|
||||
findByEmail(email: Email): Promise<User | null>;
|
||||
save(user: User): Promise<void>;
|
||||
}
|
||||
|
||||
interface AuthenticationService {
|
||||
authenticate(credentials: LoginCredentials): Promise<AuthResult>;
|
||||
refreshToken(token: RefreshToken): Promise<AccessToken>;
|
||||
}
|
||||
|
||||
使用這個接口設計吗？」
|
||||
```
|
||||
|
||||
**4. Phase 2 完成和批準**
|
||||
|
||||
```text
|
||||
|
||||
Claude：「Design Phase 已完成。
|
||||
可以生成 design.md 吗？」
|
||||
→ 「繼續」→ 生成 design.md
|
||||
|
||||
```
|
||||
|
||||
#### Phase 3: Implementation Planning & Discussion
|
||||
|
||||
**1. 最佳實践自動應用 (Kiro 式)**
|
||||
|
||||
```text
|
||||
|
||||
Claude：「生成了自動應用 Kiro 最佳實践的實施計劃：
|
||||
|
||||
自動生成的實施策略：
|
||||
|
||||
1. 安全第一開發
|
||||
- 自動集成 OWASP Top 10 對策
|
||||
- 自動實現加密和哈希
|
||||
- 自動生成安全測試
|
||||
|
||||
2. 強制清洁架構
|
||||
- 自動實現層分離
|
||||
- 自動應用依賴倒置
|
||||
- 強制可測試設計
|
||||
|
||||
3. 性能優化
|
||||
- 自動實現緩存策略
|
||||
- 數據庫優化
|
||||
- 利用異步處理
|
||||
|
||||
使用這個方法吗？」
|
||||
|
||||
```
|
||||
|
||||
**2. 質量檢查點自動設置**
|
||||
|
||||
```text
|
||||
|
||||
Claude：「自動設置各實施阶段的質量檢查點：
|
||||
|
||||
自動質量保證流程：
|
||||
|
||||
Phase 3a: 後端實施
|
||||
|
||||
- [ ] 安全掃描 (SAST/DAST)
|
||||
- [ ] API 規範測試 (OpenAPI 合規)
|
||||
- [ ] 性能測試 (負載和響應)
|
||||
- [ ] 漏洞掃描 (依賴關系和 CVE)
|
||||
|
||||
Phase 3b: 前端實施
|
||||
|
||||
- [ ] 無障礙測試 (WCAG 2.1 AA)
|
||||
- [ ] 瀏覽器兼容性測試
|
||||
- [ ] 響應式設計驗證
|
||||
- [ ] 安全头確認
|
||||
|
||||
Phase 3c: 集成和部署
|
||||
|
||||
- [ ] E2E 測試套件
|
||||
- [ ] CI/CD 管道配置
|
||||
- [ ] 監控和日誌設置
|
||||
- [ ] 生產環境安全審計
|
||||
|
||||
全部自動執行。有额外的質量標準吗？」
|
||||
|
||||
```
|
||||
|
||||
**3. 依賴關系和風險緩解的自動分析**
|
||||
|
||||
```text
|
||||
|
||||
Claude：「自動分析實施顺序和風險緩解策略：
|
||||
|
||||
優化的實施顺序：
|
||||
|
||||
Week 1: 基礎設施和安全基礎
|
||||
|
||||
- 數據庫設計和模式創建
|
||||
- 認證基礎 (JWT + 會話管理)
|
||||
- 安全中間件實施
|
||||
- 基本 API 端點
|
||||
|
||||
Week 2: 核心功能實施
|
||||
|
||||
- 用戶管理功能
|
||||
- 個人資料管理功能
|
||||
- 權限管理系統
|
||||
- 驗證和錯誤處理
|
||||
|
||||
Week 3: 高級功能和優化
|
||||
|
||||
- 多因素認證實施
|
||||
- 審計日誌功能
|
||||
- 性能優化
|
||||
- 前端集成
|
||||
|
||||
自動檢測的風險緩解策略：
|
||||
|
||||
- 多因素認證：分阶段引入 (SMS→應用認證)
|
||||
- 會話管理：Redis 集群配置
|
||||
- 大量訪問：速率限制 + CDN 利用
|
||||
- 數據一致性：加強事務管理
|
||||
|
||||
這個計劃没有問題吗？」
|
||||
|
||||
```
|
||||
|
||||
**4. Phase 3 完成和批準**
|
||||
|
||||
```text
|
||||
|
||||
Claude：「Implementation Planning Phase 已完成。
|
||||
可以生成 tasks.md 吗？」
|
||||
→ 「繼續」→ 生成 tasks.md
|
||||
|
||||
```
|
||||
|
||||
### Kiro 特有的功能
|
||||
|
||||
**EARS 記法 (Easy Approach to Requirements Syntax)**
|
||||
|
||||
```text
|
||||
# Kiro 標準的 EARS 記法模式
|
||||
|
||||
WHEN [情况・觸發器]
|
||||
GIVEN [前提條件]
|
||||
THEN [系統行為]
|
||||
AND [额外行為]
|
||||
|
||||
WHILE [狀態・流程]
|
||||
THE SYSTEM SHALL [必须行為]
|
||||
AND [相關行為]
|
||||
|
||||
WHERE [功能・組件]
|
||||
IS [條件・狀態]
|
||||
THE SYSTEM SHALL [對應行為]
|
||||
```
|
||||
|
||||
**自動生成功能**
|
||||
|
||||
- **Mermaid 圖**: 自動生成架構和數據流圖
|
||||
- **TypeScript 接口**: 基于設計自動創建類型定義
|
||||
- **最佳實践**: 自動集成安全和性能對策
|
||||
- **質量檢查點**: 自動設置分阶段質量標準
|
||||
|
||||
**hooks 聯動**
|
||||
|
||||
- 文件保存時的自動質量檢查
|
||||
- 自動應用代碼標準
|
||||
- 自動執行安全掃描
|
||||
- 自動驗證 OWASP Top 10 對策
|
||||
|
||||
**原型→生產質量保證**
|
||||
|
||||
- 通過結構化方法的一致設計
|
||||
- 強制安全第一開發
|
||||
- 自動應用可擴展架構
|
||||
- 集成持續質量管理
|
||||
|
||||
### 注意事項
|
||||
|
||||
**適用範圍**
|
||||
|
||||
- Spec Mode 最適合功能實施
|
||||
- 簡單修復或小規模更改使用常規實施形式
|
||||
- 推薦用于新功能開發或復杂功能改造
|
||||
|
||||
**質量保證**
|
||||
|
||||
- 明確各阶段的完成標準
|
||||
- 實施前的設計審查
|
||||
- 包括測試和無障礙的全面質量標準
|
||||
|
||||
**執行注意事項**
|
||||
|
||||
- 解決需求的模糊性後再進入設計阶段
|
||||
- 設計完成後生成實施任務
|
||||
- 重視各阶段的批準流程
|
||||
|
||||
### 觸發短語和控制
|
||||
|
||||
#### 分阶段工作流控制
|
||||
|
||||
**開始觸發器**
|
||||
|
||||
- 「創建[功能名]的 spec」
|
||||
- 「想用 spec 驅動開發[功能名]」
|
||||
- 「從規格書設計[功能名]」
|
||||
|
||||
**阶段進度控制**
|
||||
|
||||
- **「繼續」**: 完成當前阶段並生成文件，進入下一阶段
|
||||
- **「修改」**: 在當前阶段內調整和改進內容
|
||||
- **「重做」**: 從头開始當前阶段
|
||||
- **「詳细說明」**: 提供更詳细的說明或選項
|
||||
- **「跳過」**: 跳過當前阶段進入下一個 (不推薦)
|
||||
|
||||
**文件生成時機**
|
||||
|
||||
```text
|
||||
Phase 1 完成 → 「繼續」 → 生成 requirements.md
|
||||
Phase 2 完成 → 「繼續」 → 生成 design.md
|
||||
Phase 3 完成 → 「繼續」 → 生成 tasks.md
|
||||
```
|
||||
|
||||
### 執行示例 (分阶段流程)
|
||||
|
||||
```bash
|
||||
# 使用示例
|
||||
用戶：「創建用戶管理系統的 spec」
|
||||
|
||||
# Phase 1: Requirements Discovery
|
||||
Claude: [開始需求確認和讨論]
|
||||
用戶: [響應・讨論・修改]
|
||||
Claude: 「Requirements Phase 已完成。可以繼續吗？」
|
||||
用戶: 「繼續」
|
||||
→ 生成 requirements.md
|
||||
|
||||
# Phase 2: Design Exploration
|
||||
Claude: [開始設計提案和讨論]
|
||||
用戶: [技術選擇・架構讨論]
|
||||
Claude: 「Design Phase 已完成。可以繼續吗？」
|
||||
用戶: 「繼續」
|
||||
→ 生成 design.md
|
||||
|
||||
# Phase 3: Implementation Planning
|
||||
Claude: [開始實施計劃讨論]
|
||||
用戶: [優先級・風險・工時讨論]
|
||||
Claude: 「Implementation Phase 已完成。可以繼續吗？」
|
||||
用戶: 「繼續」
|
||||
→ 生成 tasks.md
|
||||
|
||||
# 完成
|
||||
Claude: 「spec 驅動開發的準備已完成。可以開始實施。」
|
||||
```
|
||||
|
||||
### 與 /plan 的區別
|
||||
|
||||
| 特徵 | /plan | /spec |
|
||||
| -------- | ---------------- | --------------------------------------------------- |
|
||||
| 對象 | 一般實施計劃 | 功能規格驅動開發 |
|
||||
| 輸出格式 | 單一計劃文檔 | 3 個独立文件 (requirements.md、design.md、tasks.md) |
|
||||
| 需求定義 | 基本需求整理 | 使用 EARS 記法的詳细驗收標準 |
|
||||
| 設計 | 以技術選型為中心 | 基于代碼庫分析 |
|
||||
| 實施 | 一般任務分解 | 考虑依賴關系的序列 |
|
||||
| 質量保證 | 基本測試策略 | 全面質量要求 (測試、無障礙、性能) |
|
||||
| 同步 | 靜態計劃 | 動態 spec 更新 |
|
||||
|
||||
### 推薦用例
|
||||
|
||||
**推薦使用 spec**
|
||||
|
||||
- 新功能開發
|
||||
- 復杂功能改造
|
||||
- API 設計
|
||||
- 數據庫設計
|
||||
- UI/UX 實施
|
||||
|
||||
**推薦使用 plan**
|
||||
|
||||
- 系統整體設計
|
||||
- 基礎設施構建
|
||||
- 重構
|
||||
- 技術選型
|
||||
- 架構變更
|
||||
Reference in New Issue
Block a user