AI工具

发布日期: 2026-03-07

更新日期: 2026-04-18

文章字数: 9.8k

阅读时长: 37 分

阅读次数:

Claude Code 配置全解析:让 AI 真正懂你的项目

从零开始，手把手教你搭建 Claude Code 的完整配置体系。告别每次重复解释项目背景的痛苦，让 AI 真正成为你团队的”老成员”。

开篇：配置，才是 AI 编程的分水岭

很多人第一次用 Claude Code 的体验是这样的：

“帮我加个登录功能。”

AI 噼里啪啦改了一通，结果用了你项目里根本没有的框架，命名风格跟项目格格不入，还顺手 console.log 满天飞。

你花了 20 分钟纠正它，下次换个话题，它又忘了。

这不是 AI 的问题——是你的配置没做好。

打个比方：你招了一个技术很强的实习生，但他第一天上班，没人告诉他”我们用什么框架””代码怎么命名””哪些文件不能碰”。他只能靠自己猜，猜错了你还得返工。

Claude Code 的配置系统，就是你给这个实习生准备的”入职手册”。 写好了，它秒懂项目背景、自动遵守规范、不再反复犯错。写不好，你就得天天跟在屁股后面收拾烂摊子。

本文会带你从零开始，把 Claude Code 的配置体系摸透。不需要任何前置知识——如果你已经用过 Claude Code，效果会更好；如果还没用过，跟着装也行。

第一部分：理解配置体系的全貌

在动手写配置之前，先花 5 分钟搞清楚整体结构。这就像装修之前先看户型图——方向对了，后面才不会装反。

1.1 两个 .claude 文件夹

Claude Code 实际上有两个 .claude 目录，很多人只注意到一个：

文件夹	位置	谁用	是否提交到 Git
项目级 `.claude/`	你的项目根目录下	整个团队	✅ 是（团队共享）
全局级 `~/.claude/`	你的用户主目录下	只有你自己	❌ 否（个人偏好）

项目级 .claude/ 存放的是”团队共识”：项目用什么技术栈、代码怎么写、哪些命令能跑。你把它提交到 Git，团队每个人 git pull 一下就获得相同的配置。

全局级 ~/.claude/ 存放的是”你的个人习惯”：你喜欢中文回复、你喜欢某种代码风格、你的会话历史。它只属于你，不会跟着项目走。

你的电脑
├── ~/.claude/                          ← 全局，跨所有项目
│   ├── CLAUDE.md                       # 你的个人偏好
│   ├── settings.json                   # 全局权限设置
│   ├── skills/                         # 跨项目的个人 skills
│   ├── agents/                         # 跨项目的个人 agents
│   └── projects/                       # 会话历史 + 自动记忆
│
└── 你的项目/
    ├── CLAUDE.md                       ← 项目说明书（团队共享）
    ├── CLAUDE.local.md                 ← 你的个人覆盖（不进 Git）
    ├── .claudeignore                   ← 告诉 AI 忽略哪些文件
    │
    ├── .claude/                        ← 项目级配置
    │   ├── settings.json               # 团队权限设置
    │   ├── settings.local.json         # 你的个人权限（不进 Git）
    │   ├── rules/                      # 模块化规则
    │   ├── skills/                     # 项目级 skills
    │   ├── agents/                     # 项目级 agents
    │   └── hooks/                      # 自动化脚本
    │
    └── src/
        ├── ...
        └── payment/
            └── CLAUDE.md               ← 模块说明书（仅该目录生效）

1.2 配置的优先级：谁说了算？

同一个设置可能出现在多个地方，Claude Code 按以下优先级加载（从高到低）：

文件夹级 CLAUDE.md  →  项目级 CLAUDE.md  →  全局级 CLAUDE.md
        ↓                   ↓                    ↓
     最具体             团队共识             个人兜底

高优先级覆盖低优先级。 比如全局 CLAUDE.md 写”用英文写注释”，项目级写”用中文写注释”，那么在当前项目中，Claude 会用中文。

同样的优先级规则也适用于 settings.json：项目级覆盖全局，.local 版本覆盖非 .local 版本。

1.3 配置的分类：三层递进

Claude Code 的配置可以分成三层，复杂度递增：

层级	包含什么	解决什么问题	学习曲线
基础层	CLAUDE.md、settings.json、.claudeignore	让 AI 了解项目、控制权限	10 分钟上手
进阶层	rules/、hooks/、skills/、agents/	模块化指令、自动化工作流	需要一些实践经验
记忆层	Auto Memory、自建参考文档	长期记忆、按需加载	用着用着自然就懂了

新手先把基础层搞定，后面按需逐步加入。别一上来就搞全套，会把自己搞晕。

第二部分：核心配置文件详解

这一部分是整篇文章的重中之重。掌握这几个文件，你就能解决 80% 的”AI 不听话”问题。

2.1 CLAUDE.md：AI 的”项目入职手册”

如果说 Claude Code 只让你配一个文件，那一定是 CLAUDE.md。它是整个配置体系中投入产出比最高的一个。

它是什么？

CLAUDE.md 是一个 Markdown 文件，Claude Code 每次启动时第一个读取它。它的内容会被直接注入到 AI 的系统提示词中，在整个对话过程中持续生效。

简单说：你在 CLAUDE.md 里写什么，Claude 就会照做。

你写”提交代码前必须先跑测试”——它每次都会跑测试
你写”不要使用 console.log，用项目里的 logger 模块”——它就不会再乱打印
你写”变量名用驼峰命名”——它就会遵守

