Executive Summary
- Coding agents optimize for test passes, often taking lazy architectural shortcuts that violate layer encapsulation.
- Common AI antipatterns include direct DB access in UI components, circular service calls, and bypassing auth middlewares.
- Hexagonal architecture divides systems into 4 rigid layers: View -> Controller -> Domain Service -> Repository.
- Deterministic tools like `dependency-cruiser` and ESLint boundaries turn architectural violations into immediate compiler errors.
- Strict typed Data Transfer Objects (DTOs) enforce contract boundaries between frontend and backend layers.
The lazy agent trap: Why AI creates spaghetti architecture
Autonomous coding agents are tasked with making tests pass as quickly as possible. Left unconstrained, they exhibit 'path of least resistance' behavior.
Need to display user billing status in a React button? An agent might import `prisma` directly into the component file, execute a raw SQL query, and hardcode the tax calculation.
The code compiles, the unit test passes, and the feature works—but the codebase has just accumulated toxic technical debt that breaks microservice boundaries and leaks security permissions.
The Discipline Principle
An LLM has no innate sense of clean architecture. If the repository does not mathematically forbid bad imports, the agent will write spaghetti code that destroys long-term maintainability.
The four-tier hexagonal boundary model
To maintain pristine architecture at high AI coding velocity, systems must enforce four strict layer boundaries:
1. Layer 1 — Presentation (UI/Views): Can only import UI components and typed API clients. Forbidden from touching database ORMs or server secrets.
2. Layer 2 — API Gateway / Controllers: Handles HTTP routing, input validation (Zod schemas), and calls Domain Services.
3. Layer 3 — Core Domain Services: Houses pure business logic, calculations, and state machines. Zero HTTP or database awareness.
4. Layer 4 — Data Repositories & Adapters: Encapsulates SQL, Redis, and external API queries.
Unconstrained AI Shortcuts vs Enforced Hexagonal Boundaries
Evaluating coupling, refactorability, and security risk across architectural designs.
Architectural models compared
| Feature | Dimension | Unconstrained AI Generation | Enforced Hexagonal Boundaries |
|---|---|---|---|
| Coupling Level | High (Direct DB queries in UI views) | Zero (Strict interface abstraction) | |
| ESLint Boundary Rules | Disabled / Missing | Automated `dependency-cruiser` CI rules | |
| Refactorability | Extremely painful (Touching 1 file breaks 20) | Trivial (Isolated layer modifications) | |
| Security & IAM Leakage | Frequent (Auth checks bypassed in UI) | Impossible (Gateway enforces auth on all calls) | |
| Technical Debt Half-Life | < 3 months before maintenance crisis | Decades of scalable clean evolution |
Dependency boundary enforcement in dependency-cruiser.js
Below is a configuration snippet using `dependency-cruiser` that automatically fails the build if an agent attempts an unauthorized cross-layer import.
Enforcing typed Data Transfer Objects (DTOs) across layers
Data passed between layers must be validated using immutable Zod schemas.
When an agent modifies a service output, TypeScript immediately highlights every consuming UI component that needs an update, preventing runtime undefined errors.
Preventing silent authentication and telemetry bypasses
By enforcing that all data requests pass through the API controller layer, agents cannot accidentally create endpoints that bypass JWT validation or audit logging.
Security policies remain centralized and mathematically guaranteed.
Architecture boundary enforcement checklist
Audit your repository layer encapsulation against these architectural standards.
Architecture boundary checklist
1Linting & Tooling
- `dependency-cruiser` or ESLint boundary rules run on every commit
- UI components are strictly forbidden from importing database clients
- Domain business logic is isolated in pure, framework-independent services
2Contracts & Security
- Typed DTOs govern all data exchange across system boundaries
- Authentication middlewares cannot be bypassed by newly generated routes
- Architecture rules in `AGENTS.md` explicitly explain layer responsibilities