ljwx-children/docs/best-practices/github-integration.md

GitHub 集成最佳实践

本指南介绍如何充分利用 GitHub 的项目管理功能，结合 Claude Code 实现流程化、工程化的开发。

🎯 GitHub Projects 配置

创建项目看板

# 使用 GitHub CLI 创建项目
gh project create --owner @me --title "Gold Template Development"

看板布局

┌─────────┬──────┬─────────────┬────────┬─────────┬──────┐
│ Backlog │ Todo │ In Progress │ Review │ Testing │ Done │
└─────────┴──────┴─────────────┴────────┴─────────┴──────┘

状态说明：

• Backlog: 待规划的任务
• Todo: 已规划，待开始
• In Progress: 正在开发中（限制 WIP）
• Review: 等待代码审查
• Testing: 测试验证中
• Done: 已完成

自定义字段

在 GitHub Projects 中添加以下自定义字段：

字段名	类型	选项/说明
Priority	单选	P0(紧急), P1(高), P2(中), P3(低)
Complexity	数字	1-5 星评级
Component	多选	Backend, Frontend, Database, DevOps, Docs
Claude Assisted	单选	Yes, No, Partial
Sprint	文本	Sprint-01, Sprint-02...
Estimate	数字	工作量估算（小时）
Assignee	人员	负责人

自动化规则

在 GitHub Projects 中配置自动化：

# .github/workflows/project-automation.yml
name: Project Automation

on:
  issues:
    types: [opened, closed, labeled]
  pull_request:
    types: [opened, closed, ready_for_review]

jobs:
  auto-add-to-project:
    runs-on: ubuntu-latest
    steps:
      - name: Add to project
        uses: actions/[email protected]
        with:
          project-url: https://github.com/users/YOUR_USERNAME/projects/1
          github-token: ${{ secrets.PAT_TOKEN }}

      - name: Set status
        run: |
          # Issue opened -> Todo
          # PR opened -> Review
          # Closed -> Done

📋 Issue 管理

Issue 工作流

graph LR
    A[用户创建 Issue] --> B{选择模板}
    B -->|Bug| C[Bug Report]
    B -->|Feature| D[Feature Request]
    B -->|Claude Task| E[Claude Assisted Task]

    C --> F[标签: bug]
    D --> F1[标签: enhancement]
    E --> F2[标签: claude-assisted]

    F --> G[分配优先级]
    F1 --> G
    F2 --> G

    G --> H[添加到 Project]
    H --> I[开始开发]

Issue 标签系统

类型标签：

• bug - Bug 报告
• enhancement - 新功能或改进
• documentation - 文档相关
• claude-assisted - Claude 辅助开发
• good-first-issue - 适合新手

优先级标签：

• priority-p0 - 紧急
• priority-p1 - 高优先级
• priority-p2 - 中优先级
• priority-p3 - 低优先级

状态标签：

• needs-planning - 需要规划
• in-progress - 开发中
• needs-review - 需要审查
• blocked - 被阻塞

组件标签：

• backend - 后端相关
• frontend - 前端相关
• database - 数据库相关
• devops - DevOps 相关

Issue 生命周期

# 1. 创建 Issue
gh issue create --template claude-assisted-task.md \
  --title "Feature: Add export functionality" \
  --label "enhancement,claude-assisted,priority-p1"

# 2. 分配到项目
gh issue edit 123 --add-project "Gold Template Development"

# 3. 开始开发
git checkout -b feature/export-123

# 4. 关联 Issue
git commit -m "feat: add export API endpoint

Implements the export functionality requested in #123

- Add export API endpoint
- Support multiple formats (CSV, JSON, Excel)
- Add comprehensive tests

Related: #123"

# 5. 创建 PR
gh pr create --fill --label "enhancement"

# 6. PR 合并后自动关闭 Issue
# 使用关键词: Closes #123, Fixes #123, Resolves #123

🔄 Pull Request 流程

PR 模板使用

# 创建 PR 时自动使用模板
gh pr create --template default.md

PR 审查清单

自动化检查（GitHub Actions）：

• CI 测试通过
• 代码格式检查通过
• 类型检查通过
• 安全扫描通过
• 测试覆盖率达标

人工审查要点：

• 代码逻辑正确
• 遵循项目规范
• 测试充分
• 文档完整
• 无安全隐患

PR 审查流程

graph TD
    A[创建 PR] --> B[自动化检查]
    B --> C{检查通过?}
    C -->|否| D[修复问题]
    D --> B
    C -->|是| E[请求审查]
    E --> F[人工审查]
    F --> G{审查通过?}
    G -->|否| H[修改代码]
    H --> B
    G -->|是| I[合并 PR]
    I --> J[自动部署]

使用 Claude 辅助 Code Review

"请帮我审查这个 PR: #123

重点检查：
1. 代码质量和规范
2. 潜在的 bug
3. 性能问题
4. 安全隐患
5. 测试覆盖

PR 地址：https://github.com/user/repo/pull/123"

📊 项目可视化

GitHub Insights

使用 GitHub Insights 查看项目指标：

