📝 CLAUDE.md 最佳维护实践指南

让你的 AI 助手更好地理解你和你的项目

一、什么是 CLAUDE.md？

常见名称

• CLAUDE.md - Claude Code 使用
• AGENTS.md - Clawdbot 使用
• CLAUDE.md - 通用命名

二、核心文件体系

一个完整的 AI 助理解项目上下文体系通常包含以下文件：

文件名	用途	加载时机
AGENTS.md	操作指令、规则、优先级	每个会话开始
SOUL.md	人设、语气、边界	每个会话开始
USER.md	用户信息、称呼方式	每个会话开始
IDENTITY.md	AI 助手的名字、风格、emoji	创建/更新时
TOOLS.md	本地工具和约定说明	按需读取
HEARTBEAT.md	心跳检查清单	心跳运行时
memory/	每日记忆日志	会话开始时
MEMORY.md	长期记忆精选	主会话时

三、文件内容结构

AGENTS.md 核心内容模板

# AGENTS.md - 项目操作指南

## 关于本项目

- **项目名称**：[项目名]
- **技术栈**：[如 React, Node.js, Python 等]
- **项目类型**：[如 Web 应用、CLI 工具、库等]

## 代码规范

### 编码风格
- 使用 [ESLint/Prettier] 规范
- 函数式编程优先
- 变量命名：[具体规则]

### 提交规范
- 使用 [Conventional Commits] 格式
- 提交信息格式：`type(scope): description`

### 测试要求
- 单元测试覆盖率 > 80%
- 每个新功能需要对应的测试用例

## 项目结构

```
src/
├── components/    # 组件
├── utils/        # 工具函数
├── services/     # 服务层
└── ...
```

## 常用命令

| 命令 | 说明 |
|------|------|
| `npm run dev` | 启动开发服务器 |
| `npm test` | 运行测试 |
| `npm run build` | 构建生产版本 |

## 注意事项

- [特定业务规则]
- [需要手动确认的操作]
- [敏感信息处理方式]

## 记忆

- [重要决策记录]
- [历史问题解决方案]

SOUL.md 人设模板

# SOUL.md - AI 助手人设

## 核心特质

- **专业但不高冷** - 乐于助人，但不过度殷勤
- **直接了当** - 不说废话，用结果说话
- **有观点** - 可以不同意用户，有自己的判断

## 行为准则

- 帮助但不迎合 - 可以挑战用户的想法
- 安全第一 - 涉及删除/修改时先确认
- 保守隐私 - 不该说的不说

## 沟通风格

- 简洁优先 - 能一句话说完不啰嗦
- 技术文档用 markdown
- 群聊中做有价值的贡献，不刷屏

## 边界

- 不主动做外部操作（发邮件、发推等）
- 不确定的事直接说不知道
- 拒绝危险操作（如 rm -rf /）

USER.md 用户信息模板

# USER.md - 用户信息

## 基本信息

- **称呼**：[用户希望怎么称呼]
- **时区**：[如 Asia/Shanghai]
- **偏好**：[沟通偏好、称呼习惯等]

## 技术背景

- **专长**：[技术领域]
- **水平**：[如 中级开发者/架构师]
- **偏好**：[喜欢的工具、框架等]

## 项目背景

- **当前项目**：[项目名]
- **项目目标**：[业务目标]
- **团队情况**：[ solo/小团队/大公司]

## 注意事项

- [用户特别在意的点]
- [沟通习惯]
- [不喜欢的做法]

四、最佳实践

1. 渐进式完善

• 初始 → 创建基础模板，只填必要信息
• 使用中 → 遇到问题、做了决策就更新
• 定期 → 每月回顾，清理过时内容

2. 及时记录

3. 保持简洁

• 不过度设计 - 不要一开始就写完善的文档
• 突出重点 - AI 最关心的是"怎么运行"和"注意什么"
• 定期清理 - 删除已过时的规则和记录

4. 敏感信息处理

类型	处理方式	示例
API Key	使用环境变量	${OPENAI_API_KEY}
密码/Token	绝不写入文件	使用 1Password 或 env
私钥/证书	加入 .gitignore	*.key, *.pem
敏感路径	用占位符	/path/to/credentials

5. 版本控制

• 推荐 - 将配置文件加入私有 git 仓库
• 好处 - 随时恢复，历史可查
• 注意 - 确保仓库是私有的

# 初始化 git 备份
cd ~/clawd
git init
git add AGENTS.md SOUL.md TOOLS.md USER.md memory/
git commit -m "Add agent workspace"

# 定期更新
git add -A
git commit -m "Update memory and rules"
git push

五、常见模式

模式 1：一人项目

# 重点关注
- 个人编码习惯
- 常用的快捷方式
- 项目的特殊约定

模式 2：团队项目

# 重点关注
- 团队编码规范
- Code Review 要求
- CI/CD 流程
- 发布流程
- 角色分工

模式 3：长期维护项目

# 重点关注
- 历史遗留问题记录
- 技术债务清单
- 升级注意事项
- 依赖版本管理

六、常见误区

误区	问题	正确做法
一次写完	内容过多，AI 难以聚焦	渐进式完善，需要时添加
从不更新	信息过时，失去参考价值	及时记录决策，定期清理
写入敏感信息	泄露风险	使用占位符或环境变量
过于详细	增加 token 消耗，可能被截断	保持简洁，突出重点
不备份	丢失重要上下文	使用私有 git 仓库

七、大小限制

如果文件过大

• 拆分到多个文件（如 rules/ 目录）
• 使用 TOOLS.md 存放细节
• 将历史记录移到 memory/ 目录
• 定期归档旧内容

八、与工具集成

Clawdbot 配置示例

{
  "agent": {
    "workspace": "~/clawd",
    "skipBootstrap": false
  }
}

GitHub Codespaces

# 在项目根目录创建
CLAUDE.md

# 会被自动识别为项目上下文

九、总结

维护良好的项目配置文件就像有一个好的项目经理——它帮助你保持上下文一致，让 AI 助手始终了解项目的最新状态。