通用架构治理规范

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

⚠️ 核心强制要求

分层与依赖方向

• 依赖方向必须单向流动（上层依赖下层，禁止反向依赖）

• 禁止跨层直连，跨层能力通过上层服务或明确的应用接口暴露

• 基础设施实现不得承载业务决策

变更前影响面分析

• 修改代码前必须标注所在层、上下游调用方、受影响数据流

• 任何接口变更必须明确兼容性策略（兼容、适配、版本化）

• 变更后必须确认无新增循环依赖

接口契约与可替换性

• 使用 Protocol/ABC 定义稳定契约

• 通过构造函数依赖注入组装实现，禁止静态单例绑定

• 可替换组件通过工厂/注册表与配置项切换

AI Agent 行为要求

改代码前

• 说明改动所在层级与职责边界

• 说明影响的模块、接口、数据流

• 说明是否存在跨层/反向/循环依赖风险

做设计或重构时

• 优先抽象稳定契约，再选择具体实现

• 采用依赖注入保持实现可替换

• 为潜在破坏性变更给出兼容方案

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

• 先做项目全景扫描：技术栈、目录结构、模块边界、依赖关系

• 明确业务目标与核心流程，识别关键组件、服务层与数据模型

• 以架构/质量/性能/安全/可扩展性五个维度输出评估结论

• 输出“优先级明确”的改进建议，避免一次性大改动

组合触发：联动 single-responsibility

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

• 模块/类职责边界不清，难以一句话描述职责

• 单个文件或类承担多种不相关职责

• 需要给出拆分方案（文件级、类级、函数级）

联动顺序：

• 先用本 skill 确认层级边界与依赖方向

• 再用 single-responsibility 设计职责拆分

• 最后回到本 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 。