Back to Details

architecture-validate-architecture

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Validate Architecture

架构验证

Table of Contents

目录

Quick Start → When to Use | What It Does | Simple Example
How to Implement → Validation Process | Architecture Rules | Expected Output
Patterns → Clean Architecture | Hexagonal | Layered | MVC
Help → Anti-Patterns | Troubleshooting | Integration
Reference → Layer Dependencies | Diff-Aware Validation | Quick Reference
快速开始 → 适用场景 | 功能说明 | 简单示例
如何实现 → 验证流程 | 架构规则 | 预期输出
支持的架构模式 → Clean Architecture | 六边形架构 | 分层架构 | MVC
帮助中心 → 反模式检测 | 问题排查 | 集成方案
参考文档 → 层依赖规则 | 差异感知验证 | 快速参考

Purpose

功能说明

Automates architecture validation for multiple architectural patterns (Clean Architecture, Hexagonal, Layered, MVC). Automatically detects the project's architectural style from ARCHITECTURE.md, scans all source files for import violations, validates dependency direction (inward only for Clean/Hexagonal), and reports violations with specific fixes. Adapts to any architectural pattern and provides actionable remediation guidance.
可自动完成多种架构模式（Clean Architecture、Hexagonal、分层架构、MVC）的架构验证，能从ARCHITECTURE.md自动识别项目的架构风格，扫描所有源文件的导入违规问题，验证依赖方向（Clean/Hexagonal架构仅允许向内依赖），并附带具体修复方案输出违规报告。它可适配任意架构模式，并提供可落地的修复指导。

Quick Start

快速开始

User asks: "Validate my architecture" or "Check if this follows Clean Architecture"
What happens:
  1. Reads project's 
    ARCHITECTURE.md
    to identify architectural pattern
  2. Scans all source files for import violations
  3. Validates dependency direction (inward only for Clean/Hexagonal)
  4. Reports violations with file:line:fix recommendations
Result: ✅ All checks passed OR ❌ Violations with specific fixes
用户诉求："验证我的架构" 或者 "检查是否符合Clean Architecture规范"
执行流程：
  1. 读取项目的
    ARCHITECTURE.md
    识别架构模式
  2. 扫描所有源文件的导入违规问题
  3. 验证依赖方向（Clean/Hexagonal架构仅允许向内依赖）
  4. 输出违规报告，包含文件路径、行号、修复建议
结果：✅ 所有检查通过 或者 ❌ 附带具体修复方案的违规列表

When to Use This Skill

适用场景

Invoke this skill when:
  • User asks "validate architecture", "check layer boundaries", "architectural review"
  • Before major refactoring or structural changes
  • As part of pre-commit quality gates
  • After adding new dependencies to any layer
  • Reviewing code for architecture compliance
  • User mentions "Clean Architecture", "Hexagonal", "Layered", or "MVC"
在以下场景调用本工具：
  • 用户要求"验证架构"、"检查层边界"、"架构评审"
  • 重大重构或结构调整前
  • 作为pre-commit质量门禁的一部分
  • 任意层新增依赖后
  • 代码评审时检查架构合规性
  • 用户提及"Clean Architecture"、"Hexagonal"、"分层架构"或"MVC"

Triggers

触发关键词

Trigger with phrases like:
  • "validate architecture"
  • "check layer boundaries"
  • "architectural review"
  • "validate my Clean Architecture"
  • "check if this follows Hexagonal Architecture"
  • "run architecture validation"
  • "check for layer violations"
  • "validate dependencies"
  • "architectural compliance check"
可通过以下短语触发：
  • "validate architecture"
  • "check layer boundaries"
  • "architectural review"
  • "validate my Clean Architecture"
  • "check if this follows Hexagonal Architecture"
  • "run architecture validation"
  • "check for layer violations"
  • "validate dependencies"
  • "architectural compliance check"

What This Skill Does

工具能力

Supported Architectural Patterns

支持的架构模式

This skill automatically adapts to:
  1. Clean Architecture (Concentric layers: Domain → Application → Infrastructure → Interface)
  2. Hexagonal Architecture (Ports and Adapters)
  3. Layered Architecture (Presentation → Business → Data)
  4. MVC (Model → View → Controller)
本工具可自动适配以下架构：
  1. Clean Architecture（同心层：Domain → Application → Infrastructure → Interface）
  2. Hexagonal Architecture（端口与适配器模式）
  3. 分层架构（Presentation → Business → Data）
  4. MVC（Model → View → Controller）

