Architectural Thinking Engine

The Problem

Your AI coding agent just delivered a 500-line single-function controller with the database client hardwired into route handlers, authentication logic copy-pasted across three endpoints, and no dependency injection. It works. It passes the tests it wrote for itself. And it will take a senior engineer three hours to untangle when you need to swap the database or add a second auth provider. The agent optimized for "code is cheap" while ignoring "wrong architecture is expensive."

What You Get

• Pre-implementation analysis — before writing code, the agent identifies the correct architectural layer, selects an appropriate design pattern, and validates separation of concerns
• Design pattern decision tree — maps problem types to patterns (Strategy for runtime behavior variation, Facade for complex subsystems, Observer for event decoupling) with concrete selection criteria
• SOLID compliance audit — post-implementation check against Single Responsibility, Open/Closed, Liskov Substitution, Interface Segregation, and Dependency Inversion
• Automatic extraction triggers — flags files over 150 lines, functions over 30 lines, classes with more than 7 public methods, and modules with more than 10 imports
• Refactoring judgment via Rule of Three — first occurrence noted, second flagged, third triggers mandatory extraction, preventing both premature abstraction and technical debt accumulation
• Dependency direction enforcement — validates that domain layers never depend on infrastructure, catching dependency inversion violations before they compound

Why This Beats Prompting It Yourself

"Think about architecture" is an instruction agents universally acknowledge and routinely ignore. The problem isn't the agent's intelligence — it's the absence of a structured thinking framework. This skill provides the phases, checklists, and guardrails that turn a vague suggestion into an enforced workflow. Without it, you get the same single-file monolith every time because there's no structural pressure to do otherwise.

Example Session

You: "Add user authentication to my FastAPI app"

Agent: "Pre-implementation analysis:

• Layer: Authentication is a cross-cutting concern → Infrastructure layer with clean interfaces
• Pattern selection: Repository pattern for data access, Service pattern for auth logic, Middleware for token verification
• Separation check: (1) User storage → UserRepository interface (2) Auth logic → AuthService (3) Token verification → middleware (4) HTTP routing → thin routes

Recommended structure:

src/domain/entities.py          — User entity, AuthToken value object
src/domain/interfaces.py        — UserRepository, PasswordHasher, TokenService
src/application/auth_service.py — Register, Login, Verify use cases
src/infrastructure/mongo_repo.py — MongoDB implementation
src/infrastructure/jwt_service.py — JWT implementation
src/presentation/auth_routes.py — Thin FastAPI routes

Key decisions: Repository pattern lets us swap MongoDB for Postgres by changing one file. Strategy pattern allows swapping bcrypt→argon2 via interface. This is NOT over-engineering — each class has exactly one reason to change."

Use Cases

• Starting any new feature in a codebase that will live longer than a week
• Adding to an existing codebase where you need the new code to fit the existing architecture
• Refactoring requests where the agent tends to create new files without considering existing structure
• Code review where you want the agent to evaluate architectural soundness beyond linting
• Third consecutive edit to the same file — automatic signal that the design needs restructuring

Known Limitations

This skill adds a thinking phase that may slow trivial tasks — single-line fixes, config changes, and documentation-only updates should bypass it. For features under 100 lines, limit Phase 1 analysis to 30 seconds. The skill does not override existing codebase conventions — if your project uses MVC, it won't force Clean Architecture.