Claude Code Git全栈：从init到PR自动化实战

flowchart LR
    A[代码变更] --> B[Claude Code 分析 diff]
    B --> C[智能生成 commit message]
    C --> D[自动暂存相关文件]
    D --> E[语义化提交]
    E --> F[推送并创建 PR]
    F --> G[@claude Code Review]
    style A fill:#e1f5fe
    style G fill:#c8e6c9

# 检查 Claude Code 版本
claude --version

# 检查 Git 版本
git --version

# 检查 GitHub CLI
gh --version

# 确认 GitHub 已认证
gh auth status

✔ Logged in to github.com as your-username (oauth_token)
Git operations will use HTTPS authentication

gh auth login
# 选择 GitHub.com -> HTTPS -> 浏览器认证

# 确认 npm 全局路径
npm config get prefix
# 将其加入 PATH
export PATH="$(npm config get prefix)/bin:$PATH"

# 创建项目目录
mkdir claude-git-demo && cd claude-git-demo

# 初始化 Git 仓库
git init

# 创建基础项目结构
mkdir -p src tests
cat > package.json << 'EOF'
{
  "name": "claude-git-demo",
  "version": "0.1.0",
  "description": "A demo project for Claude Code Git workflow",
  "main": "src/index.ts",
  "scripts": {
    "build": "tsc",
    "test": "jest",
    "lint": "eslint src/"
  }
}
EOF

# 创建 .gitignore
cat > .gitignore << 'EOF'
node_modules/
dist/
.env
*.log
.DS_Store
EOF

claude

# Project: claude-git-demo

## Git Conventions

### Commit Messages
- Use Conventional Commits format: `type(scope): description`
- Types: feat, fix, docs, style, refactor, test, chore
- Always include scope when applicable
- Keep description under 72 characters
- Use imperative mood ("add feature" not "added feature")

### Branch Naming
- Feature: `feat/description` (e.g., feat/add-logger)
- Bugfix: `fix/description` (e.g., fix/null-pointer)
- Release: `release/vX.Y.Z`
- Always branch from main, never commit directly to main

### Pull Requests
- Title follows same convention as commit messages
- Description must include: Summary, Changes, Test Plan
- Always request review before merging
- Squash merge to main

### General Rules
- Never force push to main
- Always run tests before committing
- Never commit .env or secrets

> 请帮我创建初始提交，包含目前所有项目文件

# Claude Code 会自动执行：

# 1. 查看 git status
git status

# 2. 选择性暂存文件（排除不应提交的文件）
git add package.json .gitignore CLAUDE.md

# 3. 生成语义化提交信息
git commit -m "chore(init): initialize project with base configuration

- Add package.json with TypeScript project setup
- Add .gitignore for node_modules and build artifacts
- Add CLAUDE.md with Git workflow conventions

Co-Authored-By: Claude <[email protected]>"

> 创建一个新分支 feat/add-logger，然后实现一个简单的日志工具模块

# 1. 基于当前分支创建功能分支
git checkout -b feat/add-logger

# 2. 创建日志模块 src/logger.ts

// src/logger.ts

export enum LogLevel {
  DEBUG = 'DEBUG',
  INFO = 'INFO',
  WARN = 'WARN',
  ERROR = 'ERROR',
}

export class Logger {
  constructor(private context: string = 'App') {}

  private formatMessage(level: LogLevel, message: string): string {
    const timestamp = new Date().toISOString();
    return `[${timestamp}] [${level}] [${this.context}] ${message}`;
  }

  debug(message: string): void {
    console.debug(this.formatMessage(LogLevel.DEBUG, message));
  }

  info(message: string): void {
    console.info(this.formatMessage(LogLevel.INFO, message));
  }

  warn(message: string): void {
    console.warn(this.formatMessage(LogLevel.WARN, message));
  }

  error(message: string, error?: Error): void {
    console.error(this.formatMessage(LogLevel.ERROR, message));
    if (error?.stack) {
      console.error(error.stack);
    }
  }
}

export function createLogger(context: string): Logger {
  return new Logger(context);
}

// src/index.ts
import { createLogger } from './logger';

const logger = createLogger('Main');

logger.info('Application started');
logger.debug('Debug mode enabled');
logger.warn('This is a warning');
logger.error('Something went wrong', new Error('test error'));

> 提交这个功能并推送到远程

# 暂存并提交
git add src/logger.ts src/index.ts
git commit -m "feat(logger): add structured logging module with level support

- Implement Logger class with DEBUG/INFO/WARN/ERROR levels
- Add timestamp and context formatting
- Export factory function createLogger()
- Add usage example in index.ts