三级 CLAUDE.md，各有分工

很多人只知道在项目根目录放一个 CLAUDE.md。其实 Claude Code 设计了三个层级，同时生效、互不冲突：

层级	文件位置	作用范围	适合写什么	谁来维护
全局级	`~/.claude/CLAUDE.md`	所有项目	个人偏好：语言、代码风格、通用原则	你自己
项目级	`项目根目录/CLAUDE.md`	当前项目	技术栈、架构、规范、进度	团队共享，提交到 Git
文件夹级	`子目录/CLAUDE.md`	仅该目录	模块专属约定，如支付模块的特殊规则	模块负责人

举个例子：

全局级写”永远用中文回复我”——所有项目都会用中文
项目级写”本项目使用 Next.js 14 + Prisma”——AI 就知道技术栈了
src/payment/CLAUDE.md 写”支付金额一律用分为单位，不要用元”——只在支付模块下生效

三层叠加，各司其职。

CLAUDE.md 里该写什么？

这是新手最头疼的问题。写太少，AI 还是一脸懵；写太多，AI 反而记不住重点。

✅ 该写的：

内容	示例
构建/测试/检查命令	`npm run test`、`make build`、`npm run lint`
技术栈和架构决策	“Express REST API, Node 20, PostgreSQL via Prisma”
不明显的注意事项	“TypeScript 开启了严格模式，未使用的变量会报错”
命名规范和导入约定	“组件用 PascalCase，工具函数用 camelCase”
目录结构概览	“所有 API handler 在 src/handlers/“
当前进度	“书签 CRUD API 开发中，搜索功能待开发”
禁忌事项	“不要修改数据库迁移文件”、”不要暴露堆栈信息给客户端”

❌ 不该写的：

内容	为什么不该写
Linter/Formatter 能管的事	“缩进用 2 空格” → 这是 ESLint 的工作
完整的 API 文档	太长，用 `@docs/api.md` 引用即可
大段的理论解释	AI 不需要你教它什么是 REST
重复的代码示例	给一个就够了，别贴十遍

黄金法则：CLAUDE.md 控制在 200 行以内。 超过这个长度，AI 的指令遵循度会明显下降。它就像一个入职手册——新人不会读 100 页的文档。

一个可以直接用的模板

# 项目名称

## 常用命令
npm run dev          # 启动开发服务器
npm run test         # 运行测试（Jest）
npm run lint         # 代码检查（ESLint + Prettier）
npm run build        # 生产构建

## 架构
- Express REST API，Node 20
- PostgreSQL，通过 Prisma ORM 操作
- 所有 API handler 在 src/handlers/
- 共享类型定义在 src/types/

## 编码规范
- 每个 handler 用 zod 做请求校验
- 返回值统一格式：{ data, error }
- 不向客户端暴露内部错误详情
- 使用项目内的 logger 模块，不用 console.log

## 注意事项
- 测试用的是真实本地数据库，不是 mock。跑测试前先 `npm run db:test:reset`
- TypeScript 严格模式：不允许未使用的 import
- 不要修改 prisma/migrations/ 下的文件

大约 20 行。简洁、具体、可执行。直接复制到你的项目里，按实际情况改就行。

如何创建 CLAUDE.md？

方法一：用 /init 命令自动生成（推荐新手）

在项目根目录启动 Claude Code，输入 /init。它会自动扫描你的项目，生成一份 CLAUDE.md 初稿。你在这基础上删减修改即可。

💡 提示：项目有一定规模再用 /init 效果更好。如果项目刚初始化，什么文件都没有，它扫不出什么东西。

方法二：用 /memory 编辑全局级

在 Claude Code 会话中输入 /memory，选择”全局 CLAUDE.md”，会用默认编辑器打开 ~/.claude/CLAUDE.md。修改后需要重启 Claude Code 才生效。

方法三：手动创建

直接在项目根目录新建 CLAUDE.md 文件，按上面的模板写。

CLAUDE.local.md：你的个人小抄

有时候你有个人的偏好，但不想让团队其他人也被影响。比如你习惯用另一种测试运行器，或者你想临时让 Claude 输出更详细的注释。

在项目根目录创建 CLAUDE.local.md。Claude Code 会连同主 CLAUDE.md 一起读取它，而且它会被自动加入 .gitignore——你的个人调整永远不会进入团队仓库。

CLAUDE.md           → 团队共享，提交到 Git
CLAUDE.local.md     → 你的个人覆盖，不进 Git

2.2 settings.json：权限的”门禁系统”

CLAUDE.md 告诉 AI “做什么”，settings.json 告诉 AI “能做什么、不能做什么”。

它是 Claude Code 的权限门禁系统：哪些操作可以直接执行、哪些需要你确认、哪些完全禁止。

三个层级的 settings.json

跟 CLAUDE.md 类似，settings.json 也有三个层级：

层级	文件位置	作用范围	提交到 Git？
全局	`~/.claude/settings.json`	所有项目	❌
项目（团队）	`项目/.claude/settings.json`	当前项目	✅
项目（个人）	`项目/.claude/settings.local.json`	当前项目	❌（自动 gitignore）

优先级：个人 > 项目团队 > 全局。

权限配置详解

settings.json 的核心就是 permissions 字段，它有两个列表：

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "allow": [
      "Read",
      "Write",
      "Edit",
      "Bash(npm run *)",
      "Bash(git status)",
      "Bash(git diff *)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(curl *)",
      "Read(./.env)",
      "Read(./.env.*)"
    ]
  }
}

