规则维护完整指南

本文档提供 WorldTourCasino 项目规则维护的完整指导。

📚 目录

1. 三层架构详解
2. 判断标准详解
3. 添加规则步骤
4. 示例对比
5. 常见问题

---

三层架构详解

第一层：核心规则（CLAUDE.md 内联）

核心特征：违反后果严重 + 难以恢复

判断标准：

1. 违反后果：严重（污染代码库、历史记录、配置损坏）
2. 恢复成本：高（难以撤销、需要团队协调）
3. 使用频率：极高（每天多次）
4. 可靠性要求：100%（绝对不能违反）

载入方式：

• AI 实例启动时自动载入（100% 载入）

内容类型：

• 禁止项（❌ 绝对不能做）
• 强制流程（✅ 必须遵守的步骤）
• 核心约束（如 ES5、提交确认）

添加位置：

CLAUDE.md
└── ⚠️ 工作规则
    ├── 禁止行为 ← 禁止项加这里
    ├── 代码规范 ← 代码约束加这里
    └── Git 工作流 ← 强制流程加这里

示例：

✅ 适合第一层：

• Git 提交必须确认 → 错误提交污染历史，团队共享
• 禁止 ES6+ 特性 → 运行时错误，可能已部署
• 配置文件必须同步 → 配置损坏影响团队开发
• 禁止修改 Git 子模块 → 破坏依赖关系

❌ 不适合第一层：

• Shell 脚本变量引用规范 → 违反会报错，立即发现，易修复
• Git 提交信息详细格式 → 格式错误可修复，不影响功能
• 文档链接格式 → 链接失效可修复，影响小

---

第二层：详细规则（外部文件 + 触发规则表）

核心特征：需要详细规范 + 违反可修复

判断标准：

1. 违反后果：中等（影响结果但可修复）
2. 恢复成本：低（立即发现，易修复）
3. 使用频率：中高（每周数次）
4. 可靠性要求：~85%（可容忍偶尔遗漏）

载入方式：

• AI 检查 CLAUDE.md "任务触发规则表" → 匹配关键词 → 读取规则文件
• 半自动，依赖 AI 判断（~85% 可靠）

内容类型：

• 详细规范（第一层核心规则的展开）
• 复杂流程（多步骤、多项目协调）
• 参考指南（最佳实践、完整规范）

添加步骤：

1. 创建规则文件：docs/工程-工具/ai-rules/[分类]/[规则名].md
2. 更新 CLAUDE.md 触发规则表：

## 任务触发规则

| 任务触发条件 | 必读文件 | 示例场景 |
|------------|---------|---------|
| **[新任务]** | `docs/.../[规则名].md` | "关键词1" <br> "关键词2" |

示例：

✅ 适合第二层：

• Shell 脚本完整规范 → 核心已要求 Shebang，详细包含错误处理、日志
• Git 多项目提交流程 → 核心已要求确认，详细包含提交顺序、冲突处理
• VitePress 开发规范 → 核心已禁止相对链接，详细包含图片处理、构建流程
• 资源版本控制规范 → 详细的 resource_dirs.json 管理流程

❌ 不适合第二层：

• Git 提交必须确认 → 太核心，应在第一层
• 发布检查清单 → 有明确工作边界，应在第三层

---

第三层：复杂任务（Slash Commands）

核心特征：有清晰的工作边界

判断标准：

1. 工作边界：用户明确知道"我要做 X 任务"
2. 任务起止：有明确的开始和结束
3. 完整流程：需要系统化的执行步骤
4. 主动触发：用户主动进入"工作模式"

可靠性：100%（用户主动触发）

载入方式：

• 用户手动执行斜杠命令（如 /release-checklist）

内容类型：

类型	说明	工作边界
系统化任务	有明确执行清单	检查开始 → 检查完成
工作模块	特定领域完整规则	进入模块 → 离开模块
业务流程	有边界的业务操作	流程开始 → 流程结束
专业领域	需要完整知识体系	进入领域 → 离开领域

添加步骤：

1. 创建命令文件：.claude/commands/[命令名].md
2. 添加 frontmatter：

---
description: 命令功能描述
---

请执行以下流程：

1. 步骤一
2. 步骤二
...

示例：

✅ 适合第三层（有清晰边界）：

• /release-checklist → "我要做发布前检查"（检查开始 → 检查完成）
• /activity-reskin → "我要做活动换皮"（备份 → 替换 → 验证 → 完成）
• /extension-dev → "我要开发扩展"（进入开发模式 → 完成开发）
• /level-config-gen → "我要生成关卡配置"（生成开始 → 验证完成）
• /native-build-guide → "我要做原生构建"（进入原生开发 → 构建完成）

