Back to Details

architecture-governance

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

通用架构治理规范

General Architecture Governance Specification

用于跨项目复用的架构基线，确保分层清晰、依赖可控、设计可演进。
An architecture baseline for cross-project reuse, ensuring clear layering, controllable dependencies, and evolvable design.

⚠️ 核心强制要求

⚠️ Core Mandatory Requirements

分层与依赖方向

Layering and Dependency Direction

  • 依赖方向必须单向流动（上层依赖下层，禁止反向依赖）
  • 禁止跨层直连，跨层能力通过上层服务或明确的应用接口暴露
  • 基础设施实现不得承载业务决策
  • Dependency direction must flow unidirectionally (upper layers depend on lower layers; reverse dependencies are prohibited)
  • Direct cross-layer connections are prohibited; cross-layer capabilities must be exposed through upper-layer services or explicit application interfaces
  • Infrastructure implementations must not carry business decisions

变更前影响面分析

Impact Analysis Before Changes

  • 修改代码前必须标注所在层、上下游调用方、受影响数据流
  • 任何接口变更必须明确兼容性策略（兼容、适配、版本化）
  • 变更后必须确认无新增循环依赖
  • Before modifying code, you must mark the layer it belongs to, upstream and downstream callers, and affected data flows
  • Any interface change must clearly define a compatibility strategy (compatible, adaptive, versioned)
  • After changes, you must confirm no new circular dependencies are introduced

接口契约与可替换性

Interface Contracts and Replaceability

  • 使用 Protocol/ABC 定义稳定契约
  • 通过构造函数依赖注入组装实现，禁止静态单例绑定
  • 可替换组件通过工厂/注册表与配置项切换
  • Use Protocol/ABC to define stable contracts
  • Assemble implementations via constructor dependency injection; static singleton binding is prohibited
  • Replaceable components are switched via factories/registries and configuration items

AI Agent 行为要求

AI Agent Behavior Requirements

改代码前

Before Modifying Code

  1. 说明改动所在层级与职责边界
  2. 说明影响的模块、接口、数据流
  3. 说明是否存在跨层/反向/循环依赖风险
  1. Explain the layer and responsibility boundary where the change is located
  2. Explain the affected modules, interfaces, and data flows
  3. Explain whether there are risks of cross-layer/reverse/circular dependencies

做设计或重构时

During Design or Refactoring

  1. 优先抽象稳定契约，再选择具体实现
  2. 采用依赖注入保持实现可替换
  3. 为潜在破坏性变更给出兼容方案
  1. Prioritize abstracting stable contracts before selecting specific implementations
  2. Use dependency injection to maintain implementability replacement
  3. Provide compatibility solutions for potentially destructive changes

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

Project Initialization Analysis (Project-level Assessment Scenario)

  1. 先做项目全景扫描：技术栈、目录结构、模块边界、依赖关系
  2. 明确业务目标与核心流程，识别关键组件、服务层与数据模型
  3. 以架构/质量/性能/安全/可扩展性五个维度输出评估结论
  4. 输出“优先级明确”的改进建议，避免一次性大改动
  1. First conduct a project panoramic scan: tech stack, directory structure, module boundaries, dependency relationships
  2. Clarify business objectives and core processes, identify key components, service layers, and data models
  3. Output evaluation conclusions from five dimensions: architecture/quality/performance/security/scalability
  4. Output "priority-clear" improvement suggestions, avoid one-time major changes

组合触发：联动 
single-responsibility

Combined Trigger: Link with 
single-responsibility

出现以下信号时，必须联动 
single-responsibility
：
  • 模块/类职责边界不清，难以一句话描述职责
  • 单个文件或类承担多种不相关职责
  • 需要给出拆分方案（文件级、类级、函数级）
联动顺序：
  1. 先用本 skill 确认层级边界与依赖方向
  2. 再用 
    single-responsibility
    设计职责拆分
  3. 最后回到本 skill 复核是否引入跨层或循环依赖
When the following signals appear, you must link with 
single-responsibility
:
  • Module/class responsibility boundaries are unclear, making it difficult to describe responsibilities in one sentence
  • A single file or class takes on multiple unrelated responsibilities
  • Provide splitting solutions (file-level, class-level, function-level)
Linkage Sequence:
  1. First use this skill to confirm layer boundaries and dependency directions
  2. Then use 
    single-responsibility
    to design responsibility splitting
  3. Finally return to this skill to review whether cross-layer or circular dependencies are introduced

高风险场景

High-Risk Scenarios

出现以下任一情况，必须升级给用户决策：
  • 架构分层调整或依赖方向改变
  • 核心接口破坏性变更
  • 数据流主路径重排
  • 对性能、容量或一致性有显著影响
If any of the following situations occur, you must escalate to the user for decision-making:
  • Adjustments to architecture layering or changes to dependency directions
  • Destructive changes to core interfaces
  • Rearrangement of main data flow paths
  • Significant impact on performance, capacity, or consistency

判断标准

Judgment Criteria

  • 是否可以清晰回答“这次改动在哪一层、影响谁、依赖谁”
  • 是否仍满足单向依赖且无循环依赖
  • 是否通过契约 + 注入 + 配置实现可替换
  • 若涉及职责拆分，是否已联动 
    single-responsibility
    并完成架构复核
  • Can you clearly answer "which layer this change is in, who it affects, who it depends on"
  • Does it still satisfy unidirectional dependencies and no circular dependencies
  • Is replaceability achieved through contracts + injection + configuration
  • If responsibility splitting is involved, has 
    single-responsibility
    been linked and architecture review completed

反模式（必须避免）

Anti-Patterns (Must Avoid)

  • 为了快速交付直接跨层调用底层实现
  • 在基础设施层写入业务规则
  • 直接改接口签名且无兼容策略
  • 在全局静态单例中硬编码具体实现
  • Directly calling underlying implementations across layers for quick delivery
  • Writing business rules in the infrastructure layer
  • Modifying interface signatures directly without a compatibility strategy
  • Hardcoding specific implementations in global static singletons

参考资料

Reference Materials

  • references/layering-and-dependencies.md
    - 分层与依赖方向基线
  • references/change-impact-analysis.md
    - 架构变更影响面分析模板
  • references/interface-di-and-pluggability.md
    - 契约、依赖注入与可插拔设计
  • references/project-initial-analysis.md
    - 项目初始化分析清单与评估维度（含可选命令模板）
  • references/layering-and-dependencies.md
    - Baseline for Layering and Dependency Direction
  • references/change-impact-analysis.md
    - Template for Architecture Change Impact Analysis
  • references/interface-di-and-pluggability.md
    - Contracts, Dependency Injection, and Pluggable Design
  • references/project-initial-analysis.md
    - Project Initialization Analysis Checklist and Evaluation Dimensions (including optional command templates)

路由说明

Routing Instructions

  • 架构分层、依赖方向、接口契约、DI、可插拔问题：优先触发本 skill。
  • 项目初始化分析、架构体检、配置基线检查：优先触发本 skill。
  • 职责拆分与边界澄清问题：联动 
    single-responsibility
    。
  • 仅局部职责优化且不改变架构边界时，可单独使用 
    single-responsibility
    。
  • For issues related to architecture layering, dependency direction, interface contracts, DI, and pluggability: trigger this skill first.
  • For project initialization analysis, architecture health checks, and configuration baseline checks: trigger this skill first.
  • For responsibility splitting and boundary clarification issues: link with 
    single-responsibility
    .
  • For local responsibility optimization that does not change architecture boundaries, 
    single-responsibility
    can be used independently.