implement-issue

实现 Issue 技能

从头到尾实现 GitHub Issue：设置分支、分析代码库并完成实现。

前置条件检查（必须先验证）

继续之前，请验证：

# 1. Check if in a git repository
git rev-parse --is-inside-work-tree

# 2. Check if gh CLI is available and authenticated
gh auth status

# 3. Check for uncommitted changes (warn user if any)
git status --porcelain

如果检查未通过，请停止并告知用户：

• 不在 git 仓库中 → "此技能需要 git 仓库。请切换到 git 项目目录。"
• gh 未通过身份验证 → "请先运行 gh auth login。"
• 存在未提交的更改 → "你有未提交的更改。请先提交或暂存这些更改。"

输入

用户提供以下格式之一的 Issue 引用：

• 完整 URL：https://github.com/owner/repo/issues/123
• 简写（在仓库中）：#123 或 123

工作流

步骤 1：提取 Issue 信息

# Get comprehensive issue metadata
gh issue view <ISSUE_NUMBER_OR_URL> --json number,title,body,state,author,labels,milestone,assignees,comments,createdAt,updatedAt

# Get repository info for branch naming
gh repo view --json owner,name,defaultBranchRef

解析 Issue，以了解：

• 标题：需要完成工作的简要概述
• 正文：详细要求、验收标准和上下文
• 标签：工作类型（bug、feature、enhancement 等）
• 评论：补充上下文、讨论和说明

步骤 2：同步到最新的 Main/Master 分支

# Detect default branch (main or master)
DEFAULT_BRANCH=$(gh repo view --json defaultBranchRef -q '.defaultBranchRef.name')

# Fetch latest changes
git fetch origin $DEFAULT_BRANCH

# Checkout and update default branch
git checkout $DEFAULT_BRANCH
git pull origin $DEFAULT_BRANCH

步骤 3：创建 Issue 分支

根据 Issue 生成分支名称：

分支命名约定：<type>/<issue-number>-<short-description>

Issue 类型（根据标签）	分支前缀
bug、bugfix	fix/
feature、enhancement	feat/
docs、documentation	docs/
refactor	refactor/
test	test/
chore	chore/
（默认）	issue/

示例：

• Issue #42「添加用户身份验证」→ feat/42-add-user-authentication
• Issue #15「修复登录重定向错误」→ fix/15-fix-login-redirect
• Issue #99「更新 README」→ docs/99-update-readme

# Create and checkout new branch
git checkout -b <BRANCH_NAME>

步骤 4：深入分析代码库

开始实现之前，彻底了解代码库：

4.1 分析项目结构

# Get project structure overview
ls -la
find . -type f -name "*.json" -path "*/package.json" -o -name "*.toml" -path "*/Cargo.toml" -o -name "*.go" -path "*/go.mod" 2>/dev/null | head -20

# Check for configuration files
ls -la *.json *.yaml *.yml *.toml .* 2>/dev/null | head -20

4.2 了解现有模式

使用探索 Agent 了解：

1. 架构：代码库如何组织？有哪些主要模块？
2. 模式：使用了哪些编码模式？（错误处理、日志记录、测试）
3. 相关代码：哪些现有代码与此 Issue 相关？
4. 依赖项：使用了哪些库/框架？

# Fire multiple explore agents in parallel
background_task(agent="explore", prompt="Find the main entry points and understand the overall architecture of this codebase")
background_task(agent="explore", prompt="Find code related to [ISSUE_TOPIC] and understand existing patterns")
background_task(agent="explore", prompt="Find test patterns and testing conventions in this codebase")

4.3 确定实现位置

根据 Issue 的要求，确定：

• 需要修改哪些文件
• 需要创建哪些新文件
• 需要添加/更新哪些测试
• 需要更新哪些文档

步骤 5：制定实现计划

编码之前，创建详细的待办事项列表：

todowrite([
  { id: "1", content: "Understand issue requirements fully", status: "completed", priority: "high" },
  { id: "2", content: "Analyze related codebase areas", status: "completed", priority: "high" },
  { id: "3", content: "[Specific implementation task 1]", status: "pending", priority: "high" },
  { id: "4", content: "[Specific implementation task 2]", status: "pending", priority: "medium" },
  { id: "5", content: "Add/update tests", status: "pending", priority: "high" },
  { id: "6", content: "Run tests and fix issues", status: "pending", priority: "high" },
  { id: "7", content: "Update documentation if needed", status: "pending", priority: "low" },
  { id: "8", content: "Final verification", status: "pending", priority: "high" }
])

步骤 6：实现解决方案

遵循以下原则：

1. 匹配现有模式：遵循代码库中既定的规范
2. 渐进式更改：进行小而聚焦的更改
3. 边做边测：继续之前，验证每项更改均正常工作
4. 记录复杂逻辑：必要时添加注释

对于每项实现任务：

1. 将待办事项标记为 in_progress
2. 进行更改
3. 对更改的文件运行 lsp_diagnostics
4. 将待办事项标记为 completed

步骤 7：测试

# Run project tests (detect test command from package.json, Makefile, etc.)
# Common patterns:
npm test
yarn test
go test ./...
cargo test
pytest
make test

确保：

• 所有现有测试均通过
• 为新功能添加了新测试
• 覆盖了边界情况

步骤 8：最终验证

# Check for any linting issues
# (detect lint command from project config)

# Verify build succeeds
# (detect build command from project config)

# Review all changes
git diff --stat
git diff

步骤 9：提交更改

# Stage all changes
git add -A

# Create commit with conventional commit message
# Format: <type>(scope): <description>
#
# Reference the issue number in the commit body
git commit -s -m "<type>: <short description>

<detailed description of changes>

Closes #<ISSUE_NUMBER>"

提交信息示例：

• feat: add user authentication system
• fix: resolve login redirect loop
• docs: update API documentation

输出格式

完成实现后，请提供：

---

实现摘要

Issue：#[NUMBER] - [TITLE] 分支：[BRANCH_NAME] 状态：[已实现 / 部分实现 / 受阻]

所做更改

文件	更改类型	描述
path/to/file.ts	已修改	[更改内容]
path/to/new-file.ts	已添加	[添加内容]

实现详情

[用 2-5 句话说明实现了什么，以及如何解决 Issue]

新增/更新的测试

• [测试 1 描述]
• [测试 2 描述]

验证结果

检查项	状态	备注
构建	通过/失败	[备注]
测试	通过/失败	[备注]
Lint	通过/失败	[备注]
诊断	正常/存在问题	[备注]

---

后续步骤

向用户建议：

1. 审查更改：git diff origin/<DEFAULT_BRANCH>...HEAD
2. 推送分支：git push -u origin <BRANCH_NAME>
3. 创建 PR：gh pr create --title "<PR_TITLE>" --body "<PR_BODY>"

或者在用户请求时，主动创建 PR。

---

重要说明

1. 先理解，再实施：花足够的时间理解问题和代码库
2. 询问以澄清：如果问题的要求不明确，请在实施前询问
3. 尽量减少更改：只更改实现该问题所必需的内容
4. 遵循约定：与现有代码库的风格和模式保持一致
5. 彻底测试：确保更改不会破坏现有功能
6. 编写文档：如果更改会影响公共 API 或面向用户的功能，请更新文档

错误处理

情况	操作
未找到问题	验证问题编号/URL，检查仓库访问权限
分支已存在	询问用户：使用现有分支，还是添加后缀创建新分支？
合并冲突	向用户报告，并建议解决步骤
测试失败	调查问题是原本就存在，还是由更改导致
要求不明确	在继续之前询问用户以澄清
实施受阻	记录阻碍因素，并建议替代方案