Agent Rules – NestJS Backend

This file defines the mandatory rules for AI coding agents working on the NestJS backend.

When to apply

These rules apply when:

• Adding a new API endpoint
• Modifying existing backend logic
• Refactoring application or persistence code
• Reviewing or extending code generated by an AI agent

Required reading (MUST READ FIRST)

Before implementing or modifying ANY backend API:

• agent-docs/nestjs/SKILL.md

Architecture rules (NON-NEGOTIABLE)

Agents MUST follow strictly:

• Clean Architecture
• Hexagonal Architecture (Ports & Adapters)
• CQRS-lite (QueryService vs UseCase)
• Nx module boundaries (NO relax, NO bypass)

Hard rules

• API layer MUST NOT import persistence or adapters
• Application layer injects dependencies via tokens ONLY
• Application layer throws DomainError ONLY
• Persistence layer implements ports and binds them using useExisting
• apps/api (or libs/api) is composition root only (NO business logic)

Decision rules

• Prefer existing patterns and features before inventing new ones
• If unsure, copy an existing feature structure exactly
• Do NOT introduce new architectural patterns without justification

Notes

• agent-docs/nestjs/SKILL.md is the execution playbook agents must follow
• metadata.json (if present) provides high-level context and references