规则架构演进史
WorldTourCasino AI 规则体系设计文档
本文档记录了项目 AI 规则体系从问题发现、方案探索到最终实施的完整过程。
📋 目录
第一部分：问题与探索
背景与目标
问题
随着项目复杂度增加，AI 规则文档分散在 20+ 个文件中，存在以下问题：
- 命名不一致：
-reference、-rules、-standards、-guide、-glossary混用 - 内容冗余：相同规则在多个文件中重复出现
- 缺乏索引：AI 难以快速定位规则
- 加载不可靠：AI 不会自动读取外部链接
目标
设计一套 AI 规则文档体系，使其：
- ✅ 组织合理，便于 AI 快速匹配规则
- ✅ 零冗余，每条规则只出现一次
- ✅ 可靠加载，核心规则 100% 生效
- ✅ 可扩展，便于未来添加新规则
三次迭代尝试
第一次尝试：模块化 + @ 导入
方案设计：
markdown
# CLAUDE.md
@docs/工程-工具/ai-rules/WTC/core-rules.md
@docs/工程-工具/ai-rules/shared/git-commit-types.md思路：
- 将规则拆分到
docs/工程-工具/ai-rules/的 15 个文件 - 使用 Anthropic 的
@导入机制引用 - 保持 CLAUDE.md 简洁
执行：
- 标准化文件命名（15 个文件重命名）
- 重构 core-rules.md（134→148 行）
- 优化 CLAUDE-REFERENCE.md（256→147 行，43% 减少）
- 创建索引文件（WTC/index.md、docs/index.md、extensions/index.md）
问题：
❌ @ 导入跨仓库不可靠
docs/ 是独立 Git 仓库
AI 可能无法正确解析路径结论：放弃 @ 导入，转向标注系统
第二次尝试：标注系统 + 索引链接
方案设计：
markdown
# CLAUDE.md
## 项目组织结构
### 主项目 (WTC)
- **核心规则**: [必读] `docs/工程-工具/ai-rules/WTC/core-rules.md`
- **Git 提交**: [触发提交任务时-必读] `docs/.../git-commits.md`
- **Shell 脚本**: [编写脚本时-必读] `docs/.../shell-scripts.md`标注系统：
[必读]- 启动时必读[XX任务时-必读]- 特定任务触发[强制]- 必须严格遵守- 无标注 - 可选参考
思路：
- 保持模块化，规则文件独立
- 通过标注告诉 AI 何时读取
- CLAUDE.md 仅作索引
实验验证：
用户在独立 Claude Code 实例中测试发现：
❌ 即使标注 [必读]，新的 AI 实例依然无法主动读取链接文档关键发现：
"我已经通过其他 claude code 实例证实了，规则确实需要内联， 即便标注必读，新的 AI 实例依然无法主动去读链接的文档"
结论：标注系统无效，核心规则必须内联
第三次尝试：混合策略（最终采用）
核心思想：
根据规则的 可靠性要求 和 使用特征 选择不同的存储和触发方式
决策依据：
| 特征 | 第一层 | 第二层 | 第三层 |
|---|---|---|---|
| 后果严重程度 | 严重（难以恢复） | 中等（可修复） | 低（可控） |
| 使用频率 | 极高（每天） | 中（每周） | 低（按需） |
| 内容复杂度 | 简洁（<50 行） | 详细（50-200 行） | 复杂（>200 行） |
| 可靠性要求 | 100% | ~85% | 100% |
| 加载方式 | 自动（内联） | 半自动（触发表） | 手动（Slash） |
最终方案：三层规则架构（详见第二部分）
关键发现
发现 1：AI 不会自动读取外部链接
实验：用户在独立 Claude Code 实例中测试标注系统
结果：
markdown
# ❌ 无效
- [必读] `docs/规则文件.md`
AI 不会自动读取该文件原因推测：
- Claude Code 启动时只读取 CLAUDE.md
- 外部链接需要显式 Read 工具调用
- 标注系统无法触发自动读取
影响：
- 核心规则必须内联
- 详细规则需要触发机制
- 复杂规则用户主动加载
发现 2：@ 导入跨仓库不可靠
问题：
markdown
# docs 是独立 Git 仓库
@docs/工程-工具/ai-rules/WTC/core-rules.md风险：
- 路径解析可能失败
- 子仓库状态不确定
- 维护成本高
结论：避免跨仓库引用，核心内容必须内联
发现 3：可靠性是架构设计的核心
错误思维：按内容类型分层（通用、主项目、子项目）
正确思维：按可靠性需求分层（100% 内联、85% 触发、100% 手动）
关键洞察：
"我们当前的三层架构划分的核心在于规则的可靠性，对吧"
这个认知转变是设计突破的关键。
第二部分：最终方案
三层架构详解
第一层：核心规则（CLAUDE.md 内联）
核心特征：违反后果严重 + 难以恢复
判断标准：
- 违反后果：严重（污染代码库、历史记录、配置损坏）
- 恢复成本：高（难以撤销、需要团队协调）
- 使用频率：极高（每天多次）
- 可靠性要求：100%（绝对不能违反）
载入方式：
- AI 实例启动时自动载入（100% 载入）
内容类型：
- 禁止项（❌ 绝对不能做）
- 强制流程（✅ 必须遵守的步骤）
- 核心约束（如 ES5、提交确认）
示例：
✅ 适合第一层：
- Git 提交必须确认 → 错误提交污染历史，团队共享
- 禁止 ES6+ 特性 → 运行时错误，可能已部署
- 配置文件必须同步 → 配置损坏影响团队开发
优点：
- 🚀 启动即生效，无需读取额外文件
- 💰 节省 token（规则已在上下文中）
- 🎯 100% 可靠（不依赖 AI 主动性）
第二层：详细规则（外部文件 + 触发表）
核心特征：需要详细规范 + 可修复
判断标准：
- 违反后果：中等（可修复、立即发现）
- 内容复杂度：详细（50-200 行）
- 使用频率：中等（每周数次）
- 可靠性要求：~85%（大部分场景够用）
载入方式：
- CLAUDE.md 中的任务触发规则表引导
- AI 看到特定任务关键词后读取
内容类型：
- 完整规范文档（Shell 脚本完整规范）
- 详细工作流（多项目提交流程）
- 配置说明（配置同步详细步骤）
CLAUDE.md 中的引导：
markdown
## 任务触发规则（强制）
执行以下任务时，**必须先读取对应规则文件**：
| 任务触发条件 | 必读文件 | 示例场景 |
|-------------|---------|---------|
| **git 提交任务** | `docs/工程-工具/ai-rules/WTC/git-commits.md` | "提交"、"都提交吧" |
| **编写 Shell 脚本** | `docs/工程-工具/ai-rules/WTC/shell-scripts.md` | "做成 shell脚本" |示例：
✅ 适合第二层：
- Shell 脚本完整规范 → 错误立即发现，可快速修复
- Git 提交详细流程 → 有确认环节，可撤销
- VitePress 开发规范 → 构建时验证，可修正
优点：
- 📚 完整文档不占用 CLAUDE.md 空间
- 🎯 明确告诉 AI "何时应该读取"
- 🔄 易于维护和更新
- 📖 人类也可以直接阅读
第三层：复杂任务（Slash Commands）
核心特征：有清晰工作边界
判断标准：
- 工作边界：清晰（用户明确："我要做 X 任务"）
- 内容复杂度：复杂（>200 行或需加载多个文件）
- 使用频率：低（每月数次或按需）
- 可靠性要求：100%（用户主动触发）
载入方式：
- 用户显式执行 Slash Command
- AI 按命令加载完整规则集
内容类型：
- 发布前完整检查清单
- 大型重构准备（加载所有规则）
- 专项任务指南（活动换皮流程）
实现位置：.claude/commands/
示例 1：加载 Git 完整规则
markdown
# .claude/commands/load-git-rules.md
---
description: 加载 Git 完整规则和工作流
---
请按顺序读取以下文件：
1. docs/工程-工具/ai-rules/shared/git-commit-types.md
2. docs/工程-工具/ai-rules/WTC/git-commits.md
3. docs/工程-工具/ai-rules/docs/auto-commits.md用法：
用户: /load-git-rules
AI: ✅ 已加载 3 个规则文件
关键规则摘要：...示例 2：发布前检查
markdown
# .claude/commands/release-checklist.md
---
description: 执行完整的发布前检查清单
---
请执行以下检查流程：
1. 代码检查：npm run lint
2. 构建所有风格
3. 检查 Git 状态
4. 验证配置同步
5. 生成检查报告示例：
✅ 适合第三层：
- 发布前检查清单 → 用户明确："我要发布"
- 加载所有规则 → 用户明确："要做大型重构"
- Shell 脚本完整规范 → 用户明确："我要写脚本"
优点：
- 🎯 100% 可靠（用户主动触发）
- 🧠 完整上下文（可加载大量规则）
- 🔧 灵活可控（用户决定何时加载）
- 📝 可组合（多个 command 配合使用）
决策矩阵
快速判断：规则放在哪里？
新规则需求
↓
违反后果严重 + 难以恢复？
├─ 是 → 第一层（内联）
└─ 否 → 用户有明确工作边界？
├─ 是 → 第三层（Slash Command）
└─ 否 → 第二层（外部文件）详细对照表
| 规则示例 | 后果严重性 | 使用频率 | 复杂度 | 层级 |
|---|---|---|---|---|
| 提交必须确认 | 严重 | 每天 10+ | 简单（5 行） | 第一层 |
| 禁止 ES6+ | 严重 | 每天 5+ | 简单（10 行） | 第一层 |
| 配置同步 | 严重 | 每周 1-2 | 简单（20 行） | 第一层 |
| Shell 脚本规范 | 中等 | 每周 2-3 | 详细（150 行） | 第二层 |
| Git 复杂流程 | 中等 | 每周 1-2 | 详细（100 行） | 第二层 |
| VitePress 开发 | 中等 | 每周 2-3 | 详细（80 行） | 第二层 |
| 发布检查清单 | 低 | 每月 1-2 | 复杂（200+ 行） | 第三层 |
| 加载所有规则 | 低 | 按需 | 极复杂（17 文件） | 第三层 |
文件结构
WorldTourCasino/
├── CLAUDE.md # 第一层：核心规则
│ ├── 📚 项目信息
│ ├── ⚠️ 工作规则（禁止、强制、规范）
│ └── 🤖 AI 工作指引（任务触发规则表）
│
├── .claude/
│ └── commands/ # 第三层：Slash Commands
│ ├── load-git-rules.md
│ ├── load-all-rules.md
│ ├── release-checklist.md
│ └── shell-best-practices.md
│
└── docs/
└── 工程-工具/
└── ai-rules/ # 第二层：详细规则
├── 规则架构演进史.md # 本文档
├── WTC/
│ ├── index.md
│ ├── git-commits.md
│ ├── shell-scripts.md
│ ├── config-sync.md
│ ├── terminology.md
│ └── doc-workflow.md
├── docs/
│ ├── index.md
│ ├── vitepress.md
│ ├── link-processing.md
│ ├── image-processing.md
│ └── auto-commits.md
├── extensions/
│ ├── index.md
│ ├── extension-dev.md
│ ├── activation.md
│ └── symlink-management.md
└── shared/
├── git-commit-types.md
└── rule-maintenance.md第三部分：实施结果
实际效果
提交记录
2025-10-15 完成实施：
主项目提交 (
094774f):- 重构 CLAUDE.md 为三层架构（468 行）
- 新增 4 个 Slash Commands
- 删除临时文件
docs 子项目提交 (
a85c39d):- 新增 rule-maintenance.md（280 行完整指南）
docs 修复提交 (
938a263):- 修复过时的规则体系说明
- 标注历史遗留文档
文件统计
| 类别 | 文件数量 | 总行数 |
|---|---|---|
| 第一层（内联） | 1 个文件 | 468 行 |
| 第二层（外部） | 17 个文件 | ~2000 行 |
| 第三层（Slash） | 4 个命令 | ~150 行 |
可靠性验证
| 层级 | 加载方式 | 可靠性 | 验证方法 |
|---|---|---|---|
| 第一层 | 自动内联 | 100% | AI 启动时自动加载 |
| 第二层 | 触发表引导 | ~85% | 任务关键词触发读取 |
| 第三层 | 用户主动 | 100% | Slash Command 显式触发 |
经验总结
✅ 有效的做法
基于可靠性分层
- 不按内容类型分层（通用/主项目/子项目）
- 按可靠性需求分层（100%/85%/100%）
- 这是设计突破的关键
实验驱动决策
- 用独立实例测试方案
- 不要基于假设做设计
- 快速迭代，敢于推翻错误方案
清晰的工作边界
- 第三层的核心不是"复杂度"
- 而是"用户有明确工作边界"
- 用户知道"我要做 X 任务"
任务触发规则表
- 明确告诉 AI "何时读取外部文件"
- 使用表格形式（任务 → 文件 → 场景）
- 提高第二层规则的加载可靠性
双层文档机制
- 核心决策流程内联（~30 行）
- 详细指南外部化（~280 行）
- 适用于规则维护本身
❌ 无效的做法
标注系统
[必读]、[XX任务时-必读]标注无效- AI 不会基于标注自动读取文件
- 必须用触发规则表或 Slash Command
@ 导入跨仓库
- 跨仓库导入不可靠
- 路径解析存在风险
- 核心内容必须内联
过度模块化
- 规则分散在多个文件
- 增加维护成本
- AI 无法自动关联
- 核心规则必须内联
按内容类型分层
- 通用规则、主项目规则、子项目规则
- 这种分类不能解决加载可靠性问题
- 必须按可靠性需求分层
🎯 最佳实践
对于 AI 上下文文件：
- 核心规则内联：100% 可靠性需求
- 触发表引导：中等可靠性需求
- 用户主动加载：复杂任务且有清晰工作边界
- 零冗余原则：每条规则只出现一次
- 高密度呈现：表格 > 列表 > 代码块 > 段落
对于团队协作：
- 实验先行：新方案先小范围测试
- 快速迭代：发现问题立即调整
- 勇于推翻：不要执着于错误方案
- 记录过程：保留决策依据（如本文档）
- 持续优化：根据使用反馈改进
对于文档维护：
- 定期检查：确保信息与实际一致
- 单一来源：避免多处重复维护
- 版本标注：记录最后更新日期
- 实际验证：测试 AI 是否正确理解
附录
迭代时间线
2025-10-13
├── 第一次尝试：模块化 + @ 导入
│ ├── 重命名 15 个文件
│ ├── 创建索引文件
│ └── 发现 @ 导入不可靠
2025-10-14 上午
├── 第二次尝试：标注系统 + 索引
│ ├── 创建带标注的索引
│ ├── 添加 AI 工作机制章节
│ └── 实验验证：标注系统无效
2025-10-14 下午
├── 第三次尝试：混合策略设计
│ ├── 提出三层架构概念
│ ├── 设计决策矩阵
│ └── 规划实施步骤
2025-10-15
└── 最终实施完成
├── 重构 CLAUDE.md（468 行）
├── 创建 4 个 Slash Commands
├── 新增 rule-maintenance.md
└── 修复过时文档关键转折点
- 放弃 @ 导入 → 认识到跨仓库引用不可靠
- 标注系统实验失败 → 核心规则必须内联
- 从内容分层到可靠性分层 → 设计思维的突破
- "工作边界"概念 → 第三层定义的澄清
参考资料
- Anthropic Claude Code 文档
- CLAUDE.md 最佳实践
- 项目内部实验记录和讨论
总结：
通过三次迭代，我们找到了适合 AI 的规则文档组织方式。关键洞察是按可靠性需求分层，而不是按内容类型。
- 第一层（100%）：核心规则内联，启动即生效
- 第二层（~85%）：详细规则外部化，触发表引导
- 第三层（100%）：复杂任务用户主动加载
这个架构经过实际验证，显著提升了 AI 的工作效率和准确性。
最后更新: 2025-10-15 维护者: WorldTourCasino Team