allow 列表——免通行证

写在里面的操作，Claude Code 执行时不会问你确认，直接放行。

常见的 allow 配置：

"allow": [
  "Read",                  // 允许读文件
  "Write",                 // 允许写文件
  "Edit",                  // 允许编辑文件
  "Bash(npm run *)",       // 允许跑 npm 脚本
  "Bash(make *)",          // 允许跑 make 命令
  "Bash(git status)",      // 允许查看 git 状态
  "Bash(git diff *)",      // 允许查看 diff
  "Bash(git log *)",       // 允许查看日志
  "Glob",                  // 允许搜索文件
  "Grep"                   // 允许搜索内容
]

💡 Bash(npm run *) 中的 * 是通配符，匹配任意字符。所以 npm run test、npm run build、npm run dev 都会被放行，但 npm publish 不会——它不是 npm run 开头。

deny 列表——黑名单

写在里面的操作，无论什么情况都不允许执行，即使你手动确认也不行。

一个合理的 deny 列表应该包含：

"deny": [
  "Bash(rm -rf *)",            // 禁止危险删除
  "Bash(git push --force *)",  // 禁止强制推送
  "Bash(curl *)",              // 禁止直接网络请求
  "Bash(wget *)",              // 禁止下载
  "Read(./.env)",              // 禁止读取环境变量文件
  "Read(./.env.*)",            // 禁止读取所有 .env 变体
  "Read(./secrets/**)"         // 禁止读取 secrets 目录
]

不在任何列表中的操作——灰色地带

如果某个操作既不在 allow 也不在 deny 中，Claude Code 会在执行前先问你。这就是”灰色地带”——安全网。

AI: 我要执行 `pip install requests`，可以吗？
你: [确认] / [拒绝]

这个中间地带是有意设计的——你不需要提前想到所有可能的命令。

其他常用配置项

除了权限，settings.json 还能配置这些：

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": { ... },

  // 默认使用的模型
  "model": "sonnet",

  // 上下文自动压缩阈值（0-100，百分比）
  // 上下文占用超过这个比例时自动压缩
  "autoCompactThreshold": 80,

  // 环境变量（在 Claude Code 会话中可用）
  "env": {
    "NODE_ENV": "development",
    "API_BASE_URL": "http://localhost:3000"
  }
}

💡 $schema 那行很重要：加上它，VS Code 或 Cursor 会自动提供配置项的自动补全和校验，能省掉很多拼写错误。

新手建议

刚入门时，建议保持最保守的权限配置：

{
  "permissions": {
    "deny": [
      "Bash(rm -rf *)",
      "Read(./.env)"
    ]
  }
}

只配 deny，不配 allow。这样 Claude Code 每次执行操作都会问你确认。等你用熟了，再逐步把信任的操作加入 allow 列表。

2.3 .claudeignore：给 AI 戴上”眼罩”

你的项目里有很多文件是 AI 根本不需要看的：node_modules/ 有几万个文件、dist/ 是构建产物、.env 里是密钥。让 AI 扫描这些文件，只会浪费 token、拖慢速度，甚至可能泄露敏感信息。

.claudeignore 就像给 AI 戴上一个”眼罩”——告诉它哪些东西不要看。

语法跟 .gitignore 一样

如果你用过 .gitignore，.claudeignore 的语法完全一样：

# 依赖包目录（太大了，不需要看）
node_modules/

# 构建产物
dist/
build/
.next/

# 日志文件
*.log

# 敏感文件
.env
.env.*
secrets/

# 数据库文件
*.db
*.sqlite

# 系统文件
.DS_Store
Thumbs.db

# IDE 配置
.vscode/
.idea/

为什么这很重要？

省 token：node_modules/ 随便就几万文件，让 AI 扫描纯属浪费
防泄露：.env 里可能有数据库密码、API Key，不能让 AI 读到
提速度：排除的文件越多，AI 搜索越快
减噪音：构建产物、日志文件对 AI 来说是垃圾信息

⚠️ 红线：.env、密钥文件、证书文件一定要加到 .claudeignore 里。这是安全底线，不是可选项。

2.4 常用斜杠命令速查

配置好之后，日常使用中这几个命令你会天天用到：

命令	作用	什么时候用
`/init`	自动生成 CLAUDE.md	进入新项目的第一件事
`/memory`	查看/编辑记忆和 CLAUDE.md	管理项目说明和自动记忆
`/context`	查看上下文使用情况	感觉 AI “变笨”了，看看上下文是不是满了
`/compact`	压缩上下文	对话太长，AI 开始”遗忘”时
`/clear`	清空对话，重新开始	一个任务完成，开始全新任务
`/model`	切换模型	需要更强/更快的模型时
`/rewind`	回滚修改	AI 改坏了代码时的”后悔药”
`/review`	代码审查	完成开发后检查质量
`/help`	查看所有命令	忘了有什么命令时

💡 /compact vs /clear：

/compact = 整理桌面，把前面的对话压缩成摘要，还能继续当前任务

/clear = 把桌面清空，等于重新开始

经验法则：看到上下文使用超过 60%，就 /compact 一下。一个独立任务完成后，用 /clear 开始新的。

第三部分：进阶配置系统

基础配置搞定之后，你会发现有些需求用 CLAUDE.md 和 settings.json 解决不了——

