Develop High-Quality Software Architecture

Provides guidance for quality-focused software development and architecture based on Clean Architecture and Domain-Driven Design principles, covering code style, library-first design decisions, naming conventions, and anti-patterns to avoid.

Use this skill when structuring a new module around Clean Architecture and DDD boundaries, deciding whether to write custom code or use an existing library, naming domain-specific modules and classes, or reviewing code for common architectural anti-patterns. Not a fit for tasks unrelated to software architecture and code organization decisions.

General code style principles favor early returns over nested conditions, avoiding duplication through reusable functions and modules, decomposing components or functions over 80 lines into smaller pieces (splitting into separate files once a file exceeds 200 lines), and preferring arrow functions over function declarations.

The library-first approach requires always searching for an existing solution (npm packages, third-party services, APIs) before writing custom code - citing using cockatiel instead of hand-rolled retry logic - reserving custom code for domain-unique business logic, performance-critical paths with special requirements, cases where a dependency would be overkill, security-sensitive code needing full control, or when existing solutions genuinely don't meet requirements after evaluation.

Architecture and design guidance applies Clean Architecture and DDD: following domain-driven design and ubiquitous language, separating domain entities from infrastructure concerns, keeping business logic independent of frameworks, and defining isolated use cases. Naming conventions avoid generic names (utils, helpers, common, shared) in favor of domain-specific names (OrderCalculator, UserAuthenticator, InvoiceGenerator) following bounded-context patterns, with each module having a single clear purpose. Separation of concerns keeps business logic out of UI components and database queries out of controllers.

Anti-patterns to avoid include NIH (Not Invented Here) syndrome - building custom auth instead of using Auth0/Supabase, custom state management instead of Redux/Zustand, custom form validation instead of established libraries - along with poor architectural choices (mixed business logic and UI, controller-level database queries) and generic-naming dumping grounds like a utils.js with 50 unrelated functions. Code quality guidance requires typed catch blocks for error handling, decomposing complex logic, capping nesting at 3 levels, and keeping functions under 50 lines and files under 200 lines where possible.

Recommends specific libraries as the library-first alternative to custom code: cockatiel for retry logic, Auth0 or Supabase for authentication, and Redux or Zustand for state management.

Developers and architects making structural decisions on a codebase who need concrete Clean Architecture/DDD naming and separation-of-concerns rules, plus a bias toward using existing libraries over custom code, rather than ad hoc architectural choices.

Naming: OrderCalculator, UserAuthenticator, InvoiceGenerator - not utils, helpers, common, shared