162 lines
4.3 KiB
Markdown
162 lines
4.3 KiB
Markdown
# Update CLAUDE.md 命令使用说明
|
||
|
||
## 概述
|
||
|
||
`update-claude-md` 是一个 Claude Code 命令，用于智能更新项目文档。遵循 **文档分层策略**，确保 CLAUDE.md 保持精简，详细内容放在专门的文档中。
|
||
|
||
## 核心原则
|
||
|
||
**CLAUDE.md 必须保持精简！** 这是 Claude Code 最佳实践的核心要求。
|
||
|
||
| 文档 | 内容 | 行数限制 |
|
||
|------|------|---------|
|
||
| `CLAUDE.md` | 核心摘要规则（1-2 句话） | ≤ 300 行 |
|
||
| `docs/CODING_RULES.md` | 详细规则 + 错误/正确示例 | 无限制 |
|
||
| `docs/FEATURE_FLOWS.md` | 功能流程说明 | 无限制 |
|
||
|
||
## 使用方法
|
||
|
||
### 基本用法
|
||
|
||
```bash
|
||
# 添加新规则
|
||
/update-claude-md 发现 Claude 经常忘记给 TDesign 的 Tooltip 添加 theme='light'
|
||
|
||
# 交互式
|
||
/update-claude-md
|
||
```
|
||
|
||
### 适用场景
|
||
|
||
1. **发现编码错误模式** → 更新 `docs/CODING_RULES.md`
|
||
2. **添加新功能流程** → 更新 `docs/FEATURE_FLOWS.md`
|
||
3. **高频/严重问题** → 同时更新 CLAUDE.md 摘要
|
||
|
||
## 命令执行流程
|
||
|
||
### 1. 判断规则重要性
|
||
|
||
```
|
||
发现问题
|
||
↓
|
||
是否高频/严重？ ──否──→ 只更新 CODING_RULES.md
|
||
↓ 是
|
||
CLAUDE.md < 280 行？ ──否──→ 先清理，再添加摘要
|
||
↓ 是
|
||
添加到 CLAUDE.md 摘要 + CODING_RULES.md 详情
|
||
```
|
||
|
||
### 2. 更新详细文档（主要操作）
|
||
|
||
在 `docs/CODING_RULES.md` 添加完整规则：
|
||
|
||
```markdown
|
||
### [问题标题]
|
||
|
||
**场景**: [何时会出现这个问题]
|
||
|
||
❌ **错误示例**:
|
||
```typescript
|
||
// 错误的代码
|
||
```
|
||
|
||
✅ **正确示例**:
|
||
```typescript
|
||
// 正确的代码
|
||
```
|
||
|
||
**原因**: [为什么这样做是错误的/正确的]
|
||
```
|
||
|
||
### 3. 更新 CLAUDE.md（仅高优先级）
|
||
|
||
只添加 1-2 句话的摘要：
|
||
|
||
```markdown
|
||
N. **规则名称**：简短描述（1-2 句话）
|
||
```
|
||
|
||
## 规则分类
|
||
|
||
| 类型 | 详细文档章节 | CLAUDE.md 章节 |
|
||
|------|-------------|---------------|
|
||
| TypeScript | `### TypeScript 规范` | `### 必须遵守` |
|
||
| React | `### React 组件规范` | `### React 规则` |
|
||
| Service Worker | `### Service Worker 规范` | `### Service Worker 规则` |
|
||
| 缓存 | `### 缓存与存储规范` | `### 缓存规则` |
|
||
| UI | `### UI 交互规范` | - |
|
||
| API | `### API 与任务处理规范` | - |
|
||
|
||
## 示例
|
||
|
||
### 示例 1：添加普通规则
|
||
|
||
**输入：**
|
||
```
|
||
/update-claude-md 发现滑块拖动时应该用 throttle 而不是 debounce
|
||
```
|
||
|
||
**结果：**
|
||
- ✅ `docs/CODING_RULES.md` 添加详细规则 + 示例
|
||
- ❌ CLAUDE.md 不更新（非高频问题）
|
||
|
||
### 示例 2：添加高优先级规则
|
||
|
||
**输入：**
|
||
```
|
||
/update-claude-md 发现 Context 回调中必须使用函数式更新，否则会导致状态错误
|
||
```
|
||
|
||
**结果：**
|
||
- ✅ `docs/CODING_RULES.md` 添加详细规则 + 示例
|
||
- ✅ CLAUDE.md 添加摘要：`Context 回调中必须使用函数式更新`
|
||
|
||
## 定期清理
|
||
|
||
当 CLAUDE.md 接近 300 行时：
|
||
|
||
1. **合并相似规则**：将多条相关规则合并为一条
|
||
2. **移除过时规则**：删除不再适用的规则
|
||
3. **降级详细规则**：将过于详细的规则移到 CODING_RULES.md
|
||
|
||
## 注意事项
|
||
|
||
1. **CLAUDE.md 必须精简**
|
||
- 行数限制 300 行
|
||
- 每条规则 1-2 句话
|
||
- 详细示例放在 CODING_RULES.md
|
||
|
||
2. **优先更新详细文档**
|
||
- 大多数规则只需更新 CODING_RULES.md
|
||
- 只有高频/严重问题才更新 CLAUDE.md
|
||
|
||
3. **检查重复**
|
||
- 避免添加已有类似规则
|
||
- 考虑补充现有规则而非新增
|
||
|
||
4. **及时清理**
|
||
- 定期审查并清理过时规则
|
||
- 合并相似规则
|
||
|
||
## 相关文件
|
||
|
||
- `.claude/commands/update-claude-md.md` - 命令定义文件
|
||
- `CLAUDE.md` - 项目核心文档（精简版）
|
||
- `docs/CODING_RULES.md` - 详细编码规则
|
||
- `docs/FEATURE_FLOWS.md` - 功能流程说明
|
||
- `docs/CONCEPTS.md` - 核心术语定义
|
||
|
||
## 常见问题
|
||
|
||
**Q: 什么规则应该放在 CLAUDE.md？**
|
||
A: 只有高频出现或会导致严重 bug 的规则才放入 CLAUDE.md，且只保留 1-2 句摘要。
|
||
|
||
**Q: CLAUDE.md 超过 300 行怎么办？**
|
||
A: 先执行清理：合并相似规则、移除过时规则、将详细规则降级到 CODING_RULES.md。
|
||
|
||
**Q: 详细的错误/正确示例放在哪？**
|
||
A: 放在 `docs/CODING_RULES.md`，CLAUDE.md 中只放简短摘要。
|
||
|
||
**Q: 如何判断规则是否"高频"？**
|
||
A: 如果同类问题在过去一周内出现 3 次以上，或者会导致生产 bug，就是高频。
|