Validation Checks

验证检查项

1. Pattern Detection
  • Reads 
    ARCHITECTURE.md
    or similar documentation
  • Identifies architectural style and layer definitions
  • Parses dependency rules and constraints
2. Layer Boundary Validation
  • Scans all import statements in source files
  • Checks for violations (e.g., Domain importing Infrastructure)
  • Detects circular dependencies between layers
3. Dependency Direction Validation
  • Verifies dependencies flow correctly (inward for Clean/Hexagonal)
  • Ensures outer layers depend on inner, never reverse
  • Validates domain/core has no external dependencies
4. Pattern Compliance
  • Checks for required patterns (ServiceResult, Repository, etc.)
  • Verifies naming conventions (Services in application/, etc.)
  • Validates file organization matches architectural layers
5. Anti-Pattern Detection
  • Domain importing database/framework code
  • Application importing concrete infrastructure
  • Circular dependencies between layers
  • Business logic in interface/presentation layers
1. 架构模式识别
  • 读取
    ARCHITECTURE.md
    或同类文档
  • 识别架构风格和层定义
  • 解析依赖规则和约束
2. 层边界验证
  • 扫描源文件中的所有导入语句
  • 检查违规问题（例如Domain层导入Infrastructure层）
  • 检测层之间的循环依赖
3. 依赖方向验证
  • 验证依赖流向是否正确（Clean/Hexagonal架构仅允许向内依赖）
  • 确保外层依赖内层，禁止反向依赖
  • 验证domain/core层无外部依赖
4. 模式合规性检查
  • 检查必填模式（ServiceResult、Repository等）是否存在
  • 验证命名规范（例如Service类需放在application/目录下等）
  • 验证文件组织方式是否符合架构分层要求
5. 反模式检测
  • Domain层导入数据库/框架代码
  • Application层导入具体的基础设施实现
  • 层之间的循环依赖
  • 业务逻辑写在interface/presentation层

Instructions

使用说明

Overview

概述

Validating architecture involves a 5-step process:
  1. Identify Architecture - Read ARCHITECTURE.md and detect pattern (Clean, Hexagonal, Layered, MVC)
  2. Extract Layer Definitions - Map directory structure to architectural layers
  3. Scan Imports - Analyze all import statements in source files
  4. Validate Rules - Check dependency direction and layer boundaries
  5. Report Violations - Generate actionable report with specific fixes
See detailed steps in Validation Process section below.
架构验证包含5个步骤：
  1. 识别架构 - 读取ARCHITECTURE.md并检测架构模式（Clean、Hexagonal、分层、MVC）
  2. 提取层定义 - 将目录结构映射到架构层
  3. 扫描导入语句 - 分析源文件中的所有导入语句
  4. 规则验证 - 检查依赖方向和层边界
  5. 违规报告 - 生成附带具体修复方案的可落地报告
可查看下方验证流程章节了解详细步骤。

Validation Process

验证流程

The validation process follows 5 steps:
  1. Identify Architecture - Read ARCHITECTURE.md and detect pattern (Clean, Hexagonal, Layered, MVC)
  2. Extract Layer Definitions - Map directory structure to architectural layers
  3. Scan Imports - Analyze all import statements in source files
  4. Validate Rules - Check dependency direction and layer boundaries
  5. Report Violations - Generate actionable report with specific fixes
See Code Examples for detailed examples of each step, including bash commands, layer definitions, validation rules, and sample output formats.
验证流程遵循5个步骤：
  1. 识别架构 - 读取ARCHITECTURE.md并检测架构模式（Clean、Hexagonal、分层、MVC）
  2. 提取层定义 - 将目录结构映射到架构层
  3. 扫描导入语句 - 分析源文件中的所有导入语句
  4. 规则验证 - 检查依赖方向和层边界
  5. 违规报告 - 生成附带具体修复方案的可落地报告
查看代码示例了解每个步骤的详细示例，包括bash命令、层定义、验证规则和示例输出格式。

Usage Examples

使用示例

Example 1: Validate Entire Codebase

示例1：验证全量代码库

User: "Validate architecture before I commit"
  • Reads ARCHITECTURE.md and identifies pattern
  • Scans all source files for imports
  • Validates each layer's imports against rules
  • Reports violations or confirms compliance
用户："在我提交前验证架构"
  • 读取ARCHITECTURE.md识别架构模式
  • 扫描所有源文件的导入语句
  • 对照规则验证每个层的导入是否合规
  • 输出违规报告或确认合规

