<!-- title: Claude Code Git全栈：从init到PR自动化 -->

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

> **适用人群**：已安装 Claude Code 但尚未建立规范 Git 工作流的开发者。无论你是个人开发者还是团队成员，本教程将带你从 `git init` 到 Pull Request 自动化，构建一套 Claude Code 原生的版本控制流程。
>
> **学习目标**：掌握 Claude Code 与 Git/GitHub 的深度集成能力，包括智能提交、分支管理、冲突解决、PR 创建、GitHub Actions 联动，以及 CLAUDE.md 中的 Git 规范配置。

---

## 一、为什么需要 Claude Code Git 工作流

传统 Git 工作流依赖开发者手动执行每一步：暂存文件、编写提交信息、创建分支、推送代码、发起 PR。每一步都可能因为疲劳或疏忽而出错——提交信息不规范、忘记暂存关键文件、分支命名混乱。

Claude Code 改变了这个范式。它**读取你的代码变更**、**理解变更意图**、**自动生成语义化提交信息**、**创建 PR 并附上结构化描述**——全部在终端内完成，无需切换工具。

```mermaid
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
```

这不是简单的"用 AI 写 commit message"。Claude Code 的 Git 集成是**全链路**的——从理解你的 CLAUDE.md 中的提交规范，到执行 `gh` CLI 命令创建 PR，再到在 PR 评论中触发自动化代码审查。

---

## 二、前置条件

### 2.1 环境要求

| 工具 | 最低版本 | 用途 |
|------|---------|------|
| Node.js | 18+ | 运行 Claude Code |
| Claude Code | 最新版 | `npm install -g @anthropic-ai/claude-code` |
| Git | 2.30+ | 版本控制 |
| GitHub CLI (`gh`) | 2.40+ | PR/Issue 操作 |
| GitHub 账号 | - | 已登录 `gh auth login` |

### 2.2 验证安装

```bash
# 检查 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 status` 显示未登录，执行：

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

### 2.3 常见问题

**Q: `claude` 命令找不到？**

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

**Q: `gh` 认证失败？**

确保你已安装 GitHub CLI 并完成了 OAuth 认证流程。如果使用企业版 GitHub，需要指定 `--hostname` 参数。

---

## 三、实战项目：从零构建 Git 工作流

我们将创建一个 TypeScript 工具项目，通过完整的 Git 生命周期演示 Claude Code 的 Git 能力。

### 3.1 项目初始化

```bash
# 创建项目目录
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 Code：

```bash
claude
```

### 3.2 配置 CLAUDE.md 的 Git 规范

CLAUDE.md 是 Claude Code 理解项目约定的核心文件。在其中定义 Git 规范，Claude Code 会严格遵循。

在项目根目录创建 `CLAUDE.md`：

```markdown
# 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.md 文件定义了：
- **提交规范**：Conventional Commits 格式，强制 type(scope) 结构
- **分支命名**：按功能/修复分类的前缀规则
- **PR 规范**：标题、描述、审查流程的标准化要求
- **安全规则**：禁止推送敏感信息、禁止 force push

Claude Code 在每次 Git 操作时会读取并遵循这些规则。

### 3.3 第一次智能提交

让 Claude Code 帮你完成初始提交：

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

Claude Code 的执行过程：

```bash
# 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 <noreply@anthropic.com>"
```

注意 Claude Code 生成的提交信息：
- **遵循 Conventional Commits**：`chore(init):` 符合 CLAUDE.md 定义的格式
- **包含详细描述**：用列表说明了具体变更
- **自动添加 Co-Authored-By**：标识 AI 参与的代码

### 3.4 功能分支开发

现在我们来演示功能分支的完整流程：

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

Claude Code 的执行过程：

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

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

Claude Code 会生成代码：

```typescript
// 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);
}
```

```typescript
// 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'));
```

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

Claude Code 执行：