❌ 不适合第三层（没有清晰边界）：

• "帮我写个函数" → 零散问答，没有工作边界
• "提交代码" → 虽有边界，但高频强制，应在第一层
• "查看日志" → 零散查询，没有完整流程

---

判断标准详解

决策矩阵（完整版）

判断维度	第一层（内联）	第二层（外部）	第三层（Command）
核心特征	违反后果严重	需要详细规范	有清晰工作边界
违反后果	严重	中等	无关
恢复成本	高（难撤销）	低（易修复）	无关
使用频率	极高（每天多次）	中高（每周数次）	低（每月数次）
可靠性要求	100%	~85%	100%（手动）
用户感知	"这是规则"	"需要详细信息"	"我要做 X 任务"
触发方式	自动载入	AI 匹配触发	用户主动

快速判断流程图

新规则需求
  ↓
问：违反后果严重吗？（污染代码库、难撤销）
  ├─ 是 → 问：使用频率高吗？（每天多次）
  │       ├─ 是 → 第一层（内联）
  │       └─ 否 → 再评估（可能仍需第一层）
  │
  └─ 否 → 问：用户有明确工作边界吗？（"我要做 X"）
          ├─ 是 → 第三层（Slash Command）
          └─ 否 → 第二层（外部文件）

---

添加规则步骤

第一层：添加到 CLAUDE.md

步骤 1：确认符合标准

• [ ] 违反后果严重
• [ ] 恢复成本高
• [ ] 使用频率极高

步骤 2：选择添加位置

⚠️ 工作规则
├── 禁止行为 ← 禁止项（❌）
├── 强制要求 ← 回答风格、语言规范
├── 代码规范 ← 代码约束（ES5、Shell）
├── Git 工作流 ← Git 强制流程
├── 配置文件同步 ← 配置强制要求
└── 文档记录原则 ← 文档规范

步骤 3：使用强制标记

• 禁止项：❌ **[规则]**
• 强制项：✅ **[规则]**
• 章节标题：（强制）

示例：

## 禁止行为

- ❌ **提交信息中添加 AI 标识**
- ❌ **跳过确认流程**
- ❌ **[新规则] 直接修改 frameworks/ 目录**（Git 子模块）

---

第二层：添加外部文件 + 更新触发表

步骤 1：创建规则文件

位置：docs/工程-工具/ai-rules/[分类]/[规则名].md

分类：

• WTC/ - 主项目规则
• docs/ - 文档子项目规则
• extensions/ - 扩展子项目规则
• shared/ - 通用规则

步骤 2：编写规则内容

建议结构：

# [规则名]

## 概述
[简要说明]

## 核心规则
[关键要求]

## 详细规范
[具体步骤]

## 示例
[正确示例]
[错误示例]

## 常见问题
[FAQ]

步骤 3：更新 CLAUDE.md 触发规则表

在 CLAUDE.md 🤖 AI 工作指引 > 任务触发规则 中添加：

| 任务触发条件 | 必读文件 | 示例场景 |
|------------|---------|---------|
| **[任务名]** | `docs/工程-工具/ai-rules/[路径]` | "关键词1" <br> "关键词2" <br> "关键词3" |

关键词选择原则：

• ✅ 用户常用的自然语言（"提交"、"写脚本"、"添加文档"）
• ✅ 2-3 个变体（"提交"、"都提交吧"、"提交一下"）
• ❌ 避免技术术语（用户不会说"执行 git commit"）

---

第三层：创建 Slash Command

步骤 1：确认有清晰工作边界

• [ ] 用户明确知道"我要做 X 任务"
• [ ] 任务有明确的起止
• [ ] 需要完整的工作流程

步骤 2：创建命令文件

位置：.claude/commands/[命令名].md

命名规范：

• 小写字母 + 连字符
• 动词开头（create-, check-, load-）
• 描述性（release-checklist, activity-reskin）

步骤 3：编写命令内容

模板：

---
description: [简短描述，显示在命令列表中]
---

[命令说明]

请执行以下流程：

## 1. [步骤名]
[具体操作]

## 2. [步骤名]
[具体操作]

...

## 输出格式

[期望的输出格式]

示例：

.claude/commands/activity-reskin.md：

---
description: 活动换皮完整流程
---

请执行活动换皮流程：