Co-Authored-By: Claude <[email protected]>"

# 推送并设置上游分支
git push -u origin feat/add-logger

> 为当前分支创建一个 Pull Request

# Claude Code 使用 gh CLI 创建 PR
gh pr create --title "feat(logger): add structured logging module" --body "$(cat <<'EOF'
## Summary

Adds a structured logging utility with multi-level support (DEBUG, INFO, WARN, ERROR).

## Changes

- `src/logger.ts`: Logger class with timestamp formatting and context tagging
- `src/index.ts`: Usage example demonstrating all log levels
- Factory pattern via `createLogger()` for easy instantiation

## Test Plan

- [ ] Verify log output format: `[timestamp] [LEVEL] [context] message`
- [ ] Test all four log levels produce correct output
- [ ] Confirm error stack traces are printed when Error object is provided
- [ ] Run `npm run build` to verify TypeScript compilation

🤖 Generated with [Claude Code](https://claude.com/claude-code)
EOF
)"

## Git Conventions (续)

### PR Description Template
Every PR description MUST follow this structure:
1. **Summary**: 1-3 sentence overview
2. **Changes**: Bulleted list of file changes with descriptions
3. **Test Plan**: Checkbox list of verification steps
4. **Screenshots**: If UI changes are involved

### PR Labels
- `feature` for new functionality
- `bugfix` for bug fixes
- `breaking` for breaking changes
- `dependencies` for dependency updates

name: Claude Code Review

on:
  issue_comment:
    types: [created]

jobs:
  claude-review:
    if: |
      github.event.issue.pull_request &&
      contains(github.event.comment.body, '@claude')
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
      issues: write
    steps:
      - uses: actions/checkout@v4

      - name: Claude Code Review
        uses: anthropics/claude-code-action@v1
        with:
          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
          prompt: |
            Review this pull request. Focus on:
            1. Code correctness and potential bugs
            2. Security vulnerabilities
            3. Performance implications
            4. Adherence to project conventions in CLAUDE.md

sequenceDiagram
    participant Dev as 开发者
    participant GH as GitHub
    participant CC as Claude Code Action
    participant PR as Pull Request

    Dev->>GH: 创建 PR
    GH->>PR: 显示 PR 详情

    Dev->>PR: 评论 "@claude review this"
    PR->>GH: 触发 issue_comment 事件
    GH->>CC: 启动 Claude Code Action

    CC->>GH: 获取 PR diff
    CC->>CC: 分析代码变更
    CC->>PR: 发布审查评论

    Dev->>PR: 回复 "@claude fix the issue"
    PR->>GH: 触发新事件
    GH->>CC: Claude 自动修复
    CC->>PR: 推送修复提交

@claude review this PR and check for security issues
@claude the error handling in logger.ts needs improvement
@claude add unit tests for the Logger class

## GitFlow Strategy

### Branch Types
- `main`: Production-ready code, always deployable
- `develop`: Integration branch for features
- `feat/*`: Feature development (branched from develop)
- `fix/*`: Bug fixes (branched from develop)
- `hotfix/*`: Production hotfixes (branched from main)
- `release/*`: Release preparation (branched from develop)

### Merge Strategy
- Feature → develop: Squash merge
- Release → main: Merge commit with tag
- Hotfix → main AND develop: Cherry-pick

> 基于 develop 创建 release/v0.2.0 分支，合并所有已完成的特性

# 确认当前在 develop 分支
git checkout develop

# 创建 release 分支
git checkout -b release/v0.2.0

# 查看已合并的特性分支
git branch --merged develop | grep feat/

# 推送 release 分支
git push -u origin release/v0.2.0

> 合并 feat/add-config 分支到 develop，如果有冲突请帮我解决

# 尝试合并
git checkout develop
git merge feat/add-config

# 如果有冲突，Claude Code 会：
# 1. 读取冲突文件
# 2. 分析两侧变更的意图
# 3. 生成合并方案
# 4. 展示给用户确认

<<<<<<< HEAD (develop)
import { Logger } from './logger';
=======
import { Logger, createLogger } from './logger';
>>>>>>> feat/add-config

检测到 src/index.ts 中的合并冲突：
- develop 分支仅导入了 Logger
- feat/add-config 分支同时导入了 Logger 和 createLogger
- 建议：保留 feat/add-config 的完整导入（更全面）
是否采纳？[Y/n]

{
  "hooks": {
    "pre-commit": [
      "npm run lint",
      "npm test"
    ]
  }
}

