AI 代理的集中式規則結構

透過 CrystaCode 專案中的單一來源架構，強制執行 AI 代理的遵循性 AI 代理...

Dev.to · Jul 30, 2026

Centralized Rule Structures for AI Agents

透過 CrystaCode 專案中的單一來源架構，強制執行 AI 代理的遵循性

AI 代理需要嚴格的目錄結構，才能在沒有邏輯分歧的情況下執行專案規則。規則重複會導致執行失敗。建立單一事實來源。在一個位置精確地定義每個規則。次要檔案僅作為路由參數運作。

系統架構

AGENTS.md                        # 主要入口檔案
CLAUDE.md                        # 指向 AGENTS.md 的指標

agents/
  rules/
    productA.md                  # 元件指令
    productB.md
  skills/
    styling-guidelines-a/SKILL.md
    styling-guidelines-b/SKILL.md
  hooks/
    styling-guard.ps1            # 攔截器執行腳本

docs/
  Conventions/
    ProductA/styling-guidelines.md   # 絕對規則文字
    ProductB/styling-guidelines.md

.claude/
  settings.json                  # Claude 鉤子指令
  skills/*/SKILL.md              # 自動產生的工件

.github/
  instructions/*.instructions.md # GitHub 代理指標
  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 檔案修改請求。
評估目標參數：
檔案副檔名會根據目標參數 (.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.")
}