structuring-projects_skill

Overview

This skill enforces universal architectural patterns for organizing project code across languages and frameworks. It defines mandatory reference reads for each project type and prescribes feature-based, DDD/hexagonal, and shared-infrastructure patterns to ensure clear module boundaries and inward dependency flow.

How this skill works

Before creating or moving files, the skill requires reading the exact reference for your project type to avoid inventing structure from memory. It inspects the project type, enforces a single source root (src/ or equivalent), and validates feature-level public APIs, path aliases, and dependency direction. It provides migration steps, audit commands, and concrete anti-patterns to correct dangerous layouts.

When to use it

• Setting up a new project structure or monorepo apps
• Creating new features, modules, or public APIs
• Refactoring codebase organization or moving files
• Defining import boundaries, path aliases, or module contracts
• Implementing DDD, Hexagonal, or Clean Architecture patterns

Best practices

• Always group code by domain/feature under src/, not by technical layer
• Expose only a feature's public API via an index file; keep internals private
• Use a single path alias (e.g. @/* → src/*) to avoid deep relative imports
• Keep shared/ for cross-cutting infra (logging, config, errors), not business logic
• Prevent circular dependencies and avoid global utils; keep helpers feature-scoped

Example use cases

• Scaffold a simple CRUD service using the feature-based layout for quick delivery
• Audit and migrate a legacy codebase: find deep relative imports and redistribute utils
• Set up a large DDD-backed backend: read the DDD reference, then create domain/application/infrastructure layers
• Organize a monorepo: apply the appropriate pattern per app under apps/ and keep shared packages isolated
• Refactor a frontend Next.js app to follow the frontend reference with feature boundaries