ClaudeCode

参考链接：Claude Code 项目目录结构 | 菜鸟教程

避免权限请求

使用ClaudeCode时，会发现它总是请求各种命令的权限，非常烦人。可以通过以下方式让他获取所有工具的权限

1
claude --allow-dangerously-skip-permissions

基本结构

claudecode有多种概念，比如skill、subagents…他们基本上都作为独立的文件存在于对应的目录，Claude Code 会在特定位置查找对应的配置文件

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
your-project/
├── CLAUDE.md                    ← 团队共享指令，提交到 git
├── CLAUDE.local.md              ← 个人覆盖，被 git 忽略
└── .claude/
    ├── settings.json            ← 权限 + 配置，提交到 git
    ├── settings.local.json      ← 个人权限，被 git 忽略
    ├── commands/                ← 自定义斜杠命令
    │   ├── review.md            →  /project:review
    │   ├── fix-issue.md         →  /project:fix-issue
    │   └── deploy.md            →  /project:deploy
    ├── rules/                   ← 模块化指令文件（全局生效）
    │   ├── code-style.md
    │   ├── testing.md
    │   └── api-conventions.md
    ├── skills/                  ← 自动调用的工作流
    │   ├── security-review/
    │   │   └── SKILL.md
    │   └── deploy/
    │       └── SKILL.md
    └── agents/                  ← 子代理角色定义
        ├── code-reviewer.md
        └── security-auditor.md