CLAUDE.md 越来越长，300 行了，根本维护不动 → 需要 rules/
想让 AI 改完文件自动跑格式化，而不是靠它”记得” → 需要 hooks/
有一整套安全审查流程，想打包给 AI 用 → 需要 skills/
想让一个”专家角色”在隔离环境里做代码审查 → 需要 agents/

这一部分介绍的四个机制，是 Claude Code 从”工具”进化为”团队成员”的关键。

3.1 rules/ 文件夹：模块化指令

问题：CLAUDE.md 越来越臃肿

项目刚起步时，一个 CLAUDE.md 就够了。但随着团队壮大，你会发现：

前端、后端、测试各有不同的规范
API 约定、安全规则、性能要求各不相同
一个人在维护一份 300 行的 CLAUDE.md，谁都不敢改

解决方案：把指令拆分成多个文件，放在 .claude/rules/ 目录下。

.claude/rules/
├── code-style.md        # 代码风格
├── testing.md           # 测试规范
├── api-conventions.md   # API 约定
└── security.md          # 安全规则

Claude Code 会自动加载 rules/ 下的每个 Markdown 文件，跟 CLAUDE.md 一起生效。每个文件保持聚焦、易于维护。负责 API 规范的团队成员改 api-conventions.md，负责测试的人改 testing.md，互不干扰。

杀手级功能：路径作用域

rules/ 真正的威力在于——你可以让一个规则只在特定目录下生效。

做法很简单，在规则文件开头加一段 YAML frontmatter：

---
paths:
  - "src/api/**/*.ts"
  - "src/handlers/**/*.ts"
---

# API 设计规范

- 所有 handler 返回 { data, error } 格式
- 用 zod 做请求体校验
- 永远不向客户端暴露内部错误详情
- 分页参数统一用 page + pageSize

效果：Claude Code 在编辑 src/api/ 或 src/handlers/ 下的文件时，才会加载这个规则。编辑 React 组件时，不会加载——节省 token，也避免不相关的规则干扰 AI。

路径匹配的语法：

"src/api/**/*.ts"     → src/api/ 下所有层级的 .ts 文件
"*.test.ts"           → 所有 .test.ts 文件
"docs/**"             → docs/ 下所有文件

没有 paths 字段的规则文件会在每次会话中无条件加载——适合那些全局通用的规则。

什么时候该用 rules/？

场景	建议
CLAUDE.md 超过 100 行了	按关注点拆分到 rules/
不同目录有不同规范	用路径作用域
团队成员各自维护各自领域	拆成独立文件，分工维护
项目还小，CLAUDE.md 只有 30 行	先不用 rules/，别过度设计

3.2 hooks/ 系统：确定性行为控制

CLAUDE.md 的局限：它只是”建议”

CLAUDE.md 里写的规则，AI 大多数时候会遵守，但不是每次。

你写”改完文件后跑 prettier 格式化”——AI 有时会忘
你写”不要执行 rm -rf“——万一 AI 理解错了呢？
你写”完成之前必须通过测试”——AI 可能会跳过测试直接宣布完成

语言模型就是这样——它尽力遵守，但你没法 100% 保证。

hooks 让你的规则从”建议”变成”强制执行”。

hooks 是什么？

hooks 是事件处理器——在 Claude Code 工作流的特定节点，自动执行你写的 shell 脚本。你的脚本每次都会运行，没有例外。

这就像工厂流水线上的质检站：产品（AI 的操作）经过每个站点时，质检员（你的脚本）自动检查。不合格？直接打回。

支持的事件类型

事件	触发时机	典型用途
PreToolUse	工具执行前	安全检查：阻止危险命令
PostToolUse	工具执行后	自动格式化、自动 lint
Stop	AI 宣布完成时	质量关卡：测试必须通过
UserPromptSubmit	用户按回车时	输入验证、敏感词过滤
Notification	需要通知时	桌面弹窗提醒
SessionStart	会话开始	注入上下文
SessionEnd	会话结束	清理资源

退出码：脚本如何”告诉” Claude Code 该怎么做

这是 hooks 最关键的机制。你的脚本执行完后，通过退出码来告诉 Claude Code 下一步怎么做：

退出码	含义	Claude Code 的反应
0	成功	继续正常执行
1	错误，但不阻止	记录日志，继续执行（不阻止！）
2	严重问题，必须阻止	停止执行，把 stderr 的内容发给 AI 让它自我纠正

⚠️ 新手最常犯的错误：在安全 hook 里用退出码 1，以为能阻止危险操作。实际上退出码 1 不会阻止执行！必须用退出码 2 才能真正阻止。

配置示例

所有 hooks 配置在 settings.json 的 hooks 字段下：

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit|MultiEdit",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write 2>/dev/null"
          }
        ]
      }
    ],
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/bash-firewall.sh"
          }
        ]
      }
    ]
  }
}

来拆解一下这段配置：

第一个 hook（PostToolUse）：

触发时机：Write、Edit 或 MultiEdit 工具执行之后
做什么：用 prettier 自动格式化被修改的文件
效果：Claude Code 每次修改文件后，代码自动格式化

第二个 hook（PreToolUse）：

触发时机：Bash 工具执行之前
做什么：运行 bash-firewall.sh 脚本，检查命令是否安全
效果：危险命令被拦截

💡 matcher 字段是正则表达式，用来筛选哪些工具触发这个 hook。"Write|Edit|MultiEdit" 匹配文件修改操作，"Bash" 匹配终端命令。不写 matcher 则匹配所有工具。

实战：写一个 bash 防火墙

.claude/hooks/bash-firewall.sh 的内容：

