Claude Code 折腾指南

一份从零基础到高阶玩法的 Claude Code 中文指南。
Claude Code 更新极快，本仓库按"框架 + 增量更新"的方式维护。

Overview (English)

A Chinese-language field guide to Claude Code, written from daily use rather than translated from the docs.

• Covers: installation and first run → daily use (context management, plan mode) → workflows (spec-driven development, TDD, review, debugging, long tasks and memory) → configuration (settings layers, CLAUDE.md, permissions, hooks) → MCP and extensions → subagents and parallel worktrees → CI automation → anti-patterns.
• Format: about 60 notes in ten parts, organised as an Obsidian vault (backlinks, graph view) that also reads fine on GitHub.
• Maintenance: maintained as a stable framework plus incremental updates. Chapters with major changes are flagged at the top, and the changelog section covers Claude Code up to v2.1.150.

说明

这不是官方文档的翻译，就是我自己用 Claude Code 过程中顺手记下来的东西。官方文档写得挺全，但很多细节要自己踩过才知道——比如 context 什么时候会悄悄污染、hooks 的执行顺序为什么跟你想的不一样、MCP 连不上时该从哪里查。这些"踩坑笔记"散在各处很难找，所以整理成了这份指南。

内容按 Obsidian Vault 组织，但在 GitHub 上直接读也没问题。如果你有 Obsidian，用它打开体验更好（双向链接、图谱都能用），见下方说明。

Claude Code 更新很快，基本每周都有变化。我会持续追更，改动比较大的章节顶部会加提示。如果发现哪里写错了或者已经过时，欢迎提 Issue。

关于我

我是哈尔滨工业大学的一名研0新生，大家可以叫我的网名 xuannn，本科就读于哈工大威海校区电子信息工程，我从去年的11月份开始使用 Claude Code 和 Codex，写这份笔记主要是想给一些入门的同学，一个了解 Claude Code 和这类 agent 的渠道，由于本人的技术水平有限，很多高级用法也是 Claude Code 教给我的。

有问题或者想聊的，可以通过我的 🛰️：xyu_hit 找到我。

适用读者

• 完全新手：装好就能用，看 绪论 → 第一次对话。
• 日常使用者：想把 CLI 用熟、配置调顺，看 02 基础篇 与 04 配置与定制。
• 进阶玩家：研究 subagent、hooks、MCP、并行 worktree、CI 自动化，看 06 高阶篇 与 07 自动化与CI。
• 团队 Lead：想在团队里推广，看 03 工作流篇 + 08 避坑与反模式。

目录

第一部分 · 起步

• 01 入门篇
  • 什么是 Claude Code
  • 安装与登录
  • 第一次对话
  • 界面与基本概念
  • 中转站 API 接入教程

第二部分 · 日常使用

• 02 基础篇
  • 与 Claude 对话的方式
  • 文件读写与编辑
  • Bash 与工具调用
  • Slash 命令一览
  • Plan 模式与 Auto 模式
  • 上下文管理：/clear 与 /compact

第三部分 · 工作流

• 03 工作流篇
  • Spec 驱动开发
  • TDD 与 Claude Code
  • 代码评审与重构
  • 调试与诊断循环
  • 长任务与记忆系统

第四部分 · 配置与定制

• 04 配置与定制
  • settings.json 三级配置
  • CLAUDE.md 分层机制
  • 权限系统 permissions
  • Hooks 钩子系统
  • Status-line 与 Output-style
  • 自定义 Slash 命令
  • Skills 技能系统

第五部分 · MCP 与扩展

• 05 MCP 与扩展
  • MCP 是什么
  • 常用 MCP 服务器
  • 编写自己的 MCP
  • MCP 安全注意事项

第六部分 · 高阶玩法

• 06 高阶篇
  • Subagent 子代理
  • 多 Agent 并行 orchestrator
  • Git Worktree 并行实例
  • Headless 模式与脚本化
  • Context Engineering
  • 大神实践案例集
  • Agent Teams 多会话协调
  • Channels 消息推送

第七部分 · 自动化与 CI

• 07 自动化与 CI
  • GitHub Actions 集成
  • 自动 PR 审查
  • Issue 自动 triage
  • 定时任务与 cron
  • Routines 云端定时任务

第八部分 · 避坑指南

• 08 避坑与反模式
  • 上下文污染
  • 无限循环与失败重试
  • Token 成本控制
  • 何时不该用

维护与参考

• 09 版本更新日志
• 10 资源与参考
• 术语表
• 快捷键与命令速查

用 Obsidian 打开（可选，体验更好）

强烈推荐用 Obsidian 阅读，wiki 链接、反向链接、图谱视图、callout 渲染全部可用。

git clone https://github.com/BeiZi6/easy-cc.git

clone 完成后，打开 Obsidian → "Open folder as vault" → 选中 easy-cc 目录即可。

维护方式

Claude Code 大约每周都有更新。建议：

1. 每次官方发版后，在 09 版本更新日志 新增一条记录。
2. 受影响的章节顶部加警告说明。
3. 旧写法保留在原位，加删除线或折叠，方便回看。
4. 每章末尾的"最后更新"字段同步刷新。

新增内容请遵循"先骨架后血肉"原则——先在对应章节列要点，确认结构后再展开。这能避免反复重写。