# Validate Architecture

> Detects inter-layer import rule violations (Clean Architecture)

- Skill: `ww-w-ai/validate-architecture` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add ww-w-ai/validate-architecture`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ww-w-ai/validate-architecture/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: ww-w-ai (https://skillmd.com/u/ww-w-ai)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/ww-w-ai/validate-architecture

---


# validate-architecture -- Architecture Layer Violation Detection

Corresponding rule: `architecture.md`

## Purpose

Statically detect inter-layer import rule violations and circular references in a project. If CLAUDE.md defines an architecture, use that layer definition; otherwise default to the general 3-layer model (presentation/business/data access).

## Input -- Dynamic Target Resolution

Resolve target directories in this order:
1. CLAUDE.md "Project Structure" section -- extract source code directories
2. If CLAUDE.md is missing or has no structure info: Glob source files (`**/*.{ts,tsx,js,jsx,py,java,go,rs}`) -- use the top-level directory containing matched files
3. If no source files are found: report status as SHALLOW and state the reason

Default exclusions: node_modules/, .git/, dist/, build/, coverage/
Skill-specific exclusions: `*.test.*`, `*.spec.*`, `test_*`, `*_test.*`

### Mandatory Output: Target Resolution Result

Output the following before proceeding with validation. Do not advance until resolution is complete.

| Step | Result |
|------|--------|
| CLAUDE.md check | Found/Not found |
| Resolved directories | {list or "none"} |
| Source file count | {count} |
| Resolution method | CLAUDE.md / Glob fallback / SHALLOW |

## Execution Logic

1. **Read the architecture definition from CLAUDE.md**
   - Use `Read` to read the project root CLAUDE.md
   - If an Architecture section exists, use its layer structure and dependency direction as the baseline
   - If no Architecture section exists, default to the general 3-layer model:
     - Presentation (presentation, ui, pages, components, views, routes, handlers)
     - Business (domain, core, application, services, use-cases, usecases)
     - Data access (infrastructure, infra, repositories, external, adapters, gateways)
   - Dependency direction: presentation -> business <- data access. The business layer must not depend on other layers.

2. **Collect source files**
   - Use `Glob` to collect files matching `src/**/*.{ts,tsx,js,jsx,py,java}`
   - Exclude test files (`*.test.*`, `*.spec.*`, `test_*`, `*_test.*`)

3. **Collect import/from statements**
   - Use `Grep` to extract import statements from each file
   - Patterns: `import .* from`, `from .* import`, `require(`, `@import`

4. **Detect layer violation patterns**
   - domain/core -> infrastructure/infra imports (business depends on data access)
   - domain/core -> presentation/ui/pages/components imports (business depends on presentation)
   - presentation -> direct DB imports: the presentation layer directly imports DB-related packages (`sqlalchemy`, `prisma`, `typeorm`, `drizzle`, `mongoose`, `sequelize`, `knex`, `pg`, `mysql`, `sqlite`, etc.)

5. **Detect circular references**
   - Detect patterns where module A imports module B while module B also imports module A
   - Check bidirectional imports at the file level

### Mandatory Output: Architecture Validation Matrix

Output the matrix below before generating the final report. Do not proceed until every check has been performed.

| Check Item | Status | Items Checked | Violations | Severity | Evidence |
|------------|:------:|:-------------:|:----------:|:--------:|----------|
| Read CLAUDE.md architecture | ? | ? | -- | -- | {Read result} |
| Source file collection | ? | ? | -- | -- | {Glob pattern, file count} |
| domain -> infra import | ? | ? | ? | ERROR | {Grep pattern, searched files} |
| domain -> presentation import | ? | ? | ? | ERROR | {Grep pattern, searched files} |
| presentation -> DB import | ? | ? | ? | ERROR | {Grep pattern, searched files} |
| Circular references | ? | ? | ? | WARN | {Grep pattern, searched files} |

Status values: PASS (verification complete, no issues), NOT_APPLICABLE (no source files), SKIPPED (plugin issue), SHALLOW (target resolution failed)

### Pre-Output Checklist (Mandatory Before Final Output)

Check every item before writing the report. If any item is unchecked, go back and complete it.

- [ ] Every check item has a Status value (no empty Status cells)
- [ ] Every check with Status != SKIPPED has an Evidence value
- [ ] Architecture basis (CLAUDE.md or general 3-layer) is identified and stated
- [ ] All 4 violation-pattern checks performed
- [ ] Circular-reference check performed
- [ ] Report language matches the user's conversation language

### Schema Compliance Check (Mandatory Before Saving to .ww-w-ai/)

Before writing to .ww-w-ai/devtools/validate-architecture/, verify the JSON output:
- [ ] Every "required" field in schema.json is present and non-empty
- [ ] The findings[] array contains every detected violation
- [ ] summary counts match the actual finding count

## Output

Generate the validation report in the user's conversation language.

Output violations as a Markdown table in this format:

```
===== Architecture Validation Report =====

[Architecture basis]: CLAUDE.md definition / General 3-layer

| File | Violation | Severity |
|------|-----------|----------|
| `src/domain/user.ts` | Infrastructure layer import (`../../infra/db`) | ERROR |
| `src/core/order.ts` | Presentation layer import (`../../pages/OrderView`) | ERROR |
| `src/pages/Dashboard.tsx` | Direct DB import (`prisma`) | ERROR |
| `src/services/auth.ts` <-> `src/services/user.ts` | Circular reference | WARN |

Total violations: {N} (ERROR: {E}, WARN: {W})
====================================
```

When there are no violations:

```
===== Architecture Validation Report =====

[Architecture basis]: CLAUDE.md definition / General 3-layer

No violations.
====================================
```

### Severity Criteria

| Severity | Condition |
|:--------:|-----------|
| ERROR | Layer dependency-direction violation (domain -> infra, domain -> presentation, presentation -> DB) |
| WARN | Circular reference, ambiguous layer placement (file outside any layer directory) |

## Output Persistence

After generating the architecture validation report, save results to `.ww-w-ai/devtools/validate-architecture/`:

1. Create `.ww-w-ai/devtools/validate-architecture/` if missing
2. Write `latest.json` -- structured result following `templates/schema.json`
3. Write `latest.md` -- human-readable report following `templates/report.template.md`
4. Archive to `history/` -- copy latest.json to `.ww-w-ai/devtools/validate-architecture/history/{timestamp}.json`

`latest.md` is generated in the user's conversation language. JSON field names stay in English regardless of language.
The JSON output enables machine-parseable history tracking and cross-run comparison.
The history/ directory preserves previous executions for trend analysis.

## Permission Rationale

- **Write**: Exclusively for .ww-w-ai/ output persistence. No project source modification.
- **Bash**: Exclusively for read-only git/system queries. No file modifications.

## Notes

- Bash is permitted for directory creation (`mkdir -p .ww-w-ai/devtools/validate-architecture/history`). The validation itself is read-only and does not modify project files.
- Test files (`*.test.*`, `*.spec.*`) are excluded from inspection (per testing.md exceptions, internal access inside tests is permitted).
- If CLAUDE.md defines an architecture, that definition takes precedence over the general principles.
- Layer directory naming may differ per project, so CLAUDE.md definitions take highest precedence.

## Spec Reference

For detailed validation criteria, evidence tables, and examples:
- Corresponding rule spec: `../../docs/specs/architecture.md`