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:
- CLAUDE.md "Project Structure" section -- extract source code directories
- 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 - 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
-
Read the architecture definition from CLAUDE.md
- Use
Readto 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.
- Use
-
Collect source files
- Use
Globto collect files matchingsrc/**/*.{ts,tsx,js,jsx,py,java} - Exclude test files (
*.test.*,*.spec.*,test_*,*_test.*)
- Use
-
Collect import/from statements
- Use
Grepto extract import statements from each file - Patterns:
import .* from,from .* import,require(,@import
- Use
-
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.)
-
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/:
- Create
.ww-w-ai/devtools/validate-architecture/if missing - Write
latest.json-- structured result followingtemplates/schema.json - Write
latest.md-- human-readable report followingtemplates/report.template.md - 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