本页目录

本页目录

架构治理

架构不变量

在 ARCHITECTURE.md 中明确记录架构边界和不变量,防止 AI Agent 无意间打破它们。

常见内容包括:

  • 领域逻辑属于哪一层
  • 哪些模块可以调用外部 API
  • 认证边界
  • 状态管理边界
  • Databricks 访问边界
  • 前后端职责划分
  • 依赖方向
  • 集成边界

ARCHITECTURE.md 应保持简短,专注回答一个问题:

当前架构有哪些事实必须始终成立?

何时必须编写该文档,见必备项目文档。

架构决策记录

每项重大架构决策都应使用共享的 ADR 模板 单独记录。

一篇 ADR 应包含:

  • 背景
  • 决策
  • 考虑过的替代方案
  • 理由
  • 后果

ADR 用于防止贡献者和 AI Agent 无意间改动架构;架构决策需要改变时,也可以修订 ADR。

当用户请求与某项 ADR 冲突时:

  1. 理解用户的真实意图。
  2. 弄清该 ADR 存在的原因。
  3. 评估修改该决策的影响。
  4. 在合理的情况下,优先选择与既有架构兼容的方案。
  5. 如果架构确实需要变更,说明其影响。
  6. 明确更新或废止该 ADR。

禁止悄悄违反 ADR。

当用户不确定架构是否应当改动时,先帮助用户分析后果,再实施变更。