文件位置（按优先级从高到低）#

编写规范#

• 不超过 200 行 — 超长内容拆分到 .claude/rules/
• 只放 Claude 无法从代码推断的信息
• ✅ 适合放：构建/测试/运行命令、架构约束、编码规范、目录结构说明、重要上下文
• ❌ 不适合放：linter 规则、明显能从代码风格推断的约定

@imports 导入#

CLAUDE.md 支持导入其他文件片段，方便模块化管理：

1
@import .claude/snippets/testing-guidelines.md
2
@import .claude/snippets/deployment-commands.md

官方 9 大技能分类#

设计原则#

1. 渐进式加载（Progressive Disclosure） — 用户通过 /skill-name 调用时才加载，不浪费上下文
2. Gotchas 章节 — 每个 skill 记录该领域的常见坑和易错点
3. 单一职责 — 一个 skill 只做一件事
4. 前置依赖声明 — 明确标注运行该 skill 需要什么环境/权限

Skill 文件结构示例#

1
---
2
name: react-patterns
3
description: React 组件开发规范与最佳实践
4
---
5

6
# React 组件规范
7

8
## 组件结构
9
- 使用函数组件 + Hooks
10
- 自定义 Hook 以 `use` 开头
11

12
## Gotchas
13
- 不要在条件语句中使用 Hooks
14
- useEffect 依赖数组必须完整
15

16
## 依赖
17
- Node >= 18
18
- React >= 18

适合放什么#

• 目录结构详细说明
• 测试编写规范
• lint 配置（无法从代码推断的部分）
• 特定模块的架构约束

与 CLAUDE.md 的分工#

黄金法则： CLAUDE.md 只放必读内容，超过 200 行就往 rules/ 拆分。

支持的事件#

Hook 配置示例#

1
{
2
  "hooks": {
3
    "PostToolUse": {
4
      "command": "npx prettier --write $(claude get-changed-files)",
5
      "blocking": false
6
    }
7
  }
8
}

使用原则#

• ✅ 适合：格式化、lint 修复、日志记录
• ❌ 不适合：需要判断逻辑的任务（交给 Skills）
• ⚠️ blocking: true 会阻塞对话，仅用于关键检查

配置位置#

.claude/agents/ 目录下存放 agent 定义：

1
name: code-reviewer
2
description: 代码审查专家
3
model: claude-sonnet-4-6
4
tools:
5
  - read
6
  - grep
7
  - glob
8
system: |
9
  你是一个严格的代码审查者。关注：
10
  - 正确性 bug
11
  - 安全漏洞
12
  - 性能问题
13
  - 代码可维护性

使用场景#

• 代码审查 — 每个 PR 自动跑一轮审查
• 安全扫描 — 独立安全审查 agent
• 测试生成 — 专职生成测试用例
• 文档检查 — 检查文档是否与代码一致

结合 Worktree 使用#

1
// Workflow 中隔离并行执行
2
agent("审核这段代码", {
3
  isolation: "worktree",   // 隔离的工作副本
4
  agentType: "code-reviewer"
5
})

标准流程#

1
探索（Explore）→ 计划（Plan）→ 编码（Code）

使用场景#

• 跨多个文件的新功能
• 架构重构
• 不确定最佳方案的决策
• 涉及数据迁移或破坏性变更

官方建议： 如果觉得任务”有点复杂”，就进 Plan Mode。宁可多规划，不要直接莽。

/btw 使用示例#

1
你在写一个用户登录功能...
2
/btw 这个项目测试框架用的是 Jest 还是 Vitest？

主任务继续，Claude 会侧边回答后自动回到主任务。

验证手段优先级#

实践中怎么做#

• 写代码时就考虑怎么验证 — 附带测试
• 改完后跑一遍确认 — verify 技能
• 复杂修改用 /code-review --fix — 评审并自动修复
• 创建专门的验证 subagent — 独立的审查视角

官方推荐矩阵#

Effort 级别说明#

官方建议： 默认用 high，遇到棘手问题升到 max。

核心原则#

上下文是有限资源，像内存一样管理它。

管理技巧#

上下文占用量预警#

1
> claude-hud
2
[████████████░░░░] 65%   ← 接近70%可以考虑compact了

核心命令#

定时与循环#

模式切换#

调试与信息#