Claude Code Hexagonal Kit

Next.js (App Router) full-stack app with hexagonal architecture, SOLID and unit tests. No database: an in-memory adapter keeps pnpm dev zero-setup. No auth (out of scope for the demo).

@AGENTS.md

Commands

• pnpm dev / pnpm build - run / build the app
• pnpm test - Vitest (domain, application, infrastructure, hooks)
• pnpm arch - dependency-cruiser layer rules (messages explain the fix)
• pnpm typecheck, pnpm lint
• pnpm check - lint + typecheck + test + arch. Run it before saying you are done.

Architecture map

src/app/            Next.js pages + server actions (driving adapter). Zod validation lives here.
src/modules/<name>/
  domain/           entities, value objects, domain errors, ports. Pure TypeScript.
  application/      use cases: make<UseCase>(deps) factories. Depend on domain only.
  infrastructure/   adapters implementing ports (in-memory repo, clock, id generator)
  index.ts          module public API (never exports infrastructure)
src/composition/    composition root: the ONLY place adapters are wired into use cases
src/shared/         tiny shared kernel, only if truly needed (does not exist yet)

Example module: orders (place / cancel / list orders).

Layer rules (enforced by .dependency-cruiser.cjs)

1. domain imports nothing from other layers and no npm packages. Time and ids come in through ports (Clock, IdGenerator).
2. application imports only domain (and shared). No next, react, zod, adapters.
3. infrastructure may import domain; never app or composition.
4. Only src/composition imports infrastructure.
5. src/app imports modules only via @/modules/<name> (index.ts) or @/composition/<name>.
6. A module never imports another module's internals, only its index.ts.
7. No circular dependencies.

Business rules live in the domain. The UI validates input (Zod) and translates; adapters store and fetch.

Workflow

For domain or application changes: write or adjust the test first, see it fail, then write the code, then pnpm check. Use the skills: new-module, new-use-case, new-adapter, connect-ui. Use the architecture-reviewer subagent on a finished diff and test-writer for missing tests.

Conventions

• Files kebab-case; one use case per file; tests beside the code (order.ts -> order.test.ts).
• Types/classes PascalCase, functions camelCase. Ports are interfaces named for the role (OrderRepository); adapters name the technology (InMemoryOrderRepository).
• Money is integer cents. Domain objects are immutable; operations return new objects.
• Domain failures are DomainError subclasses with a code; the UI turns them into friendly messages.
• Inside a module use relative imports; elsewhere use @/.

Never

• Never weaken or bypass the guardrails: do not edit .dependency-cruiser.cjs, .claude/hooks/** or .claude/settings.json, and do not use eslint-disable / @ts-ignore to get around a rule. If a rule blocks you, explain to the user what you need.
• Never put business rules in src/app or in adapters.
• Never call Date.now(), new Date() or Math.random() in domain or application code.
• Never leave console.log or commented-out code. Never commit secrets or .env files.
• Never skip validation of external input.

Hooks

Rules are enforced, not suggested (.claude/settings.json):

• PostToolUse on edits to src/**/*.ts(x): runs pnpm arch; a violation comes back to you with the rule and the fix.
• PreToolUse: edits to the guardrail files above are blocked.
• Stop: if src/ changed, typecheck and tests must pass or you are sent back to fix them.