启动 Claude Code 时，它会按以下顺序加载配置：

  1. 读取规则 (~/.claude/rules/*.md) - 这些规则适用于所有交互
  2. 加载钩子 (~/.claude/settings.json) - 在特定事件时运行
  3. 注册代理 (~/.claude/agents/*.md) - 可供委派使用
  4. 索引技能 (~/.claude/skills/*) - 在调用时准备就绪
  5. 启用命令 (~/.claude/commands/*.md) - 可通过斜杠语法使用
  6. 连接 MCPs (~/.claude.json) - 链接到外部服务

CLAUDE.md

CLAUDE.md 是一个放在项目根目录的 Markdown 文件，Claude Code 在每次会话开始时都会自动读取。

CLAUDE.md 会成为 Claude 系统提示的一部分，使每次对话都能预先加载项目上下文，不再需要重复解释基本信息。

一份好的 CLAUDE.md 应该包含以下内容：

  • 项目概述
  • 常用命令
  • 项目目录说明
  • 编码规范
  • 架构约束与禁止事项
  • 开发环境说明

以下是一份典型的 CLAUDE.md 结构示例：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
# 项目名称

## 项目概述
简述这个项目的目的和功能。

## 开发环境

- Node.js：需要 v20 或以上版本（通过 `.nvmrc` 指定）
- 包管理器：pnpm（禁止使用 npm 或 yarn 安装依赖）
- 本地数据库：Docker Compose 启动（`docker compose up -d`）
- 端口：前端 3000，API 3001，数据库 5432

### 环境变量
参考 `.env.example` 文件配置本地环境变量，复制为 `.env.local` 后填入实际值。
必填项：`DATABASE_URL`、`NEXTAUTH_SECRET`、`NEXTAUTH_URL`

## 目录结构
- `src/components/` - React 组件
- `src/api/`        - API 层
- `tests/`          - 测试文件

## 常用命令

### 安装依赖
```bash
npm ci                    # 安装依赖（CI 环境使用，严格按 lock 文件安装）
```

### 开发
```bash
npm run dev               # 启动开发服务器（端口 3000）
npm run build             # 构建生产版本
npm run preview           # 预览生产构建
```

### 测试
```bash
npm test                  # 运行所有测试
npm test -- --watch       # 监听模式
npm test -- --coverage    # 生成覆盖率报告
```

## 编码规范

### 通用
- 文件名使用 kebab-case（如 `user-profile.ts`），类名使用 PascalCase
- 优先使用具名导出（named export），避免默认导出（default export）
- 异步函数一律使用 async/await，禁止使用 .then() 链式调用

### 组件规范
- 组件文件与其测试文件放在同一目录（如 `Button.tsx` 和 `Button.test.tsx`）
- Props 类型使用 interface 定义，命名格式为 `${组件名}Props`
- 不要将业务逻辑写在组件中，提取为自定义 Hook 或 Service

### 错误处理
- API 路由使用统一的错误响应格式：`{ error: string, code: string }`
- 客户端错误通过 Error Boundary 捕获，不要在每个组件里单独 try/catch

## 架构约束

- 所有数据库查询必须通过 `src/lib/db/queries/` 中的函数执行，不要在路由或组件中直接写 SQL
- 状态管理使用 Zustand，不要引入 Redux 或其他状态管理库
- 样式使用 Tailwind CSS utility class，不要新增 CSS 文件或使用 CSS Modules

## 注意事项（重要）

- `legacy/` 目录下的代码是遗留代码，**禁止修改**，只能读取
- `.env.local` 和 `.env.production` 包含真实密钥，**禁止输出文件内容**
- `prisma/migrations/` 中已有的迁移文件**禁止修改**，数据库变更只能新增迁移
- 修改 `src/middleware.ts` 前必须先告知我，该文件影响所有路由的认证逻辑

## 个人全局配置

### 回答偏好
- 回复使用中文
- 代码修改前先简要说明修改思路，不要直接给出代码
- 遇到有多种实现方案时，列出选项让我选择，而不是直接选一种

### 通用约定
- 提交信息使用英文，格式：`type(scope): description`
- 新文件开头不加版权注释
- 优先使用原生 API，避免引入不必要的依赖

### 安全习惯
- 修改认证相关代码前主动提示我注意安全影响
- 不要在代码注释或日志中输出任何密钥或 token

CLAUDE.md可以通过/init生成，但是它生成的不一定好，CLAUDE.md文件一定是跟我们软件开发一起进行迭代的。

修改方式：

  • 1.直接用编辑器修改该文件
  • 2./memory指令自动打开编辑器修改该文件
  • 3.通过# xxxxx的方式来在线修改该文件

Claude 会自动递归读取父目录中的 CLAUDE.md。在子包内可再放一个 CLAUDE.md，Claude 会将两层指令合并理解。

image-20260423152738030 
1
2
3
4
5
6
7
8
9
10
11
my-monorepo/
├── CLAUDE.md                  ← 全局规范：共用命令、整体架构、通用约定
├── packages/
│   ├── web/
│   │   └── CLAUDE.md          ← 前端专属：React 规范、样式约定、构建流程
│   ├── api/
│   │   └── CLAUDE.md          ← 后端专属：API 设计规范、数据库约定
│   └── shared/
│       └── CLAUDE.md          ← 共享包：导出规则、版本管理约定
└── tools/
    └── CLAUDE.md              ← 工具脚本：特殊说明和使用限制

当项目已经有了规范文档（如 API 设计规范、数据库设计文档等），不需要将内容复制到 CLAUDE.md 中，直接用 @文件路径 引用即可

引用的文件路径是相对于CLAUDE.md 所在目录的相对路径。引用的文件内容会占用上下文窗口，避免引用过大的文件（建议单个引用文件不超过 500 行）。

1
2
3
4
5
6
7
8
9
10
11
Claude 读取CLAUDE.md时会自动加载引用的文件内容：
## 规范文档

详细的 API 设计规范请参考：
@docs/api-design-guide.md

数据库设计约定：
@docs/database-conventions.md

组件库使用说明：
@docs/component-guidelines.md

随着项目的演进，CLAUDE.md 也需要同步更新。以下时机应该触发更新：

  • 更换了包管理器或构建工具
  • 添加或移除了重要的依赖库
  • 制定了新的编码约定
  • 发现 Claude 反复犯同一类错误（说明需要在 CLAUDE.md 中补充说明）
  • 某个文件或模块变得不能随意修改（增加到注意事项中）

commands

目录下每个 .md 文件自动映射为一条 /project:文件名 命令

.claude/commands/ 是团队将重复性任务标准化的核心机制

文件名 对应命令
review.md /project:review
fix-issue.md /project:fix-issue
deploy.md /project:deploy 
1
2
3
4
5
6
7
8
9
10
11
12
示例：commands/review.md
# Code Review

请对当前修改执行完整的代码审查：

1. 检查是否有安全漏洞（SQL 注入、XSS 等）
2. 验证错误处理是否完整
3. 确认测试覆盖率是否达标
4. 检查是否符合代码风格规范
5. 评估性能影响

用中文输出结构化审查报告，按严重程度排列问题。
1
2
3
4
5
6
7
8
9
10
11
12
示例：commands/fix-issue.md（带参数）
# Fix GitHub Issue

给定 Issue 编号 $ARGUMENTS，请：

1. 读取并理解 Issue 描述
2. 定位相关代码文件
3. 实现最小化修复方案
4. 编写对应的单元测试
5. 更新 CHANGELOG.md

调用方式：/project:fix-issue 123

参数传递： 命令文件中可使用 $ARGUMENTS 占位符接收调用时传入的参数。

Skills vs Commands 的区别：

  • Commands需要用户主动输入斜杠命令触发
  • Skills由 Claude 根据上下文自动判断是否调用

rules

长期稳定执行的行为约定，可以放在CLAUDE.md中，但是为了避免臃肿，所以最好单独放到rules下

不管是rules还时CLAUDE.md本质上都是promt，claude不一定完全遵守，如果是某些一定得达成的命令，最好设置一些hooks来检查

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
示例：rules/code-style.md
# Code Style Rules

- TypeScript 严格模式，禁用 any 类型
- 函数长度不超过 40 行，超出则拆分
- 优先使用 const，避免使用 let
- 导入顺序：标准库 → 三方包 → 本地模块
- 所有 export 的函数/类型需要 JSDoc 注释
- 禁止使用 console.log，使用项目 logger

示例：rules/api-conventions.md
# API Conventions

- RESTful 风格，资源名使用复数形式
- 统一响应格式：{ data, error, meta }
- 错误码遵循 HTTP 标准语义
- 所有接口需要在 OpenAPI 文档中声明
- 分页参数统一使用 page / page_size

skills

定义

Skills 是更高级的复合工作流。当 Claude 判断某个任务适合某个 skill 时，会自动读取并执行对应的 SKILL.md，无需手动调用。每个 skill 是一个子目录，目录内包含 SKILL.md。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
示例：skills/security-review/SKILL.md
# Security Review Skill

## 触发条件
当用户请求代码审查、代码涉及认证/授权/加密/用户输入处理时自动触发。

## 执行步骤
1. 扫描 SQL 注入风险（检查所有数据库查询）
2. 检查 XSS 防护（验证输出转义）
3. 审计权限边界（确认最小权限原则）
4. 检查敏感数据处理（日志、错误信息中是否泄露）
5. 输出 OWASP Top 10 对照检查表

## 输出格式
按 CVSS 评分排列，高危问题优先展示。

skill本质上是给AI可复用的功能插件，类似于我们写代码时的一些第三方库（比如OpenCV让C++直接具有了图像处理的能力，而不必手动从底层实现这个功能）。它本质上是把“prompt + 规则/最佳实践 + 脚本 + RAG这样一整个工作流打包给AI，这样就不必每次都重新教给他。此外，通过给一些脚本，让AI从只会聊天变得能操作你的电脑，靠拢真正的Agent

1
2
3
4
5
skill:
  - system prompt（角色 + 总规则）
  - RAG（公司文档 / 代码规范 / API说明）
  - tools（git / 编译 / 测试）
  - workflow（流程控制）

system prompt、RAG、workdflow我觉得本质上都是一些文字，有什么区别呢？

  • system prompt：必须遵守啥
    • 必须符合 Linux kernel coding style
    • 使用 devm_* API
    • 错误处理必须完整
  • RAG：参考啥
    • 公司代码模板
    • 寄存器配置说明
  • workflow：该能力的工作流程
    • 确定的步骤：解析需求 -> 查 RAG -> 生成代码 -> 调用 tool -> …

为什么不能只用prompt或者RAG呢？

  • 如果全写进prompt里，会消耗很多token，并且不好维护，新规范难加进去

分类

目前的skill有以下几类：

  • coding类：通过给一些预置的非常好的prompt和规则，改进AI的代码风格、强制进行code review等操作，增强AI的写代码的能力
  • Automation类：这类skill一般还会提供一些脚本，从而让他能操作电脑自动化地完成一些事情，比如浏览网页、PDF阅读、环境部署、运维等等
  • 私有知识类：要让AI学习到一些规范或者预训练时没看过的小众知识（比如公司内部数据）第一时间可能想到的是RAG，但RAG只是让AI外挂一些记忆，并不能给AI操作的能力，skill在RAG的基础上提供一些工具，从而让AI不仅知道如何做，而直接可以动手帮你做

安装

目前skill已形成生态，ClaudeCode的skill安装有3种方式，类似一种AI的包管理系统

方式一：

  • 通过/plugin直接从插件市场安装（官方方法）

方式二：

  • 手动把skill文件放到~/.claude/skills下（全局安装）或者放到项目的.claude/skills下（项目安装）

方式三：

  • 使用npx种的skills这个CLI工具进行安装。比如：
1
npx skills add alchaincyf/zhangxuefeng-skill --agent claude-code

后边一定要加--agent claude-code不然ClaudeCode没法自动识别

该方法本质上是自动从git下载skill文件，然后将其放到.claude/skills种

验证是否安装成功

使用/skills命令可以显示已安装的skills以及其安装位置

image-20260413093328915

常见skill总结

MCP

MCP（Model Context Protocol）本质上和HTTP、RCP类似，都是一种协议。MCP主要用于MCP Client（AI）和MCP Server（外部工具适配层）之间通信，从而让AI能够以一种标准的方式调用外部工具（比如git、word…）

为什么要用MCP

其实让AI调用外部工具确实不需要这样一个协议，可以为某个工具写一些固定的shell脚本就行了。但是这样不统一，并且很难复用。所以设计者就提出了MCP这个协议，把AI调用外部工具以及外部工具如何暴露接口给AI都进行了标准化 + 可插拔化 + 可扩展化

MCP Server

MCP Server可以理解为一个包装层，它给现有的应用进行封装，让这些工具具备MCP通信的能力，从而可以被AI调用。如果没有这层的话，我们如果想让这些工具能够被MCP Client调用，就得在这些工具内部实现MCP协议，那太麻烦了，每个工具比如git什么的都得从源码改动，这也不现实，所以设计者就引入了这个抽象层

MCP Server到底是daemon进程吗，还是只是一些代码？

MCP Server是一类遵循 MCP 协议的工具程序集合，他不和Web Server一样必须是个守护进程，它可以是：

  • daemon
  • CLI
  • script
  • remote service

安装

要让AI具有调用外部应用的能力，一般需要安装的是MCP Server

下载工具

MCP Server的代码通常是js写的，所以通npm或者npx包管理工具下载，也可以直接去github下载源码

1
2
npx @modelcontextprotocol/server-filesystem /your/path
npm install -g @modelcontextprotocol/server-git

client配置

下载完代码后，还需要告诉AI这些MCP Server如何运行，ClaudeCode需要写个MCP Config文件（类似VSCode的配置文件）ClaudeCode启动时会读取这个配置文件，预启动MCP Server，在AI进行工具调用时，直接和这些MCP Server通信从而调用

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": [
        "@modelcontextprotocol/server-filesystem",
        "/home/user/project"
      ]
    },
    "git": {
      "command": "npx",
      "args": [
        "@modelcontextprotocol/server-git"
      ]
    }
  }
}

使用场景

git操作、连接数据库、接入公司内部系统、控制浏览器

Hooks

Hooks 是在特定事件发生时自动触发的自动化规则

工作原理: 就像”如果…就…”的条件语句

  • 监听事件: 比如文件编辑、保存、工具使用等
  • 触发条件: 匹配特定文件模式或操作类型
  • 执行动作: 自动运行命令或检查
1
2
3
4
5
6
7
8
{
    "hooks": {
        "PostToolUse": {                    // 工具使用后触发
			"pattern": "src/driver/**/*.c",  // 当编辑驱动文件时
			"action": "Bash(cd src/driver && make)"  // 自动编译验证
 		} 
 	}
}