#!/bin/bash

# 从 stdin 读取 JSON 输入，提取要执行的命令
INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')

# 检查危险模式
if echo "$COMMAND" | grep -qE 'rm -rf /|git push --force main|DROP TABLE'; then
  echo "⛔ 危险命令被拦截: $COMMAND" >&2
  exit 2  # 退出码 2 = 阻止执行！
fi

exit 0  # 退出码 0 = 放行

当 Claude Code 要执行 rm -rf / 时：

PreToolUse hook 触发
脚本检查到危险模式
以退出码 2 退出，stderr 输出拦截信息
Claude Code 停止执行，把拦截信息发给 AI
AI 收到”危险命令被拦截”的反馈，换个安全的方式

实战：测试必须通过才能完成

#!/bin/bash
# .claude/hooks/enforce-tests.sh

# 避免无限循环：检查 stop_hook_active 标志
INPUT=$(cat)
if echo "$INPUT" | jq -e '.stop_hook_active' > /dev/null 2>&1; then
  exit 0  # 第二次触发了，放行，让 AI 停下来
fi

# 跑测试
npm test 2>&1
if [ $? -ne 0 ]; then
  echo "❌ 测试未通过，请修复后再完成" >&2
  exit 2  # 阻止 AI 宣布完成
fi

exit 0

⚠️ 注意 stop_hook_active 标志：如果不检查它，会出现无限循环——hook 阻止 AI → AI 重试 → hook 又阻止 → AI 又重试……检查这个标志，第二次触发时放行，让 AI 停下来。

hooks 的几个坑

不会热重载：修改了 hooks 配置，需要重启 Claude Code 才生效
PostToolUse 无法撤销：工具已经执行了，PostToolUse 只能”事后处理”。要阻止操作，用 PreToolUse
子 agent 也会触发：hooks 对子 agent 的操作也会递归触发
没有沙箱：hooks 脚本以你的完整用户权限运行。务必引号包裹变量、校验 JSON 输入、脚本引用用绝对路径

3.3 skills/ 文件夹：可复用的工作流

什么是 skills？

想象你经常需要做安全审查。每次你都要告诉 AI：”检查 SQL 注入、XSS、暴露的密钥、不安全的配置……” 说了十遍之后，你烦了。

Skills 就是你把这些重复的工作流”打包”起来，让 AI 在合适的时候自动调用。

你: "帮我审查一下这个 PR 的安全问题"

AI 识别到匹配 security-review skill → 自动调用 → 按你定义好的流程审查

skill 的目录结构

每个 skill 是一个独立的子目录，包含一个 SKILL.md 文件：

.claude/skills/
├── security-review/
│   ├── SKILL.md              # 触发条件和指令
│   └── DETAILED_GUIDE.md     # 详细的安全标准文档
└── deploy/
    ├── SKILL.md              # 部署流程
    └── templates/
        └── release-notes.md  # 发布说明模板

跟 commands（单个文件）不同，skills 可以打包多个支持文件。这是它最大的优势。

SKILL.md 怎么写？

---
name: security-review
description: 全面的安全审查。在审查代码漏洞、部署前检查、
  或用户提到安全相关话题时使用。
allowed-tools: Read, Grep, Glob
---

对代码库进行安全漏洞分析：

1. SQL 注入和 XSS 风险
2. 暴露的凭据或密钥
3. 不安全的配置
4. 认证和授权的漏洞

输出带严重等级的发现报告，以及具体的修复建议。
参考 @DETAILED_GUIDE.md 了解我们的安全标准。

关键字段解释：

字段	作用	示例
`name`	skill 名称	`security-review`
`description`	什么时候触发这个 skill	“在审查安全漏洞时使用”
`allowed-tools`	限制 skill 能使用的工具	`Read, Grep, Glob`（只读，不写文件）

💡 @DETAILED_GUIDE.md 中的 @ 符号会引入同目录下的文件。skill 执行时，这个文件的内容也会被加载。这就是”打包”的含义——指令和支持文件一起。

两种调用方式

自动调用：你说”审查一下安全问题”，Claude 读取 description，发现匹配，自动调用 skill
手动调用：在对话框输入 /security-review，直接触发

个人 skills vs 项目 skills

位置	作用范围	示例
`~/.claude/skills/`	跨所有项目	你个人的代码审查流程
`项目/.claude/skills/`	仅当前项目	项目特定的部署流程

3.4 agents/ 文件夹：专业化的子角色

什么时候需要 agents？

有些任务足够复杂，值得用一个独立角色来处理——它有自己的系统提示词、自己的工具限制、甚至可以用不同的模型。

比如代码审查：你不想让主会话被几千行中间探索过程淹没。你可以定义一个 code-reviewer agent，让它在自己的”小房间”里做审查，完成后只把结论告诉你。

agent 的配置格式

每个 agent 是一个 Markdown 文件，放在 .claude/agents/ 下：

.claude/agents/
├── code-reviewer.md     # 代码审查专家
└── security-auditor.md  # 安全审计专家

code-reviewer.md 的内容：

---
name: code-reviewer
description: 专业代码审查员。在审查 PR、检查 bug、
  或合并前验证实现时主动使用。
model: sonnet
tools: Read, Grep, Glob
---

你是一位资深代码审查员，专注于正确性和可维护性。

审查代码时：
- 标记 bug，不只是风格问题
- 给出具体的修复建议，不说空话
- 检查边界情况和错误处理的遗漏
- 只在大规模场景下才提性能问题