1. 代码频率 - 提交活跃度
2. 贡献者 - 团队贡献分布
3. 流量 - 项目访问量
4. 依赖关系 - 依赖项安全状态

自定义仪表盘

在 README 中添加项目徽章：

# Project Name

![CI](https://github.com/user/repo/actions/workflows/ci.yml/badge.svg)
![Coverage](https://codecov.io/gh/user/repo/branch/main/graph/badge.svg)
![License](https://img.shields.io/badge/license-MIT-blue.svg)
![Claude](https://img.shields.io/badge/Claude-Assisted-purple.svg)

## Project Stats

![Contributors](https://img.shields.io/github/contributors/user/repo)
![Stars](https://img.shields.io/github/stars/user/repo)
![Forks](https://img.shields.io/github/forks/user/repo)
![Issues](https://img.shields.io/github/issues/user/repo)
![PRs](https://img.shields.io/github/issues-pr/user/repo)

项目统计页面

创建一个统计页面展示项目健康度：

# scripts/generate_stats.py
import json
from github import Github

def generate_project_stats():
    """生成项目统计信息"""
    g = Github("YOUR_TOKEN")
    repo = g.get_repo("user/repo")

    stats = {
        "total_issues": repo.get_issues(state='all').totalCount,
        "open_issues": repo.open_issues_count,
        "closed_issues": repo.get_issues(state='closed').totalCount,
        "total_prs": repo.get_pulls(state='all').totalCount,
        "merged_prs": len([pr for pr in repo.get_pulls(state='closed') if pr.merged]),
        "contributors": repo.get_contributors().totalCount,
        "stars": repo.stargazers_count,
        "forks": repo.forks_count,
    }

    return stats

🤖 Claude + GitHub 协同

自动创建 Issue

"根据这个 bug 报告，帮我创建一个详细的 GitHub Issue：

Bug 描述：
[描述]

包括：
1. 问题描述
2. 重现步骤
3. 期望行为
4. 实际行为
5. 环境信息
6. 可能的解决方案

然后使用以下命令创建：
gh issue create --title '...' --body '...'"

自动化任务分解

当 Issue 被标记为 needs-planning 时：

1. GitHub Action 触发
2. 使用 Claude API 分析 Issue
3. 自动生成子任务清单
4. 在 Issue 中添加评论

# .github/workflows/task-breakdown.yml
name: Auto Task Breakdown

on:
  issues:
    types: [labeled]

jobs:
  breakdown:
    if: github.event.label.name == 'needs-planning'
    runs-on: ubuntu-latest
    steps:
      - name: Generate breakdown
        uses: actions/github-script@v7
        with:
          script: |
            // 调用 Claude API 生成任务分解
            // 然后添加评论到 Issue

PR 自动分析

# .github/workflows/pr-analysis.yml
name: PR Analysis

on:
  pull_request:
    types: [opened, synchronize]

jobs:
  analyze:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Get changed files
        id: changes
        run: |
          echo "files=$(git diff --name-only origin/main...HEAD | jq -R -s -c 'split("\n")[:-1]')" >> $GITHUB_OUTPUT

      - name: Comment analysis
        uses: actions/github-script@v7
        with:
          script: |
            const files = ${{ steps.changes.outputs.files }};
            const comment = `## 🤖 PR Analysis

            **Changed Files:** ${files.length}

            **Suggestions:**
            - Consider adding tests for new functionality
            - Update documentation if needed
            - Verify security implications

            *Use Claude Code for detailed review*`;

            github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: comment
            });

📈 度量和改进

关键指标

跟踪以下指标来衡量开发效率：

指标	说明	目标
Lead Time	Issue 创建到关闭的时间	<7天
Cycle Time	开始开发到合并的时间	<3天
PR Review Time	PR 创建到合并的时间	<24小时
Deployment Frequency	部署频率	每天多次
Change Failure Rate	变更失败率	<5%
MTTR	平均修复时间	<4小时

使用 Claude 分析项目健康度

"请分析我们项目的 GitHub 数据：

过去一个月：
- 创建了 45 个 Issue
- 关闭了 38 个 Issue
- 合并了 52 个 PR
- 平均 PR review 时间：18 小时
- 平均 Issue 解决时间：5.2 天

请帮我：
1. 评估项目健康度
2. 识别瓶颈
3. 提供改进建议"

💡 最佳实践总结

✅ 应该做的

1. 使用 Issue 模板 - 确保信息完整
2. 关联 Issue 和 PR - 保持可追溯性
3. 及时审查 PR - 加快开发周期
4. 自动化一切 - 减少手动操作
5. 定期回顾 - 持续改进流程

❌ 不应该做的

1. 不要跳过 Code Review
2. 不要直接提交到主分支
3. 不要忽视自动化检查失败
4. 不要创建缺少描述的 Issue
5. 不要合并未通过测试的 PR

🎓 延伸资源

• GitHub Projects 文档
• GitHub Actions 文档
• GitHub CLI 文档
• Git 工作流最佳实践

---

维护者： 开发团队 最后更新： 2024-12-29 版本： 1.0.0