集中式规则结构
在 CrystaCode 项目中，为了让 AI 智能体严格遵循项目规则、避免逻辑混乱，需要设定一套严格的目录结构。规则重复会导致执行失败，因此要建立单一事实来源：每条规则只定义在一个位置，辅助文件仅作为路由参数。
系统架构
AGENTS.md # Primary entry file
CLAUDE.md # Pointer to AGENTS.md
agents/
rules/
productA.md # Component directives
productB.md
skills/
styling-guidelines-a/SKILL.md
styling-guidelines-b/SKILL.md
hooks/
styling-guard.ps1 # Interceptor execution script
docs/
Conventions/
ProductA/styling-guidelines.md # Absolute rule text
ProductB/styling-guidelines.md
.claude/
settings.json # Claude hook directive
skills/*/SKILL.md # Auto-generated artifacts
.github/
instructions/*.instructions.md # GitHub agent pointers
集中式规则结构
hooks/preToolUse.json # GitHub 钩子指令
组件规范
主节点
AGENTS.md：必填的初始化文件，包含路由矩阵，列出文件扩展名触发规则，并将它们映射到对应的文档。
重定向节点
CLAUDE.md：只含一条指令，让解析器去读取 AGENTS.md。
.github/instructions/：让 GitHub Copilot 指向各模块专属规则。
操作指令
agents/rules/：与具体项目模块对应的独立操作步骤和检查清单，其规则定义委托给 skills 目录。
agents/skills/：上下文触发条件，明确指定操作的前置条件，其规则正文委托给 docs/ 仓库。
绝对文档
docs/：最终权威仓库，包含完整技术规范和规则正文，是定义规则的唯一位置。
自动镜像
.claude/skills/：agents/skills 的自动镜像，严禁手动修改。
拦截器脚本协议
styling-guard.ps1 钩子通过检查会话标记来拦截 AI 文件的修改请求，以确保合规。
- 拦截请求：脚本在 AI 修改文件之前进行拦截。
- 评估目标参数：检查文件扩展名是否符合目标参数（
.scss、.razor）。不符合的文件直接放行。 - 确定关联产品：解析文件路径，判断该文件属于哪个项目模块。
- 查询会话数据：检查是否有该文件类型与模块对应的已执行标记。如果标记存在，AI 直接跳过拦截。
- 暂停执行：如果标记不存在，则阻止执行。AI 会收到明确指令，要求先阅读所需的技能文档。
- 写入执行标记：脚本将执行标记写入会话数据。之后同一会话内的后续修改请求不再被拦截。