关键字段：

字段	作用	说明
`name`	agent 名称	Claude 根据这个识别
`description`	什么时候调用	类似 skill 的 description
`model`	使用的模型	`haiku`（便宜快速）、`sonnet`（均衡）、`opus`（最强）
`tools`	允许使用的工具	限制 agent 的能力范围

为什么要限制工具？

安全审计员只需要读代码，不需要写代码。把 tools 限制为 Read, Grep, Glob，就确保它不会意外修改任何文件。

这种限制是有意为之的——不同的角色，不同的权限。就像公司里，审计部门有查看权限，但没有操作权限。

model 字段的意义

model 字段让你可以为不同任务选择合适的模型：

模型	适合做什么	成本
haiku	只读的探索任务、简单的搜索	最便宜
sonnet	代码审查、一般开发任务	中等
opus	复杂架构设计、关键决策	最贵

把简单任务交给 haiku，复杂任务交给 opus，既省钱又高效。

个人 agents

跟 skills 一样，agents 也分项目级和全局级：

位置	作用范围
`~/.claude/agents/`	跨所有项目
`项目/.claude/agents/`	仅当前项目

3.5 Auto Memory：AI 的”自动笔记本”

CLAUDE.md vs Auto Memory

	CLAUDE.md	Auto Memory
谁写的	你手动写	AI 自己记
加载方式	每次会话全量加载	先读索引，按需加载
优先级	高	中
内容	项目规范、技术栈	你的偏好、踩过的坑、项目决策

如果说 CLAUDE.md 是你主动立下的规矩，Auto Memory 就是 AI 在干活过程中默默记下的笔记。你没写进 CLAUDE.md 的习惯、反馈、项目踩坑，AI 会自动记录。

如何启用？

在 Claude Code 会话中输入：

/memory

在弹出的菜单中选择”启用 Auto Memory”。启用后，AI 会自动开始记录。

记录的内容分四类

类型	含义	举例
`user`	关于你	“用户不喜欢深色 UI”、”用户偏好函数式编程”
`feedback`	你给过的反馈	“不要这样做”、”对，就这样”
`project`	项目相关	“决定用 Redis 做缓存”、”数据库迁移脚本有问题”
`reference`	外部资源索引	“设计文档在 docs/design.md”

使用手感

它只在当前项目生效，换项目需重新积累
不会每次把所有记忆全加载——只读一份 memory.md 索引，遇到具体问题才去读对应的子文件，占 token 很少
随时按 Ctrl+O 查看被调用过的记忆内容（vscode中使用可能快捷键被占用）
记错了？直接跟 AI 说”忘掉刚才说的不喜欢深色主题”，它会自己删掉

💡 本质认知：agent 的所有”记忆”，本质上都是在合适的时候向大模型注入压缩过的上下文。CLAUDE.md 和 Auto Memory 只是组织方式不同。

3.6 自建参考文档：渐进式披露

有些信息不适合全部塞进 CLAUDE.md（太长、太专门），但 AI 需要的时候必须能查到。

解决方案：创建独立的参考文档，在 CLAUDE.md 中用指引告诉 AI 什么时候去读。

举个例子，假设你做一个产品，需要：

品牌视觉规范 → docs/brand-visual.md
产品文案风格 → docs/copywriting-style.md
API 约定 → docs/api-conventions.md

在 CLAUDE.md 中加上指引：

## 外部参考文档

- 修改前端视觉、调颜色、调间距时 → 必读 `docs/brand-visual.md`
- 写产品文案、按钮文字、提示语时 → 必读 `docs/copywriting-style.md`
- 写 API、定义返回格式时 → 必读 `docs/api-conventions.md`

效果：AI 只在”需要的时候”才去读完整文档。既保证了准确性，又不浪费 token。

这就是”渐进式披露”——平时不加载，需要时才加载。

三层记忆体系总览

到这里，Claude Code 的三层记忆体系就完整了：

层	位置	优先级	加载方式	谁在维护
第一层	CLAUDE.md（三级）	高	会话启动全量加载	你手动维护
第二层	Auto Memory	中	先读索引、按需读子文件	AI 自己写、你校对
第三层	参考文档	按需	遇到对应任务才读	你手动维护

第四部分：配置最佳实践

理论讲完了，这一部分聊点实际的：新手怎么一步步搭起来？常见的坑有哪些？团队协作怎么分工？

4.1 新手入门：5 步走

如果你从零开始，按这个顺序来，每一步都有明确目标：

第 1 步：用 /init 生成 CLAUDE.md

在项目根目录启动 Claude Code，输入 /init。它会自动扫描你的项目结构、技术栈，生成一份 CLAUDE.md 初稿。

拿到初稿后，精简到核心内容：常用命令、架构决策、编码规范、注意事项。控制在 200 行以内。

第 2 步：配置 settings.json 的基础权限

创建 .claude/settings.json，至少做两件事：

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "allow": [
      "Read",
      "Write",
      "Edit",
      "Bash(npm run *)",
      "Bash(git status)",
      "Bash(git diff *)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Read(./.env)"
    ]
  }
}

允许常用操作，禁止危险操作。其余的让它问你。

第 3 步：添加 .claudeignore

node_modules/
dist/
build/
.next/
*.log
.env
.env.*
.DS_Store

排除不需要的文件，省 token、防泄露。

第 4 步：项目增长后，拆分 rules/

当 CLAUDE.md 超过 100 行，按关注点拆分到 .claude/rules/。先拆最臃肿的部分，不用一次拆完。

