创建GitHub Issue技能
创建全面的、结构良好的GitHub issue，内置代理指令以自主管理PR生命周期。
概述
此技能生成自包含的工作包形式的GitHub issue。每个issue包括：
- 问题/功能规范，带有清晰的范围
- 技术规范，包括类型、架构和API设计
- TDD实现计划，采用测试优先循环
- 接受标准清单
- 代理指令，涵盖完整的PR生命周期（实现→审查→合并）
用法
/project:create-issue
交互流程
步骤 1: 问题类型
询问用户：
这是什么类型的问题？
1. 功能 - 新功能
2. 错误 - 某些功能损坏
3. 重构 - 改进现有代码
步骤 2: 简要描述
问题或功能的简要描述？（1-2句话）
步骤 3: 复杂度评估
估计的复杂度是多少？
1. 简单（< 1天）
2. 中等（2-5天）
3. 复杂（> 1周）
步骤 4: 上下文收集
有任何相关的文件、服务或问题需要引用吗？
（或者说“探索代码库”，我会进行调查）
步骤 5: 生成问题
基于输入，使用下面的适当模板生成完整的issue。
Issue模板
功能模板
## 摘要
[1-2句话描述]
**复杂度**: [简单|中等|复杂]
**预计工作量**: [X天]
---
## 问题
[这解决了什么问题？为什么需要它？]
### 证据
[日志、指标、用户报告或推理]
### 范围
- ✅ 范围内: [包括什么]
- ❌ 范围外: [明确不包括什么]
---
## 架构决策
**决策**: [将采用什么方法]
**理由**: [为什么采用这种方法，为什么不是替代方案]
---
## 技术规范
### 类型/接口
```typescript
// 关键类型定义
```
### Zod架构（如果适用）
```typescript
// 验证架构
```
### API端点（如果适用）
| 方法 | 路径 | 描述 |
| ------ | ---- | ----------- |
### 数据库更改（如果适用）
[架构更改、需要的迁移]
---
## TDD实现计划
### 循环 1: [快乐路径]
```typescript
it("应该[预期行为]", async () => {
// 测试代码
});
```
### 循环 2: [错误处理]
```typescript
it("应该处理[错误案例]", async () => {
// 测试代码
});
```
### 循环 3: [边界案例]
### 循环 4: [集成]
---
## 错误处理
| 场景 | 行为 | 日志记录 |
| -------- | -------- | ------- |
---
## 实现阶段
### 阶段 1: [核心]（高优先级）
- [ ] 任务 1
- [ ] 任务 2
### 阶段 2: [增强]（中等优先级）
- [ ] 任务 3
---
## 要创建/修改的文件
- **新建**: `路径/到/新文件.ts`
- `路径/到/现有文件.ts` - [什么更改]
---
## 接受标准
- [ ] 所有TDD循环已实现并通过测试
- [ ] 零TypeScript错误（`pnpm typecheck`）
- [ ] 零lint警告（`pnpm lint`）
- [ ] 所有测试通过（`pnpm test --run`）
- [ ] **JSDoc文档**添加到所有新/修改的服务
- [ ] **`docs/SERVICE_INVENTORY.md`** 更新（如果新/修改服务）
- [ ] **`scripts/service-registry.json`** 更新（如果新/修改服务）
- [ ] **模拟工厂** 添加/更新于 `src/lib/services/mock-factories.ts`（如果新服务）
- [ ] PR已创建且所有CI检查通过
- [ ] **所有代码审查评论已处理**（见代理指令）
- [ ] 所有审查线程已解决
- [ ] PR已批准并合并
---
## 代理指令
**关键**: 实现此issue时遵循此协议。PR在完成所有步骤之前不是完整的。
### 阶段 0: 研究（在编写任何代码之前）
**先阅读这些文件，避免重复造轮子:**
1. **服务清单** - 检查现有服务是否已满足需求：
```bash
# 阅读服务清单
cat docs/SERVICE_INVENTORY.md
# 或搜索特定功能
grep -i "embedding\|search\|cache" docs/SERVICE_INVENTORY.md
```
2. **服务注册表** - 检查服务元数据和类别：
```bash
cat scripts/service-registry.json | jq '.services[] | select(.name | test("Search|Cache"; "i"))'
```
3. **模拟工厂** - 查看现有模拟以重用模式：
```bash
cat src/lib/services/mock-factories.ts
```
4. **类似服务** - 查找具有类似模式的服务：
```bash
# 查找编排器模式
ls src/lib/services/*-orchestrator*.ts
# 查找持久性模式
ls src/lib/services/*-persistence*.ts
```
**为什么重要**: 重用现有服务和模式节省时间，保持一致性，防止重复代码。
### 阶段 A: 实现
1. 从主分支创建功能分支：`git checkout -b feat/[简短名称]`
2. 按照上述TDD循环执行
3. **添加JSDoc文档**到所有新/修改的服务
4. 运行本地验证：`pnpm lint && pnpm typecheck && pnpm test --run`
5. **更新服务清单**（如果新服务）：
```bash
npx tsx scripts/sync-service-registry.ts --execute
npx tsx scripts/update-service-inventory.ts
```
6. 使用 `/project:create-pr` 创建PR，包含全面描述
### 阶段 B: 代码审查迭代
**等待代码审查后再继续。推送代码后不要标记完成。**
对于每个代码审查迭代：
1. **获取所有评论**（包括琐碎、挑剔和范围外）：
```bash
PR_NUMBER=XXX
OWNER=$(gh repo view --json owner -q .owner.login)
REPO=$(gh repo view --json name -q .name)
gh api "repos/$OWNER/$REPO/pulls/$PR_NUMBER/comments" --paginate
```
2. **按类别处理所有评论**：
| 类型 | 操作 |
| ---------------------- | ---------------------------------------------------- |
| 🔴 关键/重大 | 立即修复 |
| 🟡 中等/轻微 | 合并前修复 |
| 🔵 **琐碎/挑剔** | **也要修复这些！** 不要跳过 |
| 🟣 **范围外** | **彻底调查** - 通常包含最佳见解 |
3. **对于每个评论**：
- **< 1天工作** → 在此PR中实施修复
- **> 1天或架构性** → 创建新的GitHub issue，在响应中链接
- **不同意** → 回复解释技术原因
4. **更改后**：
```bash
pnpm lint && pnpm typecheck && pnpm test --run
git add . && git commit -m "fix: 处理审查反馈" && git push
```
5. **逐个响应每个评论线程**：
```bash
COMMENT_ID=XXX
CURRENT_USER=$(gh api user -q '.login')
gh api "/repos/$OWNER/$REPO/pulls/$PR_NUMBER/comments/$COMMENT_ID/replies" \
-X POST \
-f body="在提交$(git rev-parse --short HEAD)中修复。 [解释]
*(Claude代表@$CURRENT_USER回复)*"
```
6. **等待下一个审查周期** - 不要自己解决线程
7. **重复步骤1-6**直到审查者确认满意
### 阶段 C: 线程解决
仅审查者批准后：
1. 重新获取所有线程以获取当前ID
2. 解决每个线程：
```bash
THREAD_ID="PRRT_xxx"
gh api graphql -f threadId="$THREAD_ID" -f query='
mutation($threadId: ID!) {
resolveReviewThread(input: {threadId: $threadId}) {
thread { id isResolved }
}
}'
```
3. 继续前验证所有线程已解决
### 阶段 D: 合并准备
PR准备好合并仅当所有条件为真：
- [ ] 所有CI检查通过（绿色）
- [ ] **每个**代码审查评论已处理（包括琐碎/范围外）
- [ ] **每个**线程有个别响应
- [ ] 所有线程已解决（审查者批准后）
- [ ] GitHub issue已创建用于任何延迟工作（> 1天）
- [ ] 没有待处理的审查评论等待响应
### 阶段 E: 压缩合并和清理
**重要**: 总是使用压缩合并，从不使用常规合并。
1. **压缩并合并** PR（将所有提交合并为一个干净的提交）：
```bash
# 通过GitHub CLI
gh pr merge $PR_NUMBER --squash --delete-branch
# 或通过GitHub网页界面：
# 点击“压缩并合并”（不是“合并”或“变基并合并”）
```
2. **删除功能分支**（自动完成，带有--delete-branch标志）：
```bash
# 如果分支未自动删除：
git push origin --delete feat/[分支名称]
git branch -d feat/[分支名称]
```
3. **更新本地主分支**：
```bash
git checkout main
git pull origin main
```
### 参考
详见 `.claude/commands/handle-pr-comments.md` 了解详细协议。
---
## 相关问题
- [相关issue链接]
## 参考资料
- [相关文档、规范或PR链接]
错误模板
使用功能模板，进行以下修改：
标题格式: fix: [简要描述]
替换“问题”部分为：
## 错误报告
**优先级**: 🐛 [P0-关键|P1-高|P2-中等|P3-低]
**影响用户**: [影响范围]
**首次报告**: [日期/来源]
### 预期行为
[应该发生什么]
### 实际行为
[实际发生什么]
### 重现步骤
1. 步骤 1
2. 步骤 2
3. 步骤 3
### 根因分析
[如果已知，解释为什么发生]
### 证据
[日志、堆栈跟踪、截图]
替换“TDD实现计划”为：
## 测试案例
### 测试 1: 验证修复报告的问题
```typescript
it("应该[正确行为]当[条件]", async () => {
// 重现错误场景
// 验证现已修复
});
```
### 测试 2: 回归测试
```typescript
it("应该不回归[相关功能]", async () => {
// 确保修复不破坏其他功能
});
```
重构模板
使用功能模板，进行以下修改：
标题格式: refactor: [简要描述]
在“摘要”后添加：
## 背景
[为什么需要此重构？什么触发了它？]
### 正在处理的审查反馈
> [引用触发此工作的审查评论]
- 原始PR: #XXX
- 评论者: @reviewer
添加到“接受标准”：
- [ ] 不破坏公共API
- [ ] 所有现有测试仍通过，无需修改
- [ ] 性能不降低（如果适用）
生成后
生成issue内容后：
-
显示预览给用户
-
询问是否需要修改
-
创建issue，带有适当标签：
# 功能 gh issue create --title "feat: [标题]" --body "[内容]" \ --label "enhancement" --label "complexity:[级别]" # 错误 gh issue create --title "fix: [标题]" --body "[内容]" \ --label "bug" --label "priority:[级别]" # 重构 gh issue create --title "refactor: [标题]" --body "[内容]" \ --label "refactor" --label "complexity:[级别]" -
报告issue编号给用户
关键原则
- 自包含: Issue应包含代理自主工作所需的一切
- TDD优先: 始终在实现前包含测试规范
- 完整生命周期: 代理指令涵盖从实现到合并
- 无捷径: 必须处理所有审查评论，包括琐碎/挑剔
- 范围外=黄金: 标记为范围外的评论通常包含最佳见解
- 迭代直到完成: PR在所有线程解决前不完整