---
name: architecture-governance
description: 通用架构治理规范，提供分层约束、影响面分析、接口契约与依赖注入基线。适用于任何多层系统的架构评审、重构与新模块设计。
metadata:
  type: declarative
  category: architecture
  scope: generic
  role: primary-entry
  related_skills:
    - single-responsibility
  derived_from:
    - architecture-cognition
    - architecture-design
---

# 通用架构治理规范

> 用于跨项目复用的架构基线，确保分层清晰、依赖可控、设计可演进。

---

## ⚠️ 核心强制要求

### 分层与依赖方向

- 依赖方向必须单向流动（上层依赖下层，禁止反向依赖）
- 禁止跨层直连，跨层能力通过上层服务或明确的应用接口暴露
- 基础设施实现不得承载业务决策

### 变更前影响面分析

- 修改代码前必须标注所在层、上下游调用方、受影响数据流
- 任何接口变更必须明确兼容性策略（兼容、适配、版本化）
- 变更后必须确认无新增循环依赖

### 接口契约与可替换性

- 使用 Protocol/ABC 定义稳定契约
- 通过构造函数依赖注入组装实现，禁止静态单例绑定
- 可替换组件通过工厂/注册表与配置项切换

---

## AI Agent 行为要求

### 改代码前

1. 说明改动所在层级与职责边界
2. 说明影响的模块、接口、数据流
3. 说明是否存在跨层/反向/循环依赖风险

### 做设计或重构时

1. 优先抽象稳定契约，再选择具体实现
2. 采用依赖注入保持实现可替换
3. 为潜在破坏性变更给出兼容方案

### 项目初始化分析（项目级评估场景）

1. 先做项目全景扫描：技术栈、目录结构、模块边界、依赖关系
2. 明确业务目标与核心流程，识别关键组件、服务层与数据模型
3. 以架构/质量/性能/安全/可扩展性五个维度输出评估结论
4. 输出“优先级明确”的改进建议，避免一次性大改动

### 组合触发：联动 `single-responsibility`

出现以下信号时，必须联动 `single-responsibility`：

- 模块/类职责边界不清，难以一句话描述职责
- 单个文件或类承担多种不相关职责
- 需要给出拆分方案（文件级、类级、函数级）

联动顺序：

1. 先用本 skill 确认层级边界与依赖方向
2. 再用 `single-responsibility` 设计职责拆分
3. 最后回到本 skill 复核是否引入跨层或循环依赖

### 高风险场景

出现以下任一情况，必须升级给用户决策：

- 架构分层调整或依赖方向改变
- 核心接口破坏性变更
- 数据流主路径重排
- 对性能、容量或一致性有显著影响

---

## 判断标准

- 是否可以清晰回答“这次改动在哪一层、影响谁、依赖谁”
- 是否仍满足单向依赖且无循环依赖
- 是否通过契约 + 注入 + 配置实现可替换
- 若涉及职责拆分，是否已联动 `single-responsibility` 并完成架构复核

---

## 反模式（必须避免）

- 为了快速交付直接跨层调用底层实现
- 在基础设施层写入业务规则
- 直接改接口签名且无兼容策略
- 在全局静态单例中硬编码具体实现

---

## 参考资料

- `references/layering-and-dependencies.md` - 分层与依赖方向基线
- `references/change-impact-analysis.md` - 架构变更影响面分析模板
- `references/interface-di-and-pluggability.md` - 契约、依赖注入与可插拔设计
- `references/project-initial-analysis.md` - 项目初始化分析清单与评估维度（含可选命令模板）

---

## 路由说明

- 架构分层、依赖方向、接口契约、DI、可插拔问题：优先触发本 skill。
- 项目初始化分析、架构体检、配置基线检查：优先触发本 skill。
- 职责拆分与边界澄清问题：联动 `single-responsibility`。
- 仅局部职责优化且不改变架构边界时，可单独使用 `single-responsibility`。