第 5 步：添加全局 ~/.claude/CLAUDE.md

写下你的个人偏好，下面是我个人使用的一个例子：

# 全局个人偏好

- **当前日期**：2026-07-06

## 语言与沟通
- 默认使用中文回复，用户要求英文时除外。
- 代码、注释、文档、提交信息必须使用英文。
- 严格遵循 Go 语言习惯（idiomatic Go），优先参考 Effective Go 和 Go Proverbs。

## Go 语言核心原则
- 优先使用标准库（stdlib），仅在必要时引入第三方库。
- 错误处理必须显式：不要忽略错误，使用 `errors` 包或自定义 error 类型。
- 并发安全：优先使用 channels 和 context 管理 goroutine。
- 性能优先：避免不必要的分配，合理使用 sync 包和 pooling。
- 代码风格：简洁、可读、明确（clear is better than clever）。
- 命名规范：使用驼峰（exported）/小写（unexported），接口名以 "er" 结尾（如 Reader）。

## 项目结构与规范
- 采用标准 Go 项目布局：
  - `cmd/`：可执行入口
  - `internal/`：私有代码
  - `pkg/`：可复用包（谨慎使用）
  - `api/`、`config/`、`pkg/` 等按需组织
- 模块管理：始终使用 Go Modules（go.mod），保持 go version 最新稳定版。
- 测试：优先 table-driven tests，使用 `testing` 和 `testify`（如果项目已引入）。

## 工具与命令
- Build：`go build ./...`
- Test：`go test ./... -race -count=1`
- Lint：`golangci-lint run`
- Format：`go fmt ./...` 或 `gofumpt`
- Vet：`go vet ./...`
- 依赖：`go mod tidy && go mod verify`

## Git 与提交
- 使用 Conventional Commits：`feat: `、`fix: `、`refactor: ` 等
- 提交信息清晰、原子化。

## 最佳实践
- 始终处理 context.Context 以支持取消和超时。
- 避免全局变量，优先依赖注入。
- 接口设计小而专一。
- 生产就绪：添加健康检查、优雅关闭、结构化日志（推荐 zap 或 slog）。
- 安全性：验证输入、避免 sql 注入、使用最新依赖。

## 关于我
- 我是一名 Go 后端工程师，专注于高性能、并发系统、微服务和 CLI 工具。
- 偏好干净架构（Clean Architecture）和领域驱动设计（DDD）思想。
- 重视可测试性、可观测性和可维护性。

这 5 步做完，你就拥有了一套能覆盖 95% 项目的配置。剩下的 skills、agents、hooks，等你有具体的重复工作流时再加。

4.2 配置避坑指南

坑 1：CLAUDE.md 写成长篇小说

症状：CLAUDE.md 超过 300 行，里面有大段的理论解释、完整的 API 文档、重复的代码示例。

后果：AI 的指令遵循度下降，上下文被大量消耗，真正重要的指令被淹没。

解决：

控制在 200 行以内
只写”做什么”，不写”为什么”
详细文档用 @docs/xxx.md 引用

坑 2：安全 hook 用退出码 1

症状：写了 PreToolUse hook 阻止危险命令，但用 exit 1。

后果：危险命令照样执行。退出码 1 只记录日志，不阻止执行。

解决：安全相关的 hook 必须用 exit 2。

坑 3：权限设置过于宽松

症状：allow 列表里有 Bash(*)，等于什么命令都能跑。

后果：AI 可能执行你没想到的危险操作，而且不会问你。

解决：

allow 列表只放你确定安全的操作
不确定的就放灰色地带，让它问你
deny 列表至少包含 rm -rf、.env 读取

坑 4：忘记 .claudeignore

症状：没有 .claudeignore，AI 扫描了整个 node_modules。

后果：上下文被垃圾信息填满，token 消耗暴增，还可能读到敏感文件。

解决：项目第一天就创建 .claudeignore。

坑 5：Stop hook 无限循环

症状：Stop hook 跑测试，测试失败就阻止 AI 完成。但 AI 重试时又触发 hook，又阻止……

后果：无限循环，Claude Code 卡死。

解决：在 hook 脚本中检查 stop_hook_active 标志，第二次触发时放行。

4.3 团队协作建议

什么提交到 Git？

文件	是否提交	原因
`CLAUDE.md`	✅ 提交	团队共识
`.claude/settings.json`	✅ 提交	团队权限
`.claude/rules/`	✅ 提交	团队规范
`.claude/skills/`	✅ 提交	团队工作流
`.claude/agents/`	✅ 提交	团队角色
`.claude/hooks/`	⚠️ 看情况	如果脚本包含本地路径，不提交
`.claudeignore`	✅ 提交	团队共识
`CLAUDE.local.md`	❌ 不提交	个人偏好（自动 gitignore）
`.claude/settings.local.json`	❌ 不提交	个人权限（自动 gitignore）

分工维护

大型项目中，一个人维护所有配置文件是不现实的。建议按领域分工：

前端负责人：维护 rules/frontend.md
后端负责人：维护 rules/backend.md、rules/api-conventions.md
测试负责人：维护 rules/testing.md
安全负责人：维护 hooks/bash-firewall.sh、skills/security-review/

每个文件有明确的 owner，改的时候不会冲突。

4.4 性能优化建议

省 token

保持 CLAUDE.md 简洁：200 行以内
用好 .claudeignore：排除大文件和无关文件
路径作用域 rules/：只在需要时加载规则
渐进式披露参考文档：不在 CLAUDE.md 里贴大段内容
定期 /compact：上下文超过 60% 就压缩

