别每次重复配置了!CLAUDE.md + Hooks 让 Claude Code 开箱就记住你的规则

Claude Code 高效使用完全指南:从入门到 Sub-agent 并行工作流

Claude Code 是 Anthropic 推出的终端原生 AI 编程助手,核心特性是自主代理循环 ------它能读取文件、执行命令、修改代码,并在无人监督下完成完整任务链,而不只是被动回答问题。截至 2026 年 6 月,Claude Code 已支持 Sub-agent 并行任务、Hooks 自动化触发、CLAUDE.md 持久上下文记忆、以及通过 MCP 协议接入 Notion / Figma / 数据库等外部工具。掌握这套工作流的核心,是管理好上下文窗口------这是影响 Claude Code 实际表现的最关键变量。


为什么上下文管理是第一优先级

Claude Code 每次对话都消耗 context window。一次调试会话、一次代码库探索,可能轻松生成数万 token。上下文越满,模型表现越差:早期指令被遗忘、错误率上升、输出质量下滑。

根据 Anthropic 官方最佳实践文档(2026 年版),以下几类操作是高频"上下文杀手":

  • 无限制的代码库探索(读取大量文件)
  • 在同一会话内堆叠不相关任务
  • 对同一错误重复纠正超过两次而不清空上下文
  • 过长的 CLAUDE.md 文件(规则越多,越容易被忽略)

核心原则:把 /clear 当成 Ctrl+Z------频繁使用,而不是最后一招。


三种工作模式:选对模式效率翻倍

Plan 模式(探索优先)

按 Shift+Tab 两次进入 Plan 模式。此模式下 Claude 只读取分析,不执行任何修改。

适用场景:

  • 多文件架构调整
  • 不确定最佳方案时
  • 需要生成实现计划供人工审核

推荐工作流:

sql 复制代码
Shift+Tab × 2 进入 Plan 模式
→ 让 Claude 读取相关文件,理解现状
→ 要求输出实现计划(可按 Ctrl+G 直接编辑计划文件)
→ 退出 Plan 模式,开始执行
→ 完成后 commit + 开 PR

Auto-accept 模式(无中断执行)

bash 复制代码
# 命令行一次性任务,自动通过权限检查
claude --permission-mode auto -p "fix all lint errors"

适合重复性任务、已验证的操作模式。内置分类器模型会审查每条命令,自动阻断高风险操作(如未知基础设施修改、scope 扩散)。

Step-by-step 模式(逐步确认)

每步操作都需要人工确认,适合学习新技术栈或修改关键业务逻辑。


CLAUDE.md:持久上下文记忆的核心配置

CLAUDE.md 是 Claude Code 在每次会话开始时自动加载的项目记忆文件。它决定了 Claude 是否理解你的代码风格、工作流约定和项目特殊规则。

快速生成初始文件

bash 复制代码
# 在项目根目录运行,自动分析代码库结构生成初始 CLAUDE.md
claude /init

文件存放位置与优先级

位置 作用范围
~/.claude/CLAUDE.md 所有 Claude 会话(全局规则)
./CLAUDE.md 项目级,提交 git 供团队共享
./CLAUDE.local.md 个人项目级,加入 .gitignore
子目录 CLAUDE.md Claude 读取该目录文件时自动加载

写什么、不写什么

✅ 应该写 ❌ 不应该写
Claude 猜不到的 Bash 命令 Claude 读代码就能推断的惯例
与默认不同的代码风格规则 标准语言约定
测试框架和运行方式 频繁变更的信息
分支命名、PR 规范 详细 API 文档(给链接即可)
特定架构决策 自说明的实践(如"写简洁代码")

判断标准:对每一行问自己------"删掉这行,Claude 会犯错吗?"不会就删。

示例 CLAUDE.md

markdown 复制代码
# Code style
- 使用 ES modules (import/export),不用 CommonJS (require)
- 尽可能解构导入

# Workflow
- 修改完成后必须运行 typecheck
- 优先运行单个测试,而非整个测试套件

# Project-specific
- API 接口版本在 URL 路径中(/v1/, /v2/)
- 数据库迁移文件禁止直接修改,只能新增

Sub-agents:并行任务的核心加速器

Sub-agent 是 Claude Code 最强大的扩展机制之一。每个 Sub-agent 运行在独立的上下文窗口中,完成研究或执行任务后仅返回摘要,不污染主会话上下文。