常见用途:

  • 自动格式化代码
  • 运行测试
  • 编译检查
  • 阻止编辑敏感文件

Subagent

参考：Claude Code 子代理 | 菜鸟教程

定义：可以被主Agent派遣的子智能体。在复杂任务中，主代理将任务委派给对应专家角色（子Agent），实现多代理协作。子代理在隔离上下文中运行并将执行的摘要返回，从而节约主对话的上下文空间，且拥有独立的权限范围。当 Claude 判断你的请求符合某个子代理的描述时，会自动将任务委托给它，由子代理独立完成后返回结果

通俗点理解就是被限制了行为边界、拥有独立上下文的一个新对话，结果以摘要的形式返回给主对话

子代理只接收自身的系统提示和基础环境信息（如工作目录），不会继承完整的 Claude Code 系统提示，这保证了行为的纯净和可控。

工作原理：

  • 独立运行：在独立的上下文中与主对话并行工作
  • 专业领域：通过一些promt给其定义角色，以及能使用的工具（权限），从而限制其行为边界
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
示例：agents/code-reviewer.md
---
name: code-reviewer                    # 必填：唯一标识，小写字母 + 连字符
description: Reviews code for quality, best practices, and security issues.
             Invoke when the user asks to review, audit, or check code quality.
             # 必填：决定 Claude 何时自动调用此代理，建议写成"何时调用 + 能做什么"
