# 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