通用架构治理规范

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

⚠️ 核心强制要求

分层与依赖方向

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

变更前影响面分析

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

接口契约与可替换性

• 使用 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。