## Batch Operations
When asked to "clean up branches":
1. List all merged branches: `git branch --merged main`
2. Exclude: main, develop, release/*
3. Delete local merged branches
4. Prune remote-tracking references

> 清理已合并的分支

# Claude Code 执行
git branch --merged main
# 输出: feat/add-logger, fix/typo, feat/add-config

# 删除已合并的本地分支
git branch -d feat/add-logger fix/typo feat/add-config

# 清理远程引用
git remote prune origin

> 对最近 3 个提交执行交互式变基，合并相关的提交

# 查看最近提交
git log --oneline -3
# abc1234 feat(logger): add structured logging module
# def5678 chore: update dependencies
# ghi9012 feat(logger): add log rotation support

检测到 2 个相关提交可以合并：
- abc1234 feat(logger): add structured logging module
- ghi9012 feat(logger): add log rotation support

合并后的提交信息建议：
feat(logger): add logging module with rotation support

是否继续？[Y/n]

# 执行 squash
git rebase -i HEAD~3
# 在编辑器中将 ghi9012 设为 fixup

git reset --soft HEAD~3
git commit -m "feat(logger): add logging module with rotation support

- Structured logging with DEBUG/INFO/WARN/ERROR levels
- Log rotation support for file-based output
- Factory pattern via createLogger()

Co-Authored-By: Claude <[email protected]>"

> 根据最近的提交生成 CHANGELOG.md

# 获取格式化的提交历史
git log --oneline v0.1.0..HEAD

# Changelog

## [0.2.0] - 2026-05-24

### Features
- **logger**: Add structured logging module with level support (abc1234)
- **logger**: Add log rotation support for file-based output (ghi9012)
- **config**: Add environment-based configuration loader (jkl3456)

### Bug Fixes
- **logger**: Fix timestamp format in non-UTC environments (mno7890)

### Chores
- Update dependencies to latest versions (def5678)

# Team Git Workflow

## Protected Branches
- `main`: Requires 2 approvals, CI must pass, no direct push
- `develop`: Requires 1 approval, CI must pass

## Commit Convention (Mandatory)
All commits MUST follow Conventional Commits. Non-compliant commits
will be rejected by CI.

Format: `type(scope): description`
- type: feat|fix|docs|style|refactor|perf|test|build|ci|chore|revert
- scope: module name (logger, config, api, ui, etc.)
- description: imperative mood, lowercase, no period

Examples:
✅ feat(api): add user authentication endpoint
✅ fix(logger): resolve timestamp timezone issue
❌ Added new feature
❘ fix: stuff
❌ feat(api): Add user authentication endpoint.

## PR Rules
- Max 400 lines changed per PR
- Must include test coverage for new features
- Must update relevant documentation
- Title follows commit convention
- Use draft PR for work-in-progress

> 审查当前 PR 的所有变更，重点关注安全问题和性能问题

## Code Review: feat/logger 分支

### 🔴 Critical Issues
1. **src/logger.ts:24** - Potential log injection
   - User input is directly logged without sanitization
   - Suggestion: Add `sanitize()` function to strip ANSI codes

### 🟡 Warnings
2. **src/logger.ts:15** - Performance concern
   - `new Date().toISOString()` called on every log entry
   - Consider caching timestamp per second

### 🟢 Suggestions
3. **src/logger.ts:8** - Type safety
   - `LogLevel` could use `as const` for better type inference
4. **src/index.ts:3** - Error handling
   - `createLogger()` should validate context string

name: Claude Code CI

on:
  pull_request:
    types: [opened, synchronize]

jobs:
  claude-auto-review:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Auto Review
        uses: anthropics/claude-code-action@v1
        with:
          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
          prompt: |
            Review this PR following our CLAUDE.md conventions.
            Check commit messages follow Conventional Commits.
            Verify no secrets or .env files are included.
            Flag any security concerns.

  validate-commits:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          ref: ${{ github.event.pull_request.head.sha }}
          fetch-depth: 0

      - name: Check Commit Messages
        run: |
          # Validate all commits follow Conventional Commits
          git log --format=%s origin/main..HEAD | while read msg; do
            if ! echo "$msg" | grep -qE "^(feat|fix|docs|style|refactor|perf|test|build|ci|chore|revert)(\(.+\))?: .+"; then
              echo "❌ Invalid commit message: $msg"
              exit 1
            fi
          done
          echo "✅ All commit messages are valid"

graph TD
    A[主工作目录<br>claude-git-demo<br>分支: main] --> B[Worktree 1<br>../claude-git-demo-feat-logger<br>分支: feat/add-logger]
    A --> C[Worktree 2<br>../claude-git-demo-fix-typo<br>分支: fix/typo]
    A --> D[Worktree 3<br>../claude-git-demo-release<br>分支: release/v0.2.0]

    style A fill:#e3f2fd
    style B fill:#e8f5e9
    style C fill:#fff3e0
    style D fill:#f3e5f5

> 使用 worktree 为 feat/add-formatter 功能创建并行工作环境

# 创建 worktree
git worktree add ../claude-git-demo-formatter feat/add-formatter

# 在新 worktree 中启动 Claude Code
cd ../claude-git-demo-formatter
claude

## Worktree Conventions
- Worktree directory naming: `../{project}-{branch-suffix}`
- Always remove worktree after branch is merged: `git worktree remove`
- Max 3 concurrent worktrees to avoid confusion

# Claude Code 执行了错误的提交？撤回最近一次提交（保留更改）
git reset --soft HEAD~1

# 推送了错误的分支？
git push origin --delete feat/wrong-branch

# 需要恢复已删除的分支？
git reflog  # 找到提交哈希
git checkout -b feat/recovered <hash>

flowchart TB
    Start[收到新需求] --> Plan[进入 Plan Mode<br>规划实现方案]
    Plan --> Branch[创建功能分支<br>feat/xxx]
    Branch --> Code[编码 + Claude Code 辅助]
    Code --> Lint{Lint 通过?}
    Lint -->|No| Code
    Lint -->|Yes| Test{测试通过?}
    Test -->|No| Code
    Test -->|Yes| Commit[智能提交<br>Conventional Commits]
    Commit --> Push[推送分支到远程]
    Push --> PR[创建 PR<br>自动生成描述]
    PR --> Review{Code Review}
    Review -->|需修改| Code
    Review -->|Approved| Merge[合并到 develop/main]
    Merge --> Cleanup[清理分支<br>更新 Changelog]
    Cleanup --> Done[发布 ✅]

    style Start fill:#e3f2fd
    style Done fill:#c8e6c9
    style Lint fill:#fff9c4
    style Test fill:#fff9c4
    style Review fill:#fff9c4

# Git Workflow Configuration

## Commit Convention
- Format: `type(scope): description`
- Types: feat, fix, docs, style, refactor, perf, test, build, ci, chore, revert
- Scope: module or component name
- Description: imperative mood, lowercase, ≤72 chars
- Body: explain WHY, not WHAT
- Never commit: .env, secrets, credentials, *.key, *.pem

## Branch Strategy
- main: protected, production-ready only
- develop: integration branch
- feat/*: from develop, squash merge back
- fix/*: from develop, squash merge back
- hotfix/*: from main, cherry-pick to develop
- release/*: from develop, merge to main with tag

## Pull Request Rules
- Title: same format as commit message
- Body: Summary + Changes + Test Plan
- Max 400 lines diff
- CI must pass
- 1+ approval required

## Automation
- Pre-commit: lint + type-check
- Pre-push: test suite
- On PR open: auto review via Claude Code Action
- On merge: auto-generate changelog

---

## Claude Code 核心命令速查

| 命令 | 用途 | 示例场景 |
|------|------|----------|
| `claude` | 启动交互式 REPL | 日常开发对话 |
| `claude -p "提示"` | 单次执行模式 | CI/CD、批量任务 |
| `/init` | 自动生成 CLAUDE.md | 新项目初始化 |
| `/plan` | 进入规划模式 | 大型重构、架构决策 |
| `/compact` | 压缩上下文 | 长会话性能优化 |
| `/review` | 代码审查 | 提交前质量检查 |
| `/skills` | 查看已安装 Skills | 确认 Skill 加载 |
| `/mcp` | 管理 MCP 服务器 | 连接外部工具 |
| `Ctrl+R` | 切换权限模式 | 调整自动允许范围 |
| `Escape` | 中断当前操作 | 停止正在执行的任务 |

---

## 常见问题与解决方案

### Q1: Claude Code 生成的 Vue 组件用了 Options API

**解决方案**：在 CLAUDE.md 中明确指定使用 Composition API：

```markdown
## Code Style
- 必须使用 Vue 3 `<script setup lang="ts">` 语法
- 禁止使用 Options API
- 禁止使用 Vue 2 风格的 `this.xxx`

## Nuxt Auto-Imports
- Vue API (ref, computed, watch, onMounted 等) 无需 import
- 组件自动从 components/ 导入
- Composables 自动从 composables/ 导入
- 不要为这些生成 import 语句

> /plan 检查 server/api/ 目录下所有文件，确认路由路径是否正确