# AI 提示词指南

## 目录

- [测试相关提示词](#测试相关提示词)
- [开发相关提示词](#开发相关提示词)
- [文档相关提示词](#文档相关提示词)
- [数据库相关提示词](#数据库相关提示词)
- [调试相关提示词](#调试相关提示词)
- [提示词最佳实践](#提示词最佳实践)

---

## 测试相关提示词

### 1. 创建完整测试（推荐）⭐

**适用场景**：模块开发完成，完全没有测试

**提示词**：
```
为 [storyboard_board] 创建完整测试，参考 Project 模块的测试结构
```

**示例**：
```
为 Folder 模块创建完整测试，参考 Project 模块的测试结构
```

**AI 会创建**：
- `test_[模块]_repository.py` - Repository 单元测试
- `test_[模块]_service.py` - Service 单元测试
- `test_[模块]_api.py` - API 集成测试

---

### 2. 创建 API 集成测试（快速）

**适用场景**：时间紧张，优先覆盖核心功能

**提示词**：
```
为 [模块名] API 创建集成测试，参考 test_project_api.py
```

**示例**：
```
为 Storyboard API 创建集成测试，参考 test_project_api.py
```

**覆盖率**：70-80% 的核心功能

---

### 3. 创建 Service 单元测试

**适用场景**：已有 API 测试，需要补充业务逻辑测试

**提示词**：
```
为 [模块名] Service 创建单元测试，参考 test_project_service.py
```

**示例**：
```
为 Credit Service 创建单元测试，参考 test_project_service.py
```

**重点测试**：
- 复杂业务逻辑
- 权限检查
- 异常处理
- 事务管理

---

### 4. 创建 Repository 单元测试

**适用场景**：需要测试复杂查询逻辑

**提示词**：
```
为 [模块名] Repository 创建单元测试，参考 test_project_repository.py
```

**示例**：
```
为 Folder Repository 创建单元测试，参考 test_project_repository.py
```

**重点测试**：
- CRUD 操作
- 复杂查询（筛选、分页、排序）
- 数据验证

---

### 5. 补充缺失的测试

**适用场景**：部分测试已存在，需要补充

**提示词**：
```
为 [模块名] 补充测试：

当前状态：
- ✅ 已有：[已有的测试]
- ❌ 缺失：[需要补充的测试]

创建缺失的测试，参考 Project 模块
```

**示例**：
```
为 Storyboard 模块补充测试：

当前状态：
- ✅ 已有：test_storyboard_api.py
- ❌ 缺失：Repository 和 Service 单元测试

创建缺失的测试，参考 Project 模块
```

---

### 6. 创建特定场景的测试

**适用场景**：需要测试特定功能或边界情况

**提示词**：
```
为 [模块名] [功能] 创建测试，覆盖以下场景：
1. [场景 1]
2. [场景 2]
3. [场景 3]

参考 test_[参考模块]_api.py
```

**示例**：
```
为 Project 权限检查创建测试，覆盖以下场景：
1. 所有者可以修改项目
2. 非所有者无法修改项目
3. 未登录用户无法访问项目

参考 test_folder_api.py
```

---

### 7. 分析并补充测试覆盖率

**适用场景**：需要提高测试覆盖率

**提示词**：
```
分析 [模块名] 的测试覆盖率，列出未覆盖的场景，然后补充测试
```

**示例**：
```
分析 Project 模块的测试覆盖率，列出未覆盖的场景，然后补充测试
```

---

## 开发相关提示词

### 1. 创建新模块（完整）

**适用场景**：从零开始创建新功能模块

**提示词**：
```
创建 [模块名] 模块，包含：
1. Model（数据模型）
2. Schema（请求/响应）
3. Repository（数据访问）
4. Service（业务逻辑）
5. API（路由）

参考 Project 模块的结构
```

**示例**：
```
创建 Comment 模块，包含：
1. Model（数据模型）
2. Schema（请求/响应）
3. Repository（数据访问）
4. Service（业务逻辑）
5. API（路由）

参考 Project 模块的结构
```

---

### 2. 创建 API 端点

**适用场景**：为现有模块添加新的 API 端点

**提示词**：
```
为 [模块名] 添加 [功能] API 端点

功能描述：[描述]

参考 [参考模块] 的 API 结构
```

**示例**：
```
为 Project 添加批量删除 API 端点

功能描述：
- 接收项目 ID 列表
- 批量软删除项目
- 返回删除结果

参考 Folder 的 API 结构
```

---

### 3. 重构代码

**适用场景**：优化现有代码结构

**提示词**：
```
重构 [文件路径]，要求：
1. [要求 1]
2. [要求 2]
3. [要求 3]

保持功能不变，遵循项目规范
```

**示例**：
```
重构 app/services/project_service.py，要求：
1. 提取重复的权限检查逻辑
2. 优化数据库查询
3. 添加类型提示

保持功能不变，遵循项目规范
```

---

### 4. 修复 Bug

**适用场景**：修复已知问题

**提示词**：
```
修复 [模块名] 的 Bug：

问题描述：[描述]
期望行为：[描述]
当前行为：[描述]

相关文件：[文件列表]
```

**示例**：
```
修复 Project Service 的 Bug：

问题描述：删除项目时未检查权限
期望行为：只有所有者可以删除项目
当前行为：任何用户都可以删除项目

相关文件：app/services/project_service.py
```

---

### 5. 添加功能

**适用场景**：为现有模块添加新功能

**提示词**：
```
为 [模块名] 添加 [功能名] 功能

需求：
1. [需求 1]
2. [需求 2]
3. [需求 3]

涉及层级：[Model/Repository/Service/API]
```

**示例**：
```
为 Project 添加归档功能

需求：
1. 添加 archived 状态
2. 归档的项目不显示在列表中
3. 可以恢复归档的项目

涉及层级：Model、Repository、Service、API
```

---

## 文档相关提示词

### 1. 创建 RFC（技术提案）

**适用场景**：新功能开发、重大重构

**提示词**：
```
为 [功能名] 创建 RFC 文档

功能描述：[描述]
技术方案：[方案]

参考现有 RFC 的格式
```

**示例**：
```
为 批量导出功能 创建 RFC 文档

功能描述：支持批量导出项目数据为 JSON/CSV 格式
技术方案：使用 Celery 异步任务处理导出

参考现有 RFC 的格式
```

---

### 2. 创建 Changelog

**适用场景**：功能实现完成，记录变更

**提示词**：
```
为 [功能名] 创建 Changelog

变更内容：
1. [变更 1]
2. [变更 2]
3. [变更 3]

参考现有 Changelog 的格式
```

**示例**：
```
为 Project 权限检查 创建 Changelog

变更内容：
1. 添加权限检查中间件
2. 更新 Service 层权限验证逻辑
3. 添加权限相关测试

参考现有 Changelog 的格式
```

---

### 3. 创建 API 文档

**适用场景**：API 开发完成，需要文档

**提示词**：
```
为 [模块名] API 创建文档

包含：
- 端点列表
- 请求/响应示例
- 错误码说明

参考现有 API 文档格式
```

**示例**：
```
为 Project API 创建文档

包含：
- 端点列表
- 请求/响应示例
- 错误码说明

参考现有 API 文档格式
```

---

### 4. 更新文档

**适用场景**：代码变更后更新文档

**提示词**：
```
更新 [文档路径]，同步以下变更：
1. [变更 1]
2. [变更 2]
3. [变更 3]
```

**示例**：
```
更新 docs/server/guides/project-api.md，同步以下变更：
1. 添加批量删除端点
2. 更新权限检查说明
3. 添加新的错误码

保持文档格式一致
```

---

## 数据库相关提示词

### 1. 创建数据库迁移

**适用场景**：修改数据库结构

**提示词**：
```
创建数据库迁移：[变更描述]

变更内容：
1. [变更 1]
2. [变更 2]
3. [变更 3]

遵循项目迁移规范
```

**示例**：
```
创建数据库迁移：为 projects 表添加 archived_at 字段

变更内容：
1. 添加 archived_at TIMESTAMPTZ 字段
2. 添加索引
3. 添加字段注释

遵循项目迁移规范
```

---

### 2. 创建新表

**适用场景**：添加新的数据表

**提示词**：
```
创建 [表名] 表的迁移脚本

字段：
- [字段 1]：[类型] - [说明]
- [字段 2]：[类型] - [说明]

索引：
- [索引 1]
- [索引 2]

参考现有表结构
```

**示例**：
```
创建 comments 表的迁移脚本

字段：
- comment_id：UUID - 主键
- project_id：UUID - 项目 ID
- user_id：UUID - 用户 ID
- content：TEXT - 评论内容
- created_at：TIMESTAMPTZ - 创建时间

索引：
- idx_comments_project_id
- idx_comments_user_id

参考 projects 表结构
```

---

### 3. 修改表结构

**适用场景**：修改现有表

**提示词**：
```
修改 [表名] 表：[变更描述]

变更：
1. [变更 1]
2. [变更 2]

创建迁移脚本（包含 upgrade 和 downgrade）
```

**示例**：
```
修改 projects 表：添加归档功能

变更：
1. 添加 archived_at TIMESTAMPTZ 字段
2. 添加 archived_by UUID 字段
3. 添加索引 idx_projects_archived_at

创建迁移脚本（包含 upgrade 和 downgrade）
```

---

## 调试相关提示词

### 1. 分析错误

**适用场景**：遇到错误需要分析

**提示词**：
```
分析以下错误：

错误信息：
[粘贴错误信息]

相关代码：
[粘贴相关代码]

提供解决方案
```

---

### 2. 性能优化

**适用场景**：代码性能问题

**提示词**：
```
优化 [文件路径] 的性能

问题：[描述性能问题]

分析瓶颈并提供优化方案
```

**示例**：
```
优化 app/repositories/project_repository.py 的性能

问题：获取项目列表时查询速度慢

分析瓶颈并提供优化方案
```

---

### 3. 代码审查

**适用场景**：代码审查

**提示词**：
```
审查以下代码：

[粘贴代码]

检查：
1. 是否遵循项目规范
2. 是否有潜在问题
3. 是否有优化空间
```

---

## 提示词最佳实践

### 1. 明确具体

❌ **不好的提示词**：
```
创建测试
```

✅ **好的提示词**：
```
为 Project API 创建集成测试，参考 test_folder_api.py
```

---

### 2. 提供上下文

❌ **不好的提示词**：
```
修复 Bug
```

✅ **好的提示词**：
```
修复 Project Service 的权限检查 Bug：
- 问题：删除项目时未检查权限
- 期望：只有所有者可以删除
- 文件：app/services/project_service.py
```

---

### 3. 参考现有代码

❌ **不好的提示词**：
```
创建 API
```

✅ **好的提示词**：
```
为 Comment 创建 API，参考 Project API 的结构
```

---

### 4. 分步执行

对于复杂任务，分步执行更可控：

**第一步**：
```
为 Storyboard API 创建集成测试
```

**验证通过后，第二步**：
```
为 Storyboard Service 创建单元测试
```

---

### 5. 使用检查清单

对于完整功能，使用检查清单：

```
为 Comment 模块创建完整功能：

- [ ] Model（数据模型）
- [ ] Schema（请求/响应）
- [ ] Repository（数据访问）
- [ ] Service（业务逻辑）
- [ ] API（路由）
- [ ] 测试（单元 + 集成）
- [ ] 文档（RFC + API 文档）

参考 Project 模块
```

---

## 常见问题

### Q1: 是否需要说明"使用 jointo-tech-stack 规范"？

**A**: 不需要。当你提到 API、测试、数据库等关键词时，`jointo-tech-stack` skill 会自动激活。

---

### Q2: 如何让 AI 生成更符合规范的代码？

**A**: 使用"参考 [现有文件]"，AI 会分析现有代码的模式并复用。

---

### Q3: 提示词太长怎么办？

**A**: 保持简洁，只说关键信息：
- 要做什么（创建测试）
- 针对什么（Project API）
- 参考什么（test_folder_api.py）

---

### Q4: AI 生成的代码不符合规范怎么办？

**A**: 不要重新说明规范，而是具体指出问题：
```
修改测试：
1. 使用 test_user_token 而非 test_auth
2. 添加 @pytest.mark.integration 标记
3. 响应格式改为 response.json()["data"]
```

---

## 相关文档

- [AI 提示词快速参考](./ai-prompts-quick-reference.md) - 常用提示词速查表
- [测试规范](../../server/tests/README.md) - 测试相关规范
- [后端架构](./backend-architecture.md) - 后端架构规范
- [Jointo 技术栈](../../.claude/skills/jointo-tech-stack/SKILL.md) - 完整技术栈规范

---

**最后更新**: 2026-02-04  
**维护者**: Jointo 开发团队