立即可用的 Sub-agent 用法

text 复制代码
# 代码库研究(不消耗主上下文)
Use subagents to investigate how our authentication system handles
token refresh, and whether we have any existing OAuth utilities.

# 并行任务(明确指定并行)
Use 4 parallel subagents to:
1. Investigate auth module
2. Check database schema
3. Review API rate limiting logic
4. Analyze error handling patterns

关键词:"in parallel using separate subagents"------不说 parallel,Claude 可能顺序执行。

创建自定义 Sub-agent

在 .claude/agents/ 目录下创建 Markdown 文件:

markdown 复制代码
<!-- .claude/agents/security-reviewer.md -->
---
name: security-reviewer
description: 代码安全漏洞审查
tools: Read, Grep, Glob, Bash
model: opus
---
你是资深安全工程师。审查以下类型漏洞:
- SQL 注入、XSS、命令注入
- 认证与授权缺陷
- 代码中的凭证或密钥泄露
- 不安全的数据处理

提供具体行号引用和修复建议。

使用时:Use the security-reviewer subagent to review src/api/

Writer/Reviewer 双 Agent 模式

Session A(写代码) Session B(审查)
实现功能 X
在全新上下文中审查 @src/X.ts,查找边界情况
修复审查发现的问题

新鲜上下文的审查更客观------审查者没有受到实现过程的先入为主影响。


Hooks:零例外的自动化触发

Hooks 是确定性执行的脚本触发器,不同于 CLAUDE.md 中的"建议性"规则。每次满足触发条件,Hook 必然执行。

常用触发时机

Hook 类型 触发时机
PreToolUse 工具调用前
PostToolUse 工具调用后
Stop Claude 停止前
InstructionsLoaded CLAUDE.md 加载时

用自然语言创建 Hook

text 复制代码
# 让 Claude 自动创建 hook
Write a hook that runs eslint after every file edit

Write a hook that blocks writes to the migrations/ folder

Claude 会直接编辑 .claude/settings.json 配置文件。也可手动运行 /hooks 查看已配置的 hooks。

典型 Hook 配置示例

json 复制代码
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit",
        "hooks": [
          {
            "type": "command",
            "command": "npm run lint --fix"
          }
        ]
      }
    ]
  }
}

上下文管理实操:5 个高频命令

bash 复制代码
# 1. 清空上下文,开始新任务
/clear

# 2. 压缩上下文,保留关键信息
/compact Focus on the API changes

# 3. 回滚到某个检查点(不破坏 git)
/rewind    # 或双击 Esc

# 4. 快速问问题,不进入上下文
/btw       # 答案在悬浮框显示,不写入对话历史

# 5. 恢复上次会话
claude --continue
claude --resume   # 从列表中选择

上下文管理决策树

arduino 复制代码
任务是否与上次会话相关?
├── 是 → claude --continue 继续
└── 否 → /clear 清空后开始

同一问题是否已纠正两次以上?
└── 是 → /clear + 重写更精准的 prompt

是否需要探索大量文件?
└── 是 → 用 subagent 处理,不消耗主 context

批量任务:用 claude -p 接管 CI/CD

非交互模式是将 Claude Code 接入自动化流程的核心方式:

bash 复制代码
# 单次查询
claude -p "Explain what this project does"

# 结构化输出(供脚本解析)
claude -p "List all API endpoints" --output-format json

# 批量文件迁移(并行执行)
for file in $(cat files.txt); do
  claude -p "Migrate $file from React class component to hooks. Return OK or FAIL." \
    --allowedTools "Edit,Bash(git commit *)" &
done
wait

# 流式 JSON(实时处理)
claude -p "Analyze this log file" --output-format stream-json --verbose

--allowedTools 参数限制无人值守任务的权限范围,防止意外操作超出任务边界。

开发者可以通过标准 OpenAI SDK 格式将 Claude Code 对接到现有工具链,例如七牛云推理服务兼容该接口,无需修改现有 API 调用代码即可切换或混合使用多个模型。


Skills:可复用的领域知识模块

Skills 将领域知识和可复用工作流封装成模块,Claude 在相关场景下自动应用 ,或通过 /skill-name 主动调用。

