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

• 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 Behavior Requirements

Before Modifying Code

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. 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. 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

Combined Trigger: Link with

single-responsibility

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)

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

• 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

• 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

  - 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

• 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.