合规规则 (Guardrails)
合规规则是确定性检查，用于根据您的架构决策验证代码变更。它们强制执行命名约定、技术约束、层边界和安全模式——无需任何 AI 参与。
在侧边栏中导航到 Agent Hub 来管理您的合规规则。
为什么需要合规规则？
当 AI 编码代理（Claude Code、Cursor、Copilot）生成代码时，它们不了解您的架构决策。合规规则将这些决策编码为可执行的约束：
- 如果您的技术雷达指定使用 PostgreSQL，代理不能使用 MongoDB
- 如果您的架构要求使用服务层，代理不能在 HTTP handler 中直接调用数据库
- 如果您的团队使用结构化日志，代理不能添加
fmt.Println
规则以确定性方式评估——没有 LLM，没有概率性输出。相同的代码始终产生相同的结果。
规则类型
Archyl 支持七种合规规则类型：
必需模式
检查代码中必须存在或不得存在的模式。
| 用例 | 示例 |
|---|---|
| 禁止调试日志 | 禁止 fmt.Println、console.log、print() |
| 禁止安全风险 | 禁止 eval()、innerHTML、硬编码密码 |
| 要求错误处理 | 要求 shell 脚本中使用 set -euo pipefail |
| 强制执行标准 | 禁止 SQL 查询中使用 SELECT * |
配置：
- File glob — 仅检查匹配模式的文件（例如
*.go、*.ts） - 禁止模式 — 发现时触发违规的正则表达式模式
- 必需模式 — 缺失时触发违规的正则表达式模式
命名约定
验证文件、类型和函数的命名模式。
| 范围 | 示例 |
|---|---|
| 文件 | Go 文件必须为 snake_case.go |
| 类型 | 导出类型必须为 PascalCase |
| 函数 | 函数应以动词开头（Get、Create、Delete） |
配置：
- 模式 — 范围（文件/类型/函数）+ 正则表达式 + 描述的列表
技术约束
限制容器中允许使用的语言和库。
| 用例 | 示例 |
|---|---|
| 语言锁定 | 后端只能使用 Go |
| 依赖禁止 | 不使用 lodash（使用原生 JS） |
| 迁移强制 | 不使用 moment.js（使用 date-fns） |
配置：
- 允许的语言 — 逗号分隔的列表（例如
go, typescript） - 禁止的导入 — 每行一个导入
层边界
强制执行 Clean Architecture、六边形架构或 DDD 层导入规则。
| 层 | 可以从以下导入 |
|---|---|
| Domain | 无（纯业务逻辑） |
| Service | 仅 Domain |
| Adapter | Domain、Service |
| Infrastructure | 仅 Domain |
配置：
- 层 — 为每个层定义名称、路径模式（glob）和允许的导入来源
- 点击层名称以切换导入权限
契约合规
验证代码端点是否与存储在 Archyl 中的 API 契约匹配。
配置：
- 契约类型 — HTTP (OpenAPI)、gRPC、GraphQL 或 AsyncAPI
- 端点文件模式 — 包含端点定义的文件的 glob
- 严格模式 — 启用时，任何不在契约中的端点都会触发违规
依赖规则
确保组件间的依赖关系与 C4 关系模型匹配。
配置：
- 范围 — 容器级或组件级
- 要求关系存在 — 每个代码导入必须有对应的 C4 关系
- 禁止对 — 永远不应相互依赖的特定元素对
事件通道合规
验证代码中的事件生产者/消费者是否与声明的 EventChannel 匹配。
配置：
- 生产者模式 — 识别事件生产代码的正则表达式模式
- 消费者模式 — 识别事件消费代码的正则表达式模式
- Topic 正则 — 从代码中提取 topic 名称的模式
规则包
规则包是精心策划的规则集合，您可以一键安装。无需逐条添加规则，安装一个规则包即可获得适合您技术栈的完整规则集。
点击工具栏中的 Packs 浏览可用的规则包。
架构包
| 包 | 规则数 | 强制内容 |
|---|---|---|
| Clean Architecture | 5 | domain/service/adapter/infra 层边界，模块隔离 |
| Hexagonal Architecture | 4 | Ports & Adapters 模式，核心隔离 |
| Domain-Driven Design | 3 | DDD 层，CQRS 命令/查询分离 |
语言包
| 包 | 规则数 | 覆盖内容 |
|---|---|---|
| Go Backend | 26 | 错误包装、goroutine 安全性、上下文传播、命名、禁止 panic、禁止 init() |
| React Frontend | 23 | TypeScript 严格性、组件模式、数据获取、禁止 DOM 操作 |
| Next.js Full-Stack | 20 | React 规则 + SSR 安全性、window 守卫、localStorage 钩子 |
| Python Backend | 16 | 异常处理、async 模式、类型提示、禁止全局状态 |
| Java Backend | 11 | Spring DI 模式、异常处理、禁止 System.exit |
| Rust Backend | 8 | 禁止 unwrap/unsafe、正确的错误类型、禁止 todo!() |
| Kotlin / Android | 5 | null 安全性、不可变性、禁止 println |
| Vue Frontend | 10 | 禁止 v-html、TypeScript 严格性、禁止 innerHTML |
| .NET / C# Backend | 5 | async 模式、异常处理、ILogger |
| Swift / iOS | 3 | Optional 安全性、禁止强制解包 |
领域包
| 包 | 规则数 | 覆盖内容 |
|---|---|---|
| Security Essentials | 17 | 硬编码密钥、注入、弱加密、TLS、CORS |
| DevOps & Infrastructure | 24 | Docker、Kubernetes、Terraform、GitHub Actions、shell 脚本 |
| API Best Practices | 9 | 状态码、SQL 安全性、契约文档、禁止硬编码 URL |
| Testing & Reliability | 5 | 禁止跳过测试、禁止 .only()、禁止 sleep、禁止 TODO |
| Event-Driven Architecture | 3 | Kafka/RabbitMQ 主题命名、禁止硬编码主题 |
规则目录
Archyl 提供了一个包含 170+ 条预构建规则的目录，涵盖 24 种技术。在 Agent Hub 中点击 Catalog 浏览目录。
涵盖的技术
Go、TypeScript、JavaScript、Python、Java、Kotlin、Rust、C#、C/C++、Ruby、PHP、Swift、React、Vue、Angular、Next.js、Docker、Kubernetes、Terraform、SQL、Shell、YAML、GitHub Actions
类别
| 类别 | 示例 |
|---|---|
| Architecture & Design | Clean Architecture、Hexagonal、DDD、MVC、handler-service-repository |
| 安全 | 无硬编码密钥、无 eval()、无 SQL 注入、无禁用 TLS、无 CORS 通配符 |
| 代码质量 | 无调试日志、无空 catch 块、无 bare except、无 any 类型、无 unwrap() |
| Infrastructure & DevOps | 固定 Docker 版本、K8s 资源限制、无特权容器、Terraform 标签 |
| 命名约定 | snake_case、PascalCase、camelCase（按语言区分） |
| 测试与可靠性 | 无跳过的测试、无 .only()、无 TODO/FIXME |
| 性能 | 无同步 sleep、无 N+1 查询、无循环中的 await |
| API 与数据 | 无原始 SQL、正确的 HTTP 状态码、验证请求体 |
点击目录中的任何规则即可添加——配置表单会自动预填充。
严重级别
每条规则都有一个决定其影响的严重级别：
| 严重级别 | 含义 | 示例 |
|---|---|---|
| Critical | 合并前必须修复 | 无硬编码密钥、无 eval()、层边界违规 |
| High | 合并前应该修复 | 无调试日志、固定 Docker 版本、Go 中无 panic |
| Medium | 方便时修复 | 命名约定、无 any 类型、JS 中无 var |
| Low | 信息性 | 无 TODO/FIXME、React 中无内联样式 |
规则管理
创建规则
- 点击 Packs 安装适合您技术栈的精选规则包，或
- 点击 Catalog 从 170+ 条预构建规则中浏览和添加，或
- 点击 Custom 手动创建新规则
启用/禁用规则
切换任何规则旁边的开关以启用或禁用它。禁用的规则不会被评估。
编辑规则
点击任何规则上的编辑图标（铅笔）以修改其名称、描述、严重级别或配置。
删除规则
点击删除图标（垃圾桶），然后确认。此操作无法撤销。
筛选规则
- 搜索 — 按规则名称或描述筛选
- 类型筛选 — 点击类型标签仅显示特定类型的规则
CI/CD 集成
合规规则可以在每个拉取请求上自动运行。请参阅 GitHub Actions 集成 了解设置说明。
工作原理
- 在 GitHub 上打开或更新 PR
- Archyl GitHub Action 获取更改的文件
- 文件被发送到 Archyl API 进行评估
- 结果以 PR 评论和提交状态的形式显示
- 如果发现 Critical 或 High 级别的违规，工作流将失败
PR 评论
当发现违规时，Archyl 会在 PR 上发布详细评论：
- 按严重级别统计违规数量的摘要表
- 每个文件的违规详情，包含描述和建议
- 评论在后续推送时更新（不会重复创建）
MCP 集成
合规规则可通过 MCP 服务器供 AI 代理访问：
可用的 MCP 工具
| 工具 | 描述 |
|---|---|
list_conformance_rules |
列出所有规则，支持按项目可选筛选 |
create_conformance_rule |
创建新规则 |
update_conformance_rule |
更新规则配置、严重级别或启用状态 |
delete_conformance_rule |
删除规则 |
get_agent_context |
获取包含活跃 guardrails 的完整架构上下文 |
代理上下文
MCP 工具 get_agent_context 会返回所有活跃的合规规则作为架构简报的一部分。在开始工作前调用此工具的 AI 代理将了解需要遵守哪些 guardrails。
上下文还包括：
- C4 model（系统、容器、组件、关系）
- 带有理由的活跃 ADR
- 技术栈
- API 契约
- 事件通道
REST API
合规规则也可通过 REST API 获取：
GET /api/v1/conformance/rules # 列出规则
POST /api/v1/conformance/rules # 创建规则
POST /api/v1/conformance/rules/bulk # 批量创建规则（规则包使用）
GET /api/v1/conformance/rules/:id # 获取规则
PUT /api/v1/conformance/rules/:id # 更新规则
DELETE /api/v1/conformance/rules/:id # 删除规则
POST /api/v1/conformance/rules/:id/toggle # 启用/禁用
POST /api/v1/projects/:id/conformance/check # 使用变更文件触发检查
GET /api/v1/projects/:id/conformance/checks # 列出检查历史
GET /api/v1/conformance/checks/:id/report # 获取检查报告
GET /api/v1/projects/:id/conformance/stats # 获取项目统计
所有端点都需要身份验证（JWT 或具有写入范围的 API 密钥用于变更操作）。