Example 2: Validate Specific Changes

示例2：验证变更内容

User: "Check if my refactoring follows Clean Architecture"
  • Runs git diff to find changed files
  • Filters to source files only
  • Validates only modified files
  • Reports violations in changed code
用户："检查我的重构是否符合Clean Architecture规范"
  • 执行git diff查找变更文件
  • 过滤仅保留源文件
  • 仅验证修改过的文件
  • 输出变更代码中的违规问题

Example 3: Pre-Commit Hook Integration

示例3：Pre-commit钩子集成

Automatically invoked by pre-commit hook to validate architectural boundaries, block commits if critical violations found, and provide actionable fix recommendations.
可被pre-commit钩子自动调用验证架构边界，若发现严重违规则阻止提交，并提供可落地的修复建议。

Architecture-Specific Rules

架构专属规则

This skill supports four architectural patterns with specific dependency rules:
本工具支持四种架构模式的专属依赖规则：

Clean Architecture

Clean Architecture

  • Dependency Rule: Dependencies flow inward only (Interface → Application → Domain ← Infrastructure)
  • Layer Rules: Domain is pure, Application orchestrates, Infrastructure implements, Interface is entry points
  • 依赖规则：仅允许向内依赖（Interface → Application → Domain ← Infrastructure）
  • 层规则：Domain层为纯逻辑，Application层负责编排，Infrastructure层负责实现，Interface层为入口

Hexagonal Architecture

Hexagonal Architecture

  • Dependency Rule: Core has no dependencies, adapters depend on ports
  • Layer Rules: Domain/Core is pure, Ports are interfaces, Adapters connect to external systems
  • 依赖规则：核心无任何依赖，适配器依赖端口
  • 层规则：Domain/Core层为纯逻辑，端口为接口，适配器负责连接外部系统

Layered Architecture

分层架构

  • Dependency Rule: Each layer depends only on layer below
  • Layer Rules: Presentation → Business Logic → Data Access
  • 依赖规则：每一层仅依赖下一层
  • 层规则：Presentation层 → 业务逻辑层 → 数据访问层

MVC Architecture

MVC架构

  • Dependency Rule: Model is independent, View/Controller depend on Model
  • Layer Rules: Model is independent, View depends on Model, Controller orchestrates
See Code Examples for detailed dependency diagrams, layer rules, and detection patterns for each architectural pattern.
  • 依赖规则：Model独立，View/Controller依赖Model
  • 层规则：Model独立，View依赖Model，Controller负责编排
查看代码示例了解每种架构模式的详细依赖图、层规则和识别模式。

Common Anti-Patterns Detected

可检测的常见反模式

This skill detects and provides fixes for common architectural violations:
  1. Domain Importing Infrastructure - Domain layer importing database/framework code
  2. Application Importing Interfaces - Application layer importing from API/UI layers
  3. Circular Dependencies - Two or more modules importing each other
  4. Business Logic in Interface Layer - Business rules and validation in API/UI code
See Code Examples for detailed violation examples with complete before/after code showing how to fix each anti-pattern using dependency inversion, repository patterns, and proper layering.
本工具可检测常见架构违规问题并提供修复方案：
  1. Domain层导入Infrastructure层 - Domain层导入数据库/框架代码
  2. Application层导入Interface层 - Application层从API/UI层导入内容
  3. 循环依赖 - 两个或多个模块互相导入
  4. 接口层存在业务逻辑 - API/UI代码中包含业务规则和校验逻辑
查看代码示例了解详细的违规示例，包含完整的代码修改前后对比，展示如何通过依赖倒置、仓储模式和合理分层修复每个反模式。

Integration Points

集成方案

This skill integrates with:
  • Pre-Commit Hooks - Block commits with architecture violations
  • CI/CD Pipeline - Automated validation in GitHub Actions, GitLab CI
  • Quality Gates - Part of comprehensive quality checks
See Code Examples for complete integration scripts for pre-commit hooks, CI/CD workflows, and quality gate configurations.
本工具可与以下系统集成：
  • Pre-commit钩子 - 阻止存在架构违规的提交
  • CI/CD流水线 - 可在GitHub Actions、GitLab CI中自动执行验证
  • 质量门禁 - 作为全量质量检查的一部分
查看代码示例获取pre-commit钩子、CI/CD工作流和质量门禁配置的完整集成脚本。

Supporting Files