## 1. 备份当前资源
```bash
cp -r res_oldvegas/activity/current res_oldvegas/activity/backup_$(date +%Y%m%d)

2. 更新活动资源

• 替换图片资源
• 更新配置文件

3. 验证资源

• 检查文件完整性
• 验证配置格式

4. 构建测试

scripts/build_local_oldvegas.sh

5. 生成报告

输出格式：

• ✅ 已完成的步骤
• ⚠️ 需要注意的问题
• 📋 资源清单

---

## 示例对比

### 示例 1：Git 提交确认

**规则需求**：主项目提交前必须询问用户确认

**判断**：
- 违反后果：严重（错误提交污染历史）
- 恢复成本：高（需要 revert，影响团队）
- 使用频率：极高（每天多次）

**结论**：✅ **第一层（内联）**

**添加位置**：
```markdown
CLAUDE.md > ⚠️ 工作规则 > Git 工作流 > 主项目提交（强制）

---

示例 2：Shell 脚本详细规范

规则需求：Shell 脚本的错误处理、日志、最佳实践

判断：

• 违反后果：中等（脚本报错，立即发现）
• 恢复成本：低（修改后重新执行）
• 使用频率：中（每周数次）

结论：✅ 第二层（外部文件）

操作：

1. 创建：docs/工程-工具/ai-rules/WTC/shell-scripts.md
2. 更新触发表：

| **编写 Shell 脚本** | `docs/.../shell-scripts.md` | "做成 shell脚本" <br> "修改 .sh 文件" |

---

示例 3：活动换皮流程

规则需求：活动换皮的完整流程（备份、替换、验证）

判断：

• 工作边界：✅ 清晰（用户："我要做万圣节活动换皮"）
• 任务起止：✅ 明确（换皮开始 → 换皮完成）
• 完整流程：✅ 需要（备份 → 替换 → 验证 → 报告）

结论：✅ 第三层（Slash Command）

操作： 创建：.claude/commands/activity-reskin.md

---

示例 4：资源版本控制

规则需求：修改资源后必须更新 resource_dirs.json

判断：

• 违反后果：中等（资源加载失败，立即发现）
• 恢复成本：低（更新版本号即可）
• 使用频率：中（每周数次）

结论：✅ 第二层（外部文件）

但可以在第一层添加简单提醒：

## 禁止行为

- ❌ 修改资源文件但不更新 resource_dirs.json

然后第二层提供详细规范：

| **资源版本控制** | `docs/.../resource-version.md` | "更新资源" <br> "添加图片" |

---

常见问题

Q1: 如何判断"后果是否严重"？

严重：

• 污染代码库（错误提交、配置损坏）
• 难以撤销（需要团队协调、影响历史记录）
• 影响生产环境（已部署的错误）

中等：

• 立即发现（脚本报错、构建失败）
• 易于修复（修改后重新执行）
• 影响本地（不影响团队或生产）

Q2: 第一层和第二层都可以时怎么选？

倾向第一层：

• 使用频率极高（每天多次）
• 团队痛点（经常被违反）
• 规则简洁（<20 行）

倾向第二层：

• 使用频率中等（每周数次）
• 规则详细（>50 行）
• 可容忍偶尔遗漏

Q3: 如何设计好的触发关键词？

原则：

• ✅ 用户自然语言（"提交"、"写脚本"）
• ✅ 提供变体（"提交"、"提交吧"、"提交一下"）
• ✅ 包含动词（"创建"、"修改"、"添加"）
• ❌ 避免技术术语（"执行 git commit"）

示例：

| **git 提交任务** | ... | "提交" <br> "都提交吧" <br> "提交一下" |
| **创建文档** | ... | "添加文档" <br> "写文档" <br> "记录到文档" |

Q4: Slash Command 的命名有什么规范？

规范：

• 小写字母 + 连字符
• 动词开头（描述动作）
• 简洁描述性

示例：

• ✅ /release-checklist （发布检查）
• ✅ /activity-reskin （活动换皮）
• ✅ /load-all-rules （加载规则）
• ❌ /check （太模糊）
• ❌ /releaseChecklist （不用驼峰）

Q5: 是否可以同时在多层添加同一规则？

可以，但需要明确分工：

示例：资源版本控制

第一层（核心禁止）：

## 禁止行为
- ❌ 修改资源文件但不更新 resource_dirs.json

第二层（详细规范）：

| **资源版本控制** | `docs/.../resource-version.md` | ... |

分工：

• 第一层：核心约束（"禁止 X"）
• 第二层：详细操作（"如何正确更新版本号"）

---

文档版本: v1.0 最后更新: 2025-10-15 维护者: WorldTourCasino Team