markdown 复制代码
<!-- .claude/skills/fix-issue/SKILL.md -->
---
name: fix-issue
description: 修复 GitHub Issue 的完整流程
disable-model-invocation: true
---
分析并修复 GitHub Issue:$ARGUMENTS

1. 用 `gh issue view` 获取 issue 详情
2. 搜索相关代码文件
3. 实现修复
4. 编写并运行测试
5. 确认通过 lint 和类型检查
6. 提交 commit 并开 PR

调用方式:/fix-issue 1234

disable-model-invocation: true 确保有副作用的工作流只在手动调用时触发。


常见失败模式与修复方案

失败模式 症状 修复方案
杂货铺会话 一个会话处理多个无关任务 每个任务前 /clear
重复纠正循环 同一问题纠正 2+ 次仍出错 /clear + 重写更精准的 prompt
臃肿 CLAUDE.md Claude 忽略部分规则 只保留"删除会导致错误"的规则
相信"完成了" 代码看起来对但有边界情况 始终提供可运行的验证(测试/构建/截图)
无界探索 让 Claude "研究一下" 导致读数百文件 用 subagent 隔离探索,或给明确范围

常见问题

Q:CLAUDE.md 写多长合适? 官方建议:精简为优。测试方法------如果 Claude 在没有这条规则时仍然表现正确,就删掉它。过长的 CLAUDE.md 会导致重要规则被"淹没",实测效果反而下降。社区研究(2025 年指令跟随实验)发现前沿模型在指令条数超过阈值后遵从率明显下降。

Q:Sub-agent 并行时如何避免文件冲突? 让每个 Sub-agent 操作不同的文件或模块,或用 worktrees 把并行任务放到独立的 git checkout 中(claude worktrees 或桌面端多会话)。Claude Code 文档建议:写操作不并行,只读/分析操作可大量并行。

Q:Hooks 和 CLAUDE.md 规则有什么区别? CLAUDE.md 是"建议"------Claude 会尽量遵守但不保证。Hooks 是"强制"------每次满足条件必然执行,不受上下文影响,适合"必须每次执行"的检查(lint、格式化、阻断敏感目录写入)。

Q:claude -p 非交互模式能做什么? 接入 CI/CD 流水线、pre-commit hooks、批量文件处理、定时任务。支持 --output-format json 或 stream-json 供脚本解析,支持 --allowedTools 精确限权,适合无人值守的大规模任务。

Q:如何在团队中共享 Claude Code 配置? 将 CLAUDE.md、.claude/agents/、.claude/skills/ 提交到 git 仓库即可共享。个人本地配置用 CLAUDE.local.md(加入 .gitignore)。Hooks 配置在 .claude/settings.json,同样可以提交共享。


延伸资源


本文内容基于 2026 年 6 月 Claude Code 官方文档与社区实战数据,建议定期查阅官方 Changelog 以获取最新特性。下一步建议先在本地项目执行 /init 生成 CLAUDE.md,再尝试用 Sub-agent 并行跑一次代码库调研------感受上下文隔离带来的效率差异。

相关推荐
deli0077 分钟前
12 个请求挤一条连接:HTTP/1.1 队头阻塞 vs HTTP/2 多路复用实测
前端
deli00740 分钟前
TCP 为什么会粘包?4 种拆包方案 49 字节实测对比
前端
deli0072 小时前
32K 上下文塞满后,AI 最先忘掉什么?120 轮对话实测
前端
deli0073 小时前
手机拍灯为什么有一条条黑纹?PWM 240Hz 实测
前端
wangruofeng8 小时前
AI Models 1.1.0 发布,查大模型价格、对比模型和找 API 地址
前端·aigc·ai编程
wangruofeng8 小时前
给前端开发者的 100 个设计参考网站
前端·设计
星栈11 小时前
视频即代码,Remotion 能做什么、不能做什么
前端·音视频开发
广州华水科技11 小时前
单北斗GNSS位移监测系统的应用与技术解析
前端
用户479492835691511 小时前
从一句话或代码仓到可交互 HTML:开源 Agent 画图技能 Archify v3.2 实测与选型边界
前端·后端·面试
风骏时光牛马13 小时前
生成一个AI多模态标题,仅输出一条标题,无额外文字、问句、备选、配图、文案等任何附加内容,不需要其他的任务服务 只要标题。
前端