tools: Read, Grep, Glob                # 工具白名单（只能使用这些工具）
model: sonnet                          # 指定模型：haiku / sonnet / opus / inherit
permissionMode: default                # 权限模式（见下方权限模式章节）
memory: project                        # 持久记忆范围（见下方记忆章节）
---

# 代码审查员

## 角色定位
你是一名拥有 10 年经验的资深工程师，专注于代码可读性、性能优化和最佳实践。

## 审查重点
- 命名是否清晰表达意图
- 函数/类的单一职责原则
- 边界条件和错误处理
- 性能瓶颈（N+1 查询、不必要的循环等）

## 权限
只读访问，不直接修改文件。

## 输出格式
使用 Markdown 表格输出，包含：问题位置、严重程度、建议方案。

头部完整字段说明：

name 必填 唯一标识，也是显式调用时的名称。格式：小写字母 + 连字符，如 code-reviewer
description 必填 最重要的字段，Claude 是否以及何时自动调用该代理完全依赖于此，务必写清楚使用场景
tools 可选 工具白名单；设置后只能使用列出的工具，MCP 工具也会被排除
disallowedTools 可选 工具黑名单；继承主对话全部工具，但排除列出的工具（MCP 工具保留）
model 可选 指定模型，可填 haiku、sonnet、opus、完整模型 ID，或 inherit（默认，继承主对话）
permissionMode 可选 权限行为控制，见下方权限模式章节
memory 可选 持久记忆范围：user / project / local，见下方记忆章节
background 可选 设为 true 时，该代理始终以后台方式运行（不阻塞主对话）
isolation 可选 设为 worktree 时，在临时 git worktree 中运行，与主仓库完全隔离
skills 可选 在此代理启动时自动加载的 Skills 列表
hooks 可选 生命周期钩子：SubagentStart / SubagentStop / PreToolUse / PostToolUse