配套文件

  • references/reference.md - Complete layer dependency matrices for all patterns
  • references/code-examples.md - All code examples, detection patterns, and integration scripts
  • references/diff-aware-validation.md - Diff-aware validation comprehensive guide
  • references/diff-aware-validation-summary.md - Diff-aware validation summary
  • references/diff-aware-validation-checklist.md - Pre-commit validation checklist
  • references/diff-aware-validation-quickref.md - Quick reference for diff-aware validation
  • references/installation.md - Installation and integration guide
  • scripts/validate.py - Standalone validation script for all architectural patterns
  • templates/arch-rules.yaml - Customizable rule definitions
  • references/reference.md - 所有模式的完整层依赖矩阵
  • references/code-examples.md - 所有代码示例、识别模式和集成脚本
  • references/diff-aware-validation.md - 差异感知验证完整指南
  • references/diff-aware-validation-summary.md - 差异感知验证摘要
  • references/diff-aware-validation-checklist.md - Pre-commit验证检查清单
  • references/diff-aware-validation-quickref.md - 差异感知验证快速参考
  • references/installation.md - 安装和集成指南
  • scripts/validate.py - 支持所有架构模式的独立验证脚本
  • templates/arch-rules.yaml - 可自定义的规则定义

Expected Outcomes

预期输出

Success (No Violations)

验证通过（无违规）

When validation passes, you'll see confirmation that all layer boundaries are respected and dependencies flow correctly.
验证通过时，你会收到确认信息，表明所有层边界都已遵守，依赖流向正确。

Failure (Violations Found)

验证失败（发现违规）

When violations are detected, you'll receive a detailed report including:
  • Violation severity (CRITICAL, HIGH, MEDIUM, LOW)
  • File path and line number
  • Specific import statement causing the violation
  • Recommended fix with explanation
  • Impact assessment
See Code Examples for complete example output showing success and failure reports with detailed violation listings.
检测到违规时，你会收到详细报告，包含：
  • 违规严重程度（CRITICAL、HIGH、MEDIUM、LOW）
  • 文件路径和行号
  • 导致违规的具体导入语句
  • 附带解释的推荐修复方案
  • 影响评估
查看代码示例获取完整的输出示例，包含成功和失败报告，以及详细的违规列表。

Success Metrics

效果指标

After invoking this skill, measure:
  • Violation Detection Rate: 95%+ (catches all major violations)
  • False Positive Rate: <5% (minimal incorrect reports)
  • Context Reduction: 90%+ vs manual agent review
  • Execution Time: <2s for typical codebase
  • Actionability: 100% of violations include specific fix
调用本工具后，可衡量以下指标：
  • 违规检测率：95%+（可捕获所有重大违规）
  • 误报率：<5%（错误报告极少）
  • 上下文精简率：相比人工Agent评审提升90%+
  • 执行时间：常规代码库<2秒
  • 可落地性：100%的违规都附带具体修复方案

Customization

自定义配置

Define Custom Rules

定义自定义规则

Create 
arch-rules.yaml
in project root to customize layer paths, import rules, severity levels, and exceptions for your project's specific architectural needs.
在项目根目录创建
arch-rules.yaml
，可自定义层路径、导入规则、严重级别和例外情况，满足项目的专属架构需求。

Language Support

语言支持

Currently supports Python (
.py
), JavaScript (
.js
), and TypeScript (
.ts
). Extend by adding patterns in 
scripts/validate.py
.
See templates/arch-rules.yaml for a complete example configuration with all available options and Code Examples for YAML configuration samples.
当前支持Python（
.py
）、JavaScript（
.js
）和TypeScript（
.ts
）。可在
scripts/validate.py
中添加模式扩展支持其他语言。
查看templates/arch-rules.yaml获取包含所有可用选项的完整配置示例，查看代码示例获取YAML配置样例。

Troubleshooting

问题排查

Issue: False Positives

问题：误报

Valid imports flagged as violations. Add exceptions to 
arch-rules.yaml
.
合法导入被标记为违规。可在
arch-rules.yaml
中添加例外规则。

Issue: Pattern Not Detected

问题：未识别架构模式

Skill doesn't recognize architectural pattern. Ensure 
ARCHITECTURE.md
contains pattern keywords: "Clean Architecture", "Hexagonal Architecture", "Layered Architecture", or "MVC".
工具无法识别架构模式。请确保
ARCHITECTURE.md
包含模式关键词："Clean Architecture"、"Hexagonal Architecture"、"Layered Architecture"或"MVC"。

