CLAUDE.md 对 Skill 行为的全局约束
High Contrast
Dark Mode
Light Mode
Sepia
Forest
3 min read513 words

CLAUDE.md 对 Skill 行为的全局约束

settings.json 控制 Claude 能调用哪些工具，而 CLAUDE.md 控制 Claude 在所有对话和 Skills 执行中的行为准则。在 Skill 开发的视角下，CLAUDE.md 是定义"工程文化"的文件——它确保所有 Skills 的执行都符合团队的统一标准。

CLAUDE.md 的加载机制

Claude Code 在启动时会按以下顺序读取 CLAUDE.md 文件：

1. 用户级：~/.claude/CLAUDE.md
（对所有项目生效的个人偏好）
2. 项目根目录：{project}/CLAUDE.md
（项目级全局约束，推荐加入版本控制）
3. 当前目录：{current-dir}/CLAUDE.md
（子目录特定约束，较少使用）

所有 CLAUDE.md 的内容都会被加载，它们叠加生效，不会互相覆盖。

CLAUDE.md 对 Skills 的三种作用

作用一：设定 Skills 的行为准则

在项目 CLAUDE.md 中定义所有 Skills 应遵守的规则：

# 项目 CLAUDE.md
## Claude Code 行为准则
### 安全操作原则
- 永远不要在没有用户确认的情况下执行破坏性操作（删除文件、强制 push）
- 生产环境的操作（--env production）必须在执行前输出操作摘要，等待确认
- 不要读取 .env 文件的内容并输出——这些是敏感信息
### 代码修改原则
- 修改代码前，先读取整个文件，理解现有结构
- 提出修改建议，但不要直接修改，除非用户明确要求
- 对修改操作，说明修改的原因和潜在影响
### 输出格式原则
- 使用 Markdown 格式输出（代码块、表格、列表）
- 报告类输出使用中文，代码注释保持英文
- 错误和警告使用统一的图标：❌ 错误，⚠️ 警告，✅ 通过，ℹ️ 信息

作用二：提供项目背景上下文

## 项目信息
**项目名称**：支付处理服务（Payment Processing Service）
**技术栈**：Node.js 20 + TypeScript + PostgreSQL + Redis
**代码仓库结构**：
- `src/api/` — REST API 路由和控制器
- `src/services/` — 业务逻辑
- `src/models/` — 数据库模型
- `tests/` — 单元测试和集成测试
- `db/migrations/` — 数据库迁移脚本
**运行测试**：`npm test`（单元）或 `npm run test:integration`（集成）
**Lint 检查**：`npm run lint`
**构建**：`npm run build`
Skills 在执行时应了解这个项目结构，特别是迁移文件位置和测试命令。

当 Skills 执行时，它们能利用这些上下文做出更准确的操作（比如知道测试命令是 npm test 而不是 pytest）。

作用三：定义团队标准

## 团队工程标准
### PR 描述规范
PR 描述必须包含：
1. 变更摘要（1–3 句）
2. 测试覆盖说明
3. 数据库影响（如有迁移）
4. 回滚方案
### 代码审查重点
每次代码审查必须检查：
- [ ] SQL 注入防护（所有查询使用参数化）
- [ ] 敏感数据日志（不得 log 用户密码、token）
- [ ] 错误处理（所有 async 函数有 try/catch 或 .catch()）
- [ ] 测试覆盖率（关键路径有单元测试）
### 数据库迁移规范
迁移脚本必须：
- 有 `up()` 和 `down()` 函数（可回滚）
- 避免在 `up()` 中删除有数据的列（需要数据清理周期）
- 大表变更使用 `CONCURRENTLY` 选项

这些标准会自动应用到所有相关的 Skills（/review-pr 会按照审查重点检查，/gen-pr-desc 会按照 PR 描述规范生成）。

CLAUDE.md 中的 Skills 特定配置

可以在 CLAUDE.md 中专门为 Skills 写一节配置：

## Skills 配置
### Skills 的通用行为规则
**所有 Skills 必须：**
- 在执行开始时输出"📌 正在执行：[Skill 名称]..."
- 在遇到错误时使用标准错误格式（❌ + 原因 + 建议）
- 在输出结束时包含"---\n*[Skill名称] 执行完成*"
**破坏性操作 Skills（write/edit/delete 类）必须：**
- 在执行前列出即将进行的操作清单
- 等待用户确认（输出"请确认以上操作 [y/N]："）
- 记录操作日志到 `.claude/audit.log`
**报告类 Skills 的输出应：**
- 优先输出最关键的发现（严重问题）
- 使用表格展示比较性数据
- 在末尾提供"建议的下一步操作"
### 安全敏感的 Skills
以下 Skill 在执行前必须要求用户确认：
- `/deploy-*` 系列（任何部署相关操作）
- `/migrate-*` 系列（数据库迁移操作）
- 任何修改 production 配置的操作

验证 CLAUDE.md 是否生效

最简单的验证方式是在会话开始时问 Claude：

> 你对这个项目有哪些行为准则？
（Claude 应该能列出 CLAUDE.md 中定义的规则）

也可以设计一个专门的验证 Skill：

---
description: 显示当前生效的 CLAUDE.md 配置摘要
---
# 配置验证
## 目标
显示当前会话中生效的项目配置摘要，帮助验证 CLAUDE.md 已正确加载。
## 执行步骤
1. 读取 `CLAUDE.md`（如果存在）
2. 读取 `~/.claude/CLAUDE.md`（用户级配置，如果存在）
3. 输出当前生效的关键配置项
## 输出格式

当前 CLAUDE.md 配置摘要

项目级配置（./CLAUDE.md）

[列出关键规则]

用户级配置（~/.claude/CLAUDE.md）

[列出关键规则]

总结

所有 Skills 将遵循以上规则执行。

本节记录清单

下一节：敏感操作的确认机制与沙箱考量——哪些操作需要额外的用户确认？如何在 Skill 设计层面建立防护机制？