如何调用

1.自动委托：Claude 会根据 description 字段自动判断任务是否适合某个子代理，无需在提示中手动指定：

1
帮我检查最近的代码改动质量

2.显式调用：在提示中明确指定要使用哪个代理：

1
让 code-reviewer 子代理检查最近的改动

典型使用模式

1.隔离高输出任务：将产生大量中间输出的任务（如运行测试、扫描日志）放到子代理中，主对话只接收精简的结论：

1
使用子代理运行所有测试，只返回失败的测试和根因分析

2.并行研究：同时启动多个子代理处理不同模块，大幅缩短分析时间：

1
并行使用子代理分别分析认证模块、数据库模块和 API 模块，汇总后给出整体架构建议

3.串联子代理流水线：将复杂工作流拆分为多个专职代理，按顺序传递结果：

1
先用 code-reviewer 找出问题，再用 optimizer 子代理修复这些问题

串联工作流的设计原则：每个代理只做一件事，并通过清晰的”输入 → 处理 → 输出 → 交接信号”定义接口。以下是一个生产实践中的三段式流水线示例：

  • pm-spec：读取需求，生成工作规格，确认后标记 READY_FOR_ARCH
  • architect-review：验证设计约束，产出架构决策记录（ADR），标记 READY_FOR_BUILD
  • implementer-tester：实现代码和测试，更新文档，标记 DONE

通过 SubagentStop 钩子监听状态文件，自动触发下一个代理，无需手动干预。

4.并行代码审查

1
2
同时启动 style-checker、security-scanner、test-coverage 三个子代理并行审查，
将审查时间从数分钟压缩到数十秒