提速度

精确的 CLAUDE.md：AI 不需要花时间”探索”项目
@ 引用文件：直接告诉 AI 看哪个文件，而不是让它自己找
限制 agents/skills 的工具：只给必要的工具，减少决策空间
用对模型：简单任务用 haiku，复杂任务用 opus

第五部分：完整配置示例

理论讲完了，给你两套前后端可以直接抄的配置模板。基本内容上面都已经提到了，只不过是对上面内容进行总结打包，下面是具体配置项目结构，有需要可以关注我后台回复cc获取。

此外我还打包了github上star比较多的常用的配置。

附录

A. 文件位置速查表

~/.claude/                        ← 全局配置
├── CLAUDE.md                     # 全局指令（所有项目生效）
├── settings.json                 # 全局权限设置
├── skills/                       # 个人 skills（跨项目）
├── agents/                       # 个人 agents（跨项目）
└── projects/                     # 会话历史 + 自动记忆

项目根目录/
├── CLAUDE.md                     # 项目指令（团队共享）
├── CLAUDE.local.md               # 个人覆盖（不进 Git）
├── .claudeignore                 # 忽略文件列表
│
└── .claude/                      ← 项目级配置
    ├── settings.json             # 团队权限设置
    ├── settings.local.json       # 个人权限（不进 Git）
    ├── rules/                    # 模块化规则
    ├── skills/                   # 项目级 skills
    ├── agents/                   # 项目级 agents
    └── hooks/                    # hook 脚本

B. 常用命令速查表

命令	作用	快捷键
`/help`	查看所有命令	-
`/init`	自动生成 CLAUDE.md	-
`/memory`	管理记忆和 CLAUDE.md	`Ctrl+O` 查看记忆
`/context`	查看上下文使用情况	-
`/compact`	压缩上下文	-
`/clear`	清空对话	-
`/model`	切换模型	-
`/rewind`	回滚修改	`Esc × 2`
`/review`	代码审查	-
`/cost`	查看费用	-
`/resume`	恢复历史会话	-
`/plan`	进入规划模式	`Shift+Tab` 切换

快捷键：

快捷键	作用
`Enter`	发送消息 / 确认
`Shift + Enter`	也是发送（不是换行！）
`Option/Alt + Enter`	换行（不发送）
`Ctrl + C`	中断当前操作
`Esc`	取消生成
`Esc × 2`	回滚界面
`Shift + Tab`	切换模式
`Ctrl + B`	后台运行

C. YAML Frontmatter 速查

rules/ 文件：

---
paths:
  - "src/api/**/*.ts"
  - "src/handlers/**/*.ts"
---

skills/SKILL.md：

---
name: security-review
description: 安全审查，在用户提到安全时使用
allowed-tools: Read, Grep, Glob
---

agents/ 文件：

---
name: code-reviewer
description: 代码审查专家
model: sonnet
tools: Read, Grep, Glob
---

D. settings.json 配置项速查

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",

  // 权限控制
  "permissions": {
    "allow": ["Read", "Write", "Bash(npm run *)"],
    "deny": ["Bash(rm -rf *)", "Read(./.env)"]
  },

  // 默认模型
  "model": "sonnet",

  // 自动压缩阈值
  "autoCompactThreshold": 80,

  // 环境变量
  "env": {
    "NODE_ENV": "development"
  },

  // Hooks
  "hooks": {
    "PreToolUse": [...],
    "PostToolUse": [...],
    "Stop": [...]
  }
}

结语

回到文章开头的问题：怎么让 AI 真正”懂”你的项目？

答案就是配置。

CLAUDE.md 告诉 AI 项目是什么、怎么做
settings.json 控制 AI 能做什么、不能做什么
rules/ 把规则拆分成模块，按需加载
hooks/ 让规则从”建议”变成”强制执行”
skills/ 打包重复的工作流
agents/ 定义专业的子角色
Auto Memory 让 AI 自己记住你的偏好

配置不是一蹴而就的。从小处开始——先写好 CLAUDE.md，配好基本权限。用一段时间后，你会发现”这里可以自动化”、”那个规则应该拆出来”。逐步迭代，配置会越来越完善。

好的配置，就像好的基础设施——一旦搭好，每天都会给你带来回报。

现在，打开你的项目，开始配置吧。

参考资料

本文内容参考了以下资料，感谢各位大佬的分享：

Claude Code 官方文档
- https://code.claude.com/docs/zh-CN/how-claude-code-works
尚硅谷 AI Coding 教程
- 零基础实战教程，涵盖 Claude Code 深度使用与进阶技巧
- https://www.bilibili.com/video/BV1RPET6tEp2/?share_source=copy_web&vd_source=1c112747a1b05592cc7e39e91a3d66aa
@akshay_pachaar的twitter推文
- 原文：https://x.com/akshay_pachaar/status/2035341800739877091
- 详细解析 CLAUDE.md、自定义命令、skills、agents 和 permissions 的配置方法

ZhangZhengYu

https://welcomemonth.github.io/2026/03/07/claude-code/claude%20code/

本博客所有文章除特別声明外，均采用 CC BY 4.0 许可协议。转载请注明来源 ZhangZhengYu !

vibcoding Claude Code

Eino框架

2026-03-18 AI工具

eino vibcoding langchain

Go语言圣经的练习题

夯实基础。

2025-06-07 Golang