Issue: Missing Violations

问题：遗漏违规

Known violations not reported. Check file paths match layer definitions. Update layer patterns if needed.
See Code Examples for complete troubleshooting examples with exception configurations and pattern detection fixes.
已知违规未被报告。请检查文件路径是否匹配层定义，必要时更新层匹配模式。
查看代码示例获取完整的问题排查示例，包含例外配置和模式识别修复方案。

Expected Benefits

预期收益

MetricWithout ValidationWith ValidationImprovement
Architecture violations15-20 per quarter0-2 per quarter95% reduction
Time to detect violations2-5 days5-10 seconds99.9% faster
Refactoring costHigh (violations embedded)Low (caught early)80% reduction
Code review time45-60 min15-20 min70% faster
Onboarding time2-3 weeks3-5 days75% faster
Technical debt20-30 violations/year2-5 violations/year90% reduction
指标无验证时使用验证后提升幅度
架构违规数每季度15-20个每季度0-2个减少95%
违规检测耗时2-5天5-10秒速度提升99.9%
重构成本高（违规已嵌入代码）低（提前发现）减少80%
代码评审耗时45-60分钟15-20分钟速度提升70%
新人上手耗时2-3周3-5天速度提升75%
技术债务每年20-30个违规每年2-5个违规减少90%

Requirements

依赖要求

  • Python 3.10+ (for validation script)
  • Source code in supported language (Python/JS/TS)
  • ARCHITECTURE.md
    or similar documentation defining layers
  • Read, Grep, Bash, Glob tools available
  • Python 3.10+（运行验证脚本需要）
  • 源码为支持的语言（Python/JS/TS）
  • 存在
    ARCHITECTURE.md
    或同类定义层的文档
  • 环境有Read、Grep、Bash、Glob工具可用

Red Flags to Avoid

需避免的风险点

Architecture Violations

架构违规

  1. Domain importing Infrastructure - Breaks dependency inversion
  2. Application importing Interface - Creates circular dependencies
  3. Infrastructure importing concrete Domain - Should use Protocols
  4. Business logic in Interface layer - Violates layer separation
  1. Domain层导入Infrastructure层 - 破坏依赖倒置原则
  2. Application层导入Interface层 - 产生循环依赖
  3. Infrastructure层导入具体Domain实现 - 应使用Protocols
  4. 接口层存在业务逻辑 - 违反分层隔离原则

Detection Anti-Patterns

检测反模式

  1. Ignoring False Positives - Add exceptions to arch-rules.yaml
  2. Skipping validation before major changes - Always validate first
  3. Not updating layer definitions - Keep ARCHITECTURE.md current
  4. Assuming pattern without verification - Read ARCHITECTURE.md first
  1. 忽略误报 - 请在arch-rules.yaml中添加例外规则
  2. 重大变更前跳过验证 - 请务必先执行验证
  3. 不更新层定义 - 请保持ARCHITECTURE.md同步更新
  4. 未验证就假设架构模式 - 请先读取ARCHITECTURE.md

Process Mistakes

流程错误

  1. Proceeding with violations - Fix before committing
  2. Not documenting exceptions - Explain why deviation needed
  3. Skipping after refactor - Validation most critical after structural changes
  4. Manual validation only - Automate in pre-commit hooks and CI
  1. 存在违规仍继续操作 - 提交前请先修复
  2. 不记录例外情况 - 请说明偏离规则的原因
  3. 重构后跳过验证 - 结构变更后验证最为重要
  4. 仅依赖人工验证 - 请在pre-commit钩子和CI中自动化执行

Utility Scripts

工具脚本

  • Validate Architecture Script - Full-featured architecture validation tool supporting Clean, Hexagonal, Layered, and MVC patterns
  • 架构验证脚本 - 功能完整的架构验证工具，支持Clean、Hexagonal、分层和MVC模式

See Also

相关参考

  • validate-layer-boundaries - Project-specific validation for project-watch-mcp
  • @architecture-guardian - Agent for architectural guidance and review
  • ARCHITECTURE.md - Project's architecture documentation
  • ADR-001 - Architecture Decision Record for Clean Architecture
  • validate-layer-boundaries - project-watch-mcp的项目专属验证工具
  • @architecture-guardian - 架构指导和评审Agent
  • ARCHITECTURE.md - 项目架构文档
  • ADR-001 - Clean Architecture的架构决策记录