```bash
# 暂存并提交
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 <noreply@anthropic.com>"

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

---

## 四、Pull Request 自动化

### 4.1 从终端创建 PR

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

Claude Code 会分析分支上所有提交和文件变更，自动生成 PR：

```bash
# 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
)"
```

注意 PR 描述的几个关键特征：
- **Summary**：一句话概括 PR 目的
- **Changes**：逐文件说明具体变更
- **Test Plan**：可勾选的验证清单
- **品牌标识**：自动添加 Claude Code 生成标记

### 4.2 PR 内容模板化

在 CLAUDE.md 中定义 PR 模板，确保每次创建 PR 都遵循统一格式：

```markdown
## 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
```

### 4.3 使用 @claude 进行 PR Code Review

Claude Code GitHub Actions 允许在 PR 中通过 `@claude` 触发 AI 代码审查。

在仓库中创建 `.github/workflows/claude-review.yml`：

```yaml
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
```

工作流程：

```mermaid
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: 推送修复提交
```

在 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 + Claude Code 实战

### 5.1 配置 GitFlow 结构

在 CLAUDE.md 中定义完整的 GitFlow 规范：

```markdown
## 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
```

### 5.2 一键式 GitFlow 操作

利用 Claude Code 的 `/` 斜杠命令或自然语言执行 GitFlow 操作：

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

Claude Code 执行：

```bash
# 确认当前在 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
```

### 5.3 冲突解决

当合并冲突发生时，Claude Code 可以智能地分析冲突原因并给出解决方案：

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

Claude Code 的冲突解决流程：

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

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

Claude Code 在处理冲突时会读取文件中的冲突标记：

```
<<<<<<< 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]
```

---

## 六、高级 Git 自动化

### 6.1 提交前自动检查（Hooks 集成）

在 `.claude/settings.json` 中配置 pre-commit hook：

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

每次 Claude Code 执行 `git commit` 前会自动运行 lint 和测试。如果失败，提交会被阻止。

### 6.2 批量分支操作

在 CLAUDE.md 中定义批量操作规则：

```markdown
## 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
```

然后直接用自然语言触发：

```
> 清理已合并的分支
```

```bash
# 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
```

### 6.3 交互式变基（Rebase）

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

Claude Code 会分析最近的提交历史：

```bash
# 查看最近提交
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]
```

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

> **注意**：Claude Code 不会使用 `git rebase -i`（交互式变基需要编辑器），而是使用非交互方式：

```bash
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 <noreply@anthropic.com>"
```

### 6.4 Changelog 自动生成

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

Claude Code 会分析 `git log` 中的 Conventional Commits：

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

生成结构化 Changelog：

```markdown
# 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)
```

---

## 七、团队协作场景

### 7.1 多人协作的 CLAUDE.md 规范

在团队项目中，CLAUDE.md 应包含更严格的 Git 规范：

```markdown
# 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
```

### 7.2 Code Review 自动化

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

Claude Code 的审查输出：

```
## 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
```

### 7.3 团队级 CI/CD 集成

`.github/workflows/claude-ci.yml`：

```yaml
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"
```

---

## 八、Git Worktree 并行开发

### 8.1 什么是 Git Worktree

Git Worktree 允许你同时检出多个分支到不同目录，无需 stash 或 commit 当前工作。

```mermaid
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
```

### 8.2 Claude Code + Worktree 实战

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

Claude Code 执行：

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

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

在 CLAUDE.md 中配置 Worktree 规范：

```markdown
## 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
```

---

## 九、常见问题与故障排除

### 9.1 问题诊断清单

| 问题 | 原因 | 解决方案 |
|------|------|---------|
| Claude Code 不遵循 commit 规范 | CLAUDE.md 中未定义或格式错误 | 检查 CLAUDE.md 的 Git Conventions 部分 |
| `gh pr create` 失败 | 未认证或无远程仓库 | `gh auth login` + `git remote add origin` |
| 提交信息重复或不准确 | 上下文窗口不足 | 使用 `/compact` 压缩对话后再操作 |
| Hook 执行失败阻止提交 | lint/test 未通过 | 先修复代码问题，或临时禁用 hook |
| Worktree 冲突 | 同一分支已在其他 worktree 检出 | `git worktree remove` 旧 worktree |
| Claude Code 忘记 Git 规范 | 会话过长导致上下文丢失 | 重新提及 CLAUDE.md 或重启会话 |

### 9.2 紧急恢复

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

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

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

---

## 十、完整工作流程图

```mermaid
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
```

---

## 十一、CLAUDE.md Git 配置速查模板

以下是一份可直接复制使用的完整 Git 配置模板：

```markdown
# 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
```

---

## 十二、训练营适用性评估

| 维度 | 评估 |
|------|------|
| **适合训练营类型** | AI 辅助开发训练营、DevOps 工程实践、团队协作工作坊 |
| **前置知识要求** | Git 基础操作（add/commit/push）、命令行基础 |
| **教学时长** | 3-4 小时（含实操练习） |
| **难度等级** | ⭐⭐ 初中级 |
| **实操占比** | 70% 实操 + 30% 理论 |
| **所需设备** | 笔记本电脑，已安装 Node.js 18+ 和 Git |
| **扩展方向** | CI/CD 管道构建、Monorepo 管理、代码审查自动化 |

**推荐课程结构**：
- **第1小时**：环境搭建 + CLAUDE.md 配置 + 第一次智能提交
- **第2小时**：功能分支开发 + PR 创建自动化
- **第3小时**：GitFlow 实战 + GitHub Actions 集成
- **第4小时**：团队协作场景模拟 + 故障排除演练

---

## 延伸阅读

- [Claude Code 官方文档 - Quickstart](https://code.claude.com/docs/en/quickstart) — Anthropic 官方快速入门指南
- [Claude Code 官方文档 - Best Practices](https://code.claude.com/docs/en/best-practices) — 官方最佳实践和模式
- [Claude Code GitHub Actions](https://code.claude.com/docs/en/github-actions) — CI/CD 集成官方文档
- [Claude Code Cheat Sheet 2026](https://computingforgeeks.com/claude-code-cheat-sheet/) — 命令速查和配置参考

---

## 参考来源

1. [Claude Code Quickstart — 官方快速入门](https://code.claude.com/docs/en/quickstart) — Anthropic 官方文档，安装和基础使用
2. [Best Practices for Claude Code](https://code.claude.com/docs/en/best-practices) — 官方最佳实践，环境配置到规模化使用
3. [Claude Code GitHub Actions](https://code.claude.com/docs/en/github-actions) — 官方 CI/CD 集成文档
4. [How to Use Claude Code With GitHub: Commits, PRs, and Branch Workflows](https://blink.new/blog/claude-code-github-workflow) — Git 工作流深度指南
5. [Git Integration Best Practices — SFEIR Institute](https://institute.sfeir.com/en/claude-code/claude-code-git-integration/best-practices/) — 企业级 Git 集成实践
6. [Hands-On: Automating Git Workflows — SitePoint](https://www.sitepoint.com/handson-with-claude-code-automating-git-workflows-and-legacy-refactoring/) — 实战案例和遗留代码重构
7. [Complete Guide to Git Flow in Claude Code](https://medium.com/@dan.avila7/complete-guide-to-setting-up-git-flow-in-claude-code-616477941f78) — GitFlow 配置完整指南
api/tasks
    API-->>CC: [task list]
    CC-->>U: 测试报告 ✓

    U->>CC: /plan 替换为数据库
    CC->>CC: 分析影响范围
    CC-->>U: 显示修改计划
    U->>CC: 确认执行
    CC->>API: 重构存储层
```

---

## 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`
```

### Q2: Nuxt 自动导入不生效

**原因**：Claude Code 可能不知道 Nuxt 的自动导入机制，手动添加了 `import` 语句。

**解决方案**：在 CLAUDE.md 或 Skill 中说明：

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

### Q3: 服务端 API 路由 404

**原因**：文件命名或位置不正确。Nuxt 的文件路由对位置和命名有严格要求。

**解决方案**：
```
> /plan 检查 server/api/ 目录下所有文件，确认路由路径是否正确
```

Claude Code 会逐一验证文件路径与路由的对应关系。

### Q4: `$fetch` 和 `useFetch` 该用哪个

| 场景 | 推荐使用 | 原因 |
|------|----------|------|
| 组件中需要 SSR | `useFetch` | 支持服务端渲染，避免双重请求 |
| 非 Vue 组件中 | `$fetch` | 纯函数调用，无 Vue 上下文 |
| Pinia Store 中 | `$fetch` | Store 不在组件上下文中 |

---

## 延伸阅读

- [Anthropic Claude Code 官方文档](https://docs.anthropic.com/en/docs/claude-code) — 最权威的参考来源，涵盖所有命令和配置选项
- [Nuxt 3 官方文档](https://nuxt.com/docs) — Vue 3 元框架的完整指南，包括 Nitro 服务器引擎
- [Spec-Driven Development with Claude Code](https://dev.to/guayoyo_tech/spec-driven-development-with-claude-code-build-a-nuxt-app-from-scratch-part-1-of-3-4826) — 用规范驱动开发方式构建 Nuxt 应用的三部分教程
- [Claude Code 最佳实践](https://code.claude.com/docs/en/best-practices) — 官方推荐的提示词工程和项目配置模式
- [Vue 3 & Nuxt Architect Skill](https://mcpmarket.com/tools/skills/vue-3-nuxt-architect) — 社区开发的 Vue/Nuxt 专用 Claude Code Skill

---

## 参考来源

1. [Quickstart - Claude Code Docs](https://code.claude.com/docs/en/quickstart) — Anthropic 官方 Claude Code 快速入门指南
2. [Spec-Driven Development with Claude Code: Build a Nuxt App from Scratch](https://dev.to/guayoyo_tech/spec-driven-development-with-claude-code-build-a-nuxt-app-from-scratch-part-1-of-3-4826) — 使用规范驱动开发构建 Nuxt 应用的实战教程
3. [Claude Code Best Practices: 15 Tips from 6 Projects](https://aiorg.dev/blog/claude-code-best-practices) — 基于六个生产项目的 Claude Code 最佳实践总结
4. [Claude Code Tutorial for Beginners - Complete 2026 Guide](https://codewithmukesh.com/blog/claude-code-for-beginners/) — 面向初学者的 Claude Code 完整教程
5. [Vue, Nuxt & Vite Status in 2026](https://fivejars.com/insights/vue-nuxt-vite-status-for-2026-risks-priorities-architecture-updates/) — Vue/Nuxt 生态 2026 年架构更新与优先级分析

---

## 训练营适用性评估

| 维度 | 评估 |
|------|------|
| **适合训练营类型** | 前端全栈速成营、AI 编程工具训练营、Vue 3 实战训练营 |
| **学员基础要求** | 了解 HTML/CSS/JavaScript 基础，无需 Vue 经验 |
| **预计教学时长** | 4-6 小时（含动手实践） |
| **难度曲线** | 前两步平缓（安装配置），第三到六步中等（组件开发），七八步有挑战（API + 集成） |
| **可扩展方向** | 接入 Supabase 数据库、添加用户认证、部署到 Vercel/Cloudflare、添加实时协作 |
| **硬件要求** | 任意能运行 Node.js 的开发机，无需 GPU |

> [!tip] 51学通信知识星球
> **星主：爱卫生**（微信：gprshome201101）——公众号「51学通信」创办者，19 年通信行业运维与讲师经验，著有《GPRS网络信令实例详解》《EPC原理与实践》《5G核心网原理与实践》三本纸质书（各大电商平台有售）。
> **星球定位**：深耕 5G 核心网、IMS、NFV/AI、云原生等 ICT 领域，主打运维岗位与信令分析。
> **当前规模**：5200 篇主题 / 990 个回答，198 元/年。
> **加入福利**：加入星球后请加爱卫生微信，拉您进知识星球年度陪伴与答疑群——不限量回复您的各种问题，另有群内分享。
> **AI 加持**：51学通信知识星球已作为 skill 接入 WorkBuddy，使用 deepseek-4-flash 在海量星球帖子中精准找贴、找视频、找 FAQ 和案例，做总结、找文档和 PPT 等场景全覆盖。

![51学通信知识星球海报-扫码加入](https://wiki.500nian.com/images/zhixingqiu_qrcode.png)