Claude Code in Action 深度导读
Claude Code 进阶导读——Hooks 系统、SDK 编程接口、MCP 集成、GitHub Actions 与 CI/CD 全链路自动化。
目录
Claude Code 进阶导读——Hooks 系统、SDK 编程接口、MCP 集成、GitHub Actions 与 CI/CD 全链路自动化。
Section 1 · 什么是 Claude Code
Claude Code 是 Anthropic 的 Agentic 编程 CLI 工具:它不仅能回答编程问题,更能在你的真实代码仓库中规划、执行和验证多步骤编程任务。本节建立对 Claude Code 架构和 Agentic 编程范式的理解。
What Is Claude Code — Architecture and Agentic Coding
Claude Code 是 Anthropic 的 Agentic 编程 CLI 工具:它不仅能回答编程问题,更能在你的真实代码仓库中规划、执行和验证多步骤编程任务。本节建立对 Claude Code 架构和 Agentic 编程范式的理解。
传统 AI 编程助手
- 在 IDE 中提供内联建议
- 一次建议一段代码片段
- 无法执行命令或验证结果
- 理解范围限于当前文件
Claude Code (Agentic)
- 在终端中独立工作
- 规划多步骤任务并逐步执行
- 读写文件、运行命令、验证输出
- 理解整个代码仓库的上下文
Claude Code 核心架构
claude 启动交互会话Section 2.1 · 环境搭建与上下文配置
正确的环境配置和上下文提供是 Claude Code 产出质量的基石。本节覆盖安装、项目初始化和 CLAUDE.md 的进阶用法。
Setup and Giving Claude Context
正确的环境配置和上下文提供是 Claude Code 产出质量的基石。本节覆盖安装、项目初始化和 CLAUDE.md 的进阶用法。
npm install -g @anthropic-ai/claude-codeclaudeCLAUDE.md — 项目级规范入口.claude/settings.json 定义权限和工具白名单CLAUDE.md 进阶用法
CLAUDE.md 不仅仅是"项目说明"——它是你与 Claude Code 之间的操作契约。写得好的 CLAUDE.md 能让 Claude 的输出质量提升 2-3 倍。
| 层级 | 位置 | 作用 | 内容示例 |
|---|---|---|---|
| 全局 | ~/.claude/CLAUDE.md | 所有项目的默认规则 | 编码风格、语言偏好、Git 规范 |
| 项目 | ./CLAUDE.md | 本项目的架构和规范 | 技术栈、命名约定、测试要求 |
| 模块 | ./src/api/CLAUDE.md | 模块级别的特殊规则 | API 设计规范、认证流程 |
| 动态 | .claude/settings.json | 运行时配置 | 工具权限、超时设置 |
# CLAUDE.md
## Project Overview
E-commerce platform (Next.js 14 + tRPC + Prisma + PostgreSQL)
## Commands
- Build: `pnpm build`
- Test: `pnpm test`
- Lint: `pnpm lint`
## Code Style
- Use TypeScript strict mode
- Prefer named exports over default exports
- Error handling: use Result type, never throw in business logic
- Tests: co-locate with source files (*.test.ts)
## Architecture Decisions
- Server Components by default; Client Components only for interactivity
- API routes via tRPC; no REST endpoints
- Database migrations via Prisma; never modify schema manuallySection 2.2 · 代码修改与自定义命令
掌握 Claude Code 的核心工作流:从描述需求到代码落地、从自定义 Slash Command 到利用记忆系统保持会话连贯性。
Making Changes, Custom Commands, and Memory
掌握 Claude Code 的核心工作流:从描述需求到代码落地、从自定义 Slash Command 到利用记忆系统保持会话连贯性。
先描述"要什么"而非"怎么做"。Claude 会自动搜索相关代码、理解依赖关系、规划修改步骤。
Claude 每次修改后会展示完整 diff。逐个审查,按 y 接受、n 拒绝、或给出修改意见让 Claude 调整。
在 .claude/commands/ 目录创建 Markdown 文件,定义可复用的工作流。例如 /review、/test-coverage、/deploy。
# .claude/commands/review.md
Review the staged changes for:
1. Logic errors and edge cases
2. Security vulnerabilities (SQL injection, XSS, auth bypass)
3. Performance issues (N+1 queries, unnecessary re-renders)
4. Missing test coverage for new code paths
Output format:
- CRITICAL: Must fix before merge
- WARNING: Should fix, create issue if not now
- NOTE: Nice-to-have improvements记忆系统
Claude Code 的记忆系统让它跨会话保持对项目的理解:
| 记忆类型 | 存储位置 | 特点 |
|---|---|---|
| 项目记忆 | .claude/memory.md | 项目级的长期记忆,所有会话共享 |
| 会话记忆 | 会话内缓存 | 当前会话的所有操作和上下文 |
| CLAUDE.md | 项目根目录 | 显式规范,每次会话自动加载 |
Section 2.3 · MCP 集成与 GitHub 工作流
通过 MCP (Model Context Protocol) 连接外部工具和服务,并将 Claude Code 深度集成到 GitHub 工作流中——从 PR 创建到代码审查全链路自动化。
MCP Integration and GitHub Workflows
通过 MCP (Model Context Protocol) 连接外部工具和服务,并将 Claude Code 深度集成到 GitHub 工作流中——从 PR 创建到代码审查全链路自动化。
MCP(外部工具集成)
- 连接数据库(PostgreSQL、MongoDB……)
- 访问 API(Jira、Linear、Notion……)
- 操控浏览器(Playwright、Puppeteer)
- 自定义工具服务器(用 Python/Node 开发)
GitHub 集成
- 自动创建 PR 并填写描述
- 在 PR 评论中触发 Claude Code
- CI/CD Pipeline 中作为 reviewer
- Issue → Branch → PR 全链路自动化
# .claude/settings.json
{
"mcpServers": {
"github": {
"command": "npx",
"args": ["-y", "@anthropic-ai/github-mcp-server"],
"env": { "GITHUB_TOKEN": "env:GITHUB_TOKEN" }
},
"playwright": {
"command": "npx",
"args": ["@anthropic-ai/playwright-mcp-server"]
}
}
}GitHub PR 工作流
/pr 命令自动创建 Pull RequestSection 3.1 · Hooks 系统
Hooks 是 Claude Code 的事件系统:在特定时间点(会话开始、工具调用前后、消息发送后等)自动执行自定义脚本。它让你能在不修改 Claude Code 本身的前提下,注入自定义逻辑。
The Hooks System — Automating Claude Code's Behavior
Hooks 是 Claude Code 的事件系统:在特定时间点(会话开始、工具调用前后、消息发送后等)自动执行自定义脚本。它让你能在不修改 Claude Code 本身的前提下,注入自定义逻辑。
| Hook | 触发时机 | 典型用途 |
|---|---|---|
PreToolUse | 工具调用之前 | 阻止危险操作、记录操作日志 |
PostToolUse | 工具调用之后 | 自动格式化代码、触发测试 |
PreSendMessage | 发送消息给模型前 | 注入额外上下文、修改提示词 |
PostSendMessage | 收到模型响应后 | 日志记录、质量检查 |
SessionStart | 会话开始时 | 加载环境变量、初始化工具 |
SessionEnd | 会话结束时 | 清理临时文件、生成报告 |
# .claude/settings.json
{
"hooks": {
"PostToolUse": [
{
"matcher": "edit_file",
"command": "npx eslint --fix $CLAUDE_FILE_PATH",
"timeout": 10000
}
]
}
}
# 效果:每次 Claude 编辑文件后,自动运行 ESLint 修复
# 如果 lint 失败,Claude 会看到错误并自行修复Section 3.2 · Claude Code SDK 与 CI/CD
Claude Code SDK 让你以编程方式调用 Claude Code 的全部能力——将 Agentic 编程嵌入到脚本、CI/CD Pipeline 和自动化工作流中。
SDK, Automation, and CI/CD Integration
Claude Code SDK 让你以编程方式调用 Claude Code 的全部能力——将 Agentic 编程嵌入到脚本、CI/CD Pipeline 和自动化工作流中。
使用 claude -p "task" 在脚本中运行单次任务。适合 CI/CD Pipeline 中的代码审查、文档生成。
通过 TypeScript/Python SDK 创建自定义的 Agentic 工作流——把 Claude Code 作为其他系统的"大脑"。
在 PR 创建时自动触发 Claude Code 进行代码审查,审查结果作为 PR Comment 自动发布。
结合 claude -p 和 Shell 脚本,批量处理仓库中的任务:迁移 API、更新依赖、生成文档。
# .github/workflows/claude-review.yml
name: Claude Code Review
on:
pull_request:
types: [opened, synchronize]
jobs:
review:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Claude Code Review
run: |
npx @anthropic-ai/claude-code -p \
"Review the changes in this PR.
Focus on: bugs, security, performance.
Output as GitHub PR comment format." \
--allowedTools "Read,Grep,Glob" \
| gh pr comment ${{ github.event.pull_request.number }} \
--body-file -
env:
ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}SDK 使用模式
| 模式 | 命令 | 适用场景 |
|---|---|---|
| 交互式 | claude | 日常开发、探索、调试 |
| 单任务 | claude -p "task" | 脚本、CI/CD、自动化 |
| 管道 | cat file | claude -p "analyze" | 处理 stdin 输入 |
| SDK | TypeScript/Python API | 自定义 Agentic 系统 |
Section 3.3 · 调试与故障排除
当 Claude Code 的行为不符合预期时,如何系统性地排查问题。
Debugging Claude Code
当 Claude Code 的行为不符合预期时,如何系统性地排查问题。
| 症状 | 可能原因 | 排查步骤 |
|---|---|---|
| Claude 不遵循 CLAUDE.md 规则 | 文件位置/格式错误 | 确认 CLAUDE.md 在项目根目录;检查语法 |
| 工具调用被拒绝 | 权限配置不足 | 检查 .claude/settings.json 的 allowedTools |
| 修改了错误的文件 | 上下文不足 | 在 CLAUDE.md 中明确文件结构和修改范围 |
| 测试未自动运行 | Hook 未配置或超时 | 检查 hooks 配置;增加 timeout 值 |
| MCP Server 连接失败 | 环境变量/依赖缺失 | 手动运行 MCP server 命令确认可用 |
claude --version确认版本是最新claude doctor运行内置诊断- 检查
~/.claude/logs/中的详细日志 - 使用
claude --verbose获取详细输出 - 尝试新会话(
claude --new)排除上下文污染
Section 4 · 课程总结与进阶方向
回顾课程核心概念,并展望 Claude Code 的进阶使用方向。
Assessment and Next Steps
回顾课程核心概念,并展望 Claude Code 的进阶使用方向。
知识图谱
| 主题 | 关键概念 | 实践要点 |
|---|---|---|
| 架构 | Agentic Loop、权限模型 | 理解 Claude Code 不是 Copilot,是独立的编程 Agent |
| 上下文 | CLAUDE.md 四层结构、记忆系统 | 投资时间写好 CLAUDE.md,回报是 2-3x 输出质量 |
| 工作流 | Slash Commands、MCP、GitHub | 把重复工作流抽象为自定义命令 |
| 自动化 | Hooks、SDK、CI/CD | 从手动审查过渡到自动化守门 |
先用 Claude Code 完成一个简单的 Bug 修复或文档更新。体验完整的 Agentic 循环。
为你的主要项目写一份高质量的 CLAUDE.md。这是 ROI 最高的单一投入。
把一个重复性的代码审查或部署流程用 Hooks + SDK 自动化。
关注 Anthropic Docs、GitHub Discussions、Discord 社区获取最新最佳实践。