architect-pro_skill

Overview

This skill is an advanced software architecture masterclass focused on Clean Architecture, Hexagonal (Ports & Adapters), and Domain-Driven Design tuned for the 2026 stack (Next.js 16.2, React 19.3, Node.js 24). It teaches patterns and conventions that make codebases predictable, testable, and AI-agent friendly. The content emphasizes decoupling domain logic from infrastructure and practical composition for server actions and autonomous agents.

How this skill works

The skill inspects and prescribes folder layouts, layer responsibilities, and interaction patterns between Domain, Application, Infrastructure, and Presentation layers. It defines use-case driven flows (Server Actions → Use Cases → Domain → Adapters), value objects, aggregates, and event-driven patterns to preserve business invariants. It also provides tactical guidance for making code discoverable and dependable for both humans and AI agents.

When to use it

• Starting a new product or major rewrite that must scale and be maintained by AI-assisted teams
• When introducing AI agents that will modify or generate code across the codebase
• To enforce strict separation of concerns for teams working with Next.js 16.2 / React 19.3 / Node.js 24
• When you need predictable file paths and explicit contracts for testing and automation
• To evolve a monolith into modular bounded contexts using DDD and event-driven patterns

Best practices

• Keep Domain pure: no framework, DB, or UI imports in domain code
• Prefer explicit composition for dependencies over opaque DI containers
• Model important concepts as Value Objects and Aggregates, not primitive types
• Write Use Cases as orchestration only; push business rules into Entities or Domain Services
• Provide in-memory adapters or fakes for use-case tests to keep test suites fast
• Record Architecture Decision Records (ADRs) for significant choices and trade-offs

Example use cases

• Create server actions that compose a use case with a concrete repository adapter for web forms
• Implement DeactivateUserUseCase that loads an entity, mutates state, and persists via a port
• Design a TransferService domain service that emits domain events and triggers side-effect adapters
• Migrate CRUD endpoints to use value objects and explicit DTOs for clearer agent prompts
• Pack compact repomix context for an AI agent by shipping only domain + use case files relevant to a change