kiro-spec-engine 1.2.3 → 1.4.0

package/docs/quick-start-with-ai-tools.md

@@ -0,0 +1,374 @@
+# 快速入门：配合 AI 工具使用 kse
+
+> 5分钟学会如何用 kse 配合 Claude、Cursor、Copilot 等 AI 工具
+
+---
+
+## ⚠️ 重要：kse 的定位
+
+**kse 不是独立开发工具，而是 AI 工具的增强器**
+
+```
+你的工作界面 = AI 工具（Codex/Claude/Cursor）
+kse 的角色 = 后台管理 Spec，为 AI 提供结构化上下文
+```
+
+**简单理解**：
+- ❌ kse 不是用来写代码的
+- ✅ kse 是用来**组织项目信息**，让 AI 更好地帮你写代码
+- ✅ 你主要在 AI 工具中工作，kse 在后台提供支持
+
+**三种使用模式**：
+1. **AI 主动调用 kse**（Windsurf/Cline）- 最佳，完全自动 ⭐
+2. **手动导出上下文**（Claude/ChatGPT）- 当前方式
+3. **Watch Mode 自动化**（所有工具）- 进阶用法
+
+**详细说明**：查看 [集成哲学文档](./integration-philosophy.md)
+
+---
+
+## 核心理念
+
+**kse 是什么？**
+- 一个 CLI 工具，帮你管理项目的 Spec（需求、设计、任务）
+- 生成结构化的上下文，让 AI 工具更好地理解你的项目
+
+**为什么需要 kse？**
+- AI 工具需要清晰的上下文才能生成高质量代码
+- kse 帮你组织和导出这些上下文
+- 让 AI 按照你的设计和规范工作
+
+---
+
+## 工作流程图
+
+```
+┌─────────────┐
+│  1. 用 kse  │
+│  创建 Spec  │
+└──────┬──────┘
+       │
+       ▼
+┌─────────────┐
+│  2. 导出    │
+│  上下文     │
+└──────┬──────┘
+       │
+       ▼
+┌─────────────┐
+│  3. 复制到  │
+│  AI 工具    │
+└──────┬──────┘
+       │
+       ▼
+┌─────────────┐
+│  4. AI 帮你 │
+│  写代码     │
+└──────┬──────┘
+       │
+       ▼
+┌─────────────┐
+│  5. 更新    │
+│  任务状态   │
+└─────────────┘
+```
+
+---
+
+## 5分钟快速开始
+
+### 步骤 1：安装 kse
+
+```bash
+npm install -g kiro-spec-engine
+```
+
+### 步骤 2：初始化项目
+
+```bash
+cd your-project
+kse adopt
+```
+
+这会在项目中创建 `.kiro/` 目录。
+
+### 步骤 3：创建你的第一个 Spec
+
+```bash
+kse create-spec 01-00-user-login
+```
+
+然后编辑生成的文件：
+- `.kiro/specs/01-00-user-login/requirements.md` - 写需求
+- `.kiro/specs/01-00-user-login/design.md` - 写设计
+- `.kiro/specs/01-00-user-login/tasks.md` - 列任务
+
+### 步骤 4：导出上下文
+
+```bash
+kse context export 01-00-user-login
+```
+
+这会生成：`.kiro/specs/01-00-user-login/context-export.md`
+
+### 步骤 5：使用 AI 工具
+
+#### 方式 A：Claude Code / ChatGPT
+
+1. 打开生成的 `context-export.md`
+2. 复制全部内容
+3. 粘贴到 Claude/ChatGPT 对话框
+4. 说："请帮我实现任务 1.1"
+
+#### 方式 B：Cursor
+
+1. 生成任务提示：
+   ```bash
+   kse prompt generate 01-00-user-login 1.1
+   ```
+
+2. 打开 Cursor Composer (Cmd+K)
+3. 粘贴生成的提示
+4. Cursor 会根据上下文生成代码
+
+#### 方式 C：GitHub Copilot
+
+1. 在代码文件中添加注释：
+   ```javascript
+   // Task 1.1: Implement user login
+   // See: .kiro/specs/01-00-user-login/design.md
+   ```
+
+2. Copilot 会根据 Spec 文件生成代码
+
+### 步骤 6：更新任务状态
+
+完成任务后，编辑 `tasks.md`：
+
+```markdown
+- [x] 1.1 实现用户登录功能  ← 改成 [x] 表示完成
+- [ ] 1.2 添加密码加密
+```
+
+---
+
+## 详细示例：用 Claude Code 实现登录功能
+
+### 1. 创建 Spec
+
+```bash
+kse create-spec 01-00-user-login
+```
+
+### 2. 编写需求（requirements.md）
+
+```markdown
+# 用户登录功能
+
+## 1. 功能需求
+
+### 1.1 用户可以用邮箱和密码登录
+- 输入：邮箱、密码
+- 输出：登录成功返回 token，失败返回错误信息
+- 验证：邮箱格式、密码长度 >= 6
+```
+
+### 3. 编写设计（design.md）
+
+```markdown
+# 设计方案
+
+## 1. API 设计
+
+### 1.1 登录接口
+- 路径：POST /api/auth/login
+- 请求体：{ email: string, password: string }
+- 响应：{ token: string } 或 { error: string }
+
+## 2. 实现方案
+
+### 2.1 AuthController
+- validateEmail() - 验证邮箱格式
+- validatePassword() - 验证密码长度
+- login() - 处理登录逻辑
+```
+
+### 4. 列出任务（tasks.md）
+
+```markdown
+- [ ] 1.1 实现 AuthController 类
+- [ ] 1.2 实现邮箱验证
+- [ ] 1.3 实现密码验证
+- [ ] 1.4 实现登录逻辑
+- [ ] 1.5 编写单元测试
+```
+
+### 5. 导出上下文
+
+```bash
+kse context export 01-00-user-login
+```
+
+### 6. 在 Claude Code 中使用
+
+**对话示例**：
+
+```
+你：[粘贴 context-export.md 的全部内容]
+
+你：请帮我实现任务 1.1 "实现 AuthController 类"，
+    按照设计文档中的方案，用 TypeScript 实现。
+
+Claude：好的，我会根据设计文档实现 AuthController 类...
+[生成代码]
+
+你：很好！现在请为这个类编写单元测试。
+
+Claude：[生成测试代码]
+
+你：完美！请帮我更新 tasks.md，标记任务 1.1 为完成。
+
+[你手动更新 tasks.md：- [x] 1.1 实现 AuthController 类]
+```
+
+---
+
+## 不同 AI 工具的最佳实践
+
+### Claude Code / ChatGPT
+✅ **优势**：大上下文窗口，可以一次加载完整 Spec  
+📝 **用法**：复制 `context-export.md` 全部内容  
+💡 **技巧**：一次对话可以完成多个任务
+
+### Cursor
+✅ **优势**：IDE 集成，可以直接修改文件  
+📝 **用法**：用 `kse prompt generate` 生成任务提示  
+💡 **技巧**：使用 Composer 模式，让 Cursor 直接编辑文件
+
+### GitHub Copilot
+✅ **优势**：实时代码补全  
+📝 **用法**：在代码注释中引用 Spec 文件  
+💡 **技巧**：写详细的注释，Copilot 会根据 Spec 生成代码
+
+### Windsurf / Cline
+✅ **优势**：可以执行命令和修改文件  
+📝 **用法**：让 AI 直接运行 `kse` 命令  
+💡 **技巧**：AI 可以自动导出上下文和更新任务状态
+
+---
+
+## 常见问题
+
+### Q: 每次都要复制粘贴上下文吗？
+
+**A**: 取决于 AI 工具：
+- **Claude/ChatGPT**：是的，每次新对话需要重新加载
+- **Cursor**：可以在项目中持续使用，Cursor 会记住上下文
+- **Copilot**：不需要，它会自动读取项目文件
+
+### Q: 上下文太大怎么办？
+
+**A**: 使用任务级别的提示：
+```bash
+# 只导出特定任务的上下文
+kse prompt generate 01-00-user-login 1.1
+```
+
+### Q: AI 生成的代码不符合设计怎么办？
+
+**A**: 
+1. 检查 `design.md` 是否写得够详细
+2. 在提示中明确说："严格按照设计文档实现"
+3. 提供代码示例在设计文档中
+
+### Q: 如何让 AI 遵循项目规范？
+
+**A**: 使用 Steering Rules：
+```bash
+# 导出时包含规范
+kse context export 01-00-user-login --steering --steering-files=CORE_PRINCIPLES.md
+```
+
+### Q: 可以自动更新任务状态吗？
+
+**A**: 
+- **Kiro IDE**：支持自动更新
+- **其他工具**：需要手动更新 `tasks.md`
+- **未来**：计划支持更多工具的自动更新
+
+---
+
+## 进阶技巧
+
+### 1. 使用 Steering Rules 控制 AI 行为
+
+创建 `.kiro/steering/CODING_STANDARDS.md`：
+
+```markdown
+# 编码规范
+
+- 使用 TypeScript
+- 所有函数必须有 JSDoc 注释
+- 使用 async/await 而不是 Promise.then
+- 错误处理使用 try-catch
+```
+
+导出时包含：
+```bash
+kse context export 01-00-user-login --steering
+```
+
+### 2. 为不同工具生成不同格式的提示
+
+```bash
+# 为 Claude 生成
+kse prompt generate 01-00-user-login 1.1 --tool=claude-code
+
+# 为 Cursor 生成
+kse prompt generate 01-00-user-login 1.1 --tool=cursor
+
+# 通用格式
+kse prompt generate 01-00-user-login 1.1
+```
+
+### 3. 批量导出多个任务
+
+```bash
+# 导出整个 Spec
+kse context export 01-00-user-login
+
+# 然后在 AI 工具中说：
+# "请按顺序实现任务 1.1 到 1.5"
+```
+
+---
+
+## 总结
+
+**kse 的价值**：
+1. ✅ 结构化管理项目需求和设计
+2. ✅ 生成 AI 友好的上下文
+3. ✅ 让 AI 按照你的规范工作
+4. ✅ 跟踪任务进度
+
+**配合 AI 工具的流程**：
+1. 用 kse 写 Spec（需求、设计、任务）
+2. 导出上下文
+3. 复制给 AI 工具
+4. AI 帮你写代码
+5. 更新任务状态
+
+**下一步**：
+- 查看 [完整跨工具指南](./cross-tool-guide.md)
+- 查看 [命令参考](./command-reference.md)
+- 查看 [手动工作流指南](./manual-workflows-guide.md)
+
+---
+
+**开始使用！** 🚀
+
+```bash
+npm install -g kiro-spec-engine
+kse adopt
+kse create-spec 01-00-my-feature
+```