AI 代理的集中式规则结构

通过 CrystaCode 项目的单一来源架构强制 AI 代理遵守规则 AI 代理...

Dev.to · Jul 30, 2026

Centralized Rule Structures for AI Agents

通过 CrystaCode 项目的单一来源架构强制 AI 代理遵守规则

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 hook directive

Enter fullscreen mode Exit fullscreen mode

组件规格

主节点

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 文件修改请求。
评估目标参数：
文件扩展名根据目标参数（.scss，.razor）进行评估。不匹配的文件绕过拦截。
确定产品关联：
脚本评估目标文件路径以识别关联的项目模块。
查询会话数据：
脚本检查会话数据中是否存在与文件类型和模块对应的现有执行标记。如果存在，AI 将绕过拦截。
停止执行：
如果标记不存在，执行将被阻止。AI 将收到明确指令来解析所需的技能文档。
写入执行标记：
脚本将执行标记写入会话数据。同一会话中的后续修改尝试将不受干扰地进行。

拦截器实现逻辑
当会话标记不存在时，拦截机制会输出明确的错误指令来停止执行：

部署检查清单

if ($category -eq 'scss') {
    [Console]::Error.WriteLine(
        "MANDATORY styling gate: this is the first .scss edit in this session for the " +
        "'$product' product. Invoke the '$skill' skill (canonical rules: $doc), apply its " +
        "rules -- $checklist -- then retry this exact edit. $forbidden " +
        "This gate fires once per session per product per file category.")
} else {
    [Console]::Error.WriteLine(
        "MANDATORY component gate: this is the first .razor edit in this session for the " +
        "'$product' product. Before this edit: (1) invoke the '$skill' skill (canonical " +
        "rules: $doc) for color/typography/component conventions -- use $components. " +
        "(2) invoke the 'localize-app-strings' skill -- never hardcode user-facing text, " +
        "always route through IStringLocalizer<AppStrings>. Then retry this exact edit. " +
        "This gate fires once per session per product per file category.")
}