AGENTS.md

Canonical instructions for AI coding agents working in this repository. CLAUDE.md, GEMINI.md, and .github/copilot-instructions.md are symlinks to this file — edit only this file.

Read First

• Project overview and architecture: README.md
• Setup and contributor workflow: CONTRIBUTING.md

Skills

Reusable workflows live in .agents/skills/ (source of truth; .claude/skills/ contains symlinks into it). Prefer a skill when the request matches one:

Project workflows:

• new-resource — scaffold a complete API resource end to end
• update-schema — Prisma schema change + migration + client regen + downstream updates
• add-middleware — create and wire Express middleware
• add-test — scaffold unit and integration tests for a resource
• add-openapi-docs — document endpoints in src/docs/ (schemas, paths, registration)
• security-audit — project-specific security review (auth, CSRF, limits, validation, secrets)

Reference guidance:

• prisma-client-api, prisma-database-setup, prisma-postgres — Prisma
• vitest — Vitest testing patterns
• api-design-principles — REST API design
• nodejs-best-practices — Node.js patterns and decision-making
• multi-stage-dockerfile — optimized Dockerfiles
• typescript-magician — advanced TypeScript typing
• find-skills — discover and install new skills

When no skill matches, follow this file directly.

Working Style

• Keep edits small and localized; avoid broad refactors unless explicitly requested.
• Preserve current architecture and naming conventions.
• After code changes, run pnpm full-check and the most relevant test suite before finishing.

Stack

Node.js 22+ · Express 5 · TypeScript 6 (strict) · Prisma 7 + PostgreSQL 16 · Zod v4 · Pino · JWT (HttpOnly cookies) · CSRF (double-submit cookie) · Vitest · pnpm

Required Commands

# Development
pnpm dev
pnpm build
pnpm start

# Quality gate (run before finalizing changes)
pnpm full-check

# Focused checks
pnpm lint
pnpm format
pnpm type-check
pnpm knip          # dead code / unused deps (enforced in CI)

# Prisma
pnpm prisma:migrate
pnpm prisma:migrate:deploy
pnpm prisma:generate
pnpm prisma:db:seed

# Tests
pnpm test
pnpm test:integration
pnpm test:all
pnpm db:test:up
pnpm db:test:migrate
pnpm db:test:down

Package manager is pnpm only. Never use npm or yarn.

Architecture Contract

Layering is strict and one-directional:

Routes → Controllers → Services → Repositories → Prisma

• The DI container in src/container/index.ts is the only place to instantiate concrete classes.
• Route classes resolve controllers via this.container.get<Name>Controller().
• src/index.ts binds the port only; src/app.ts handles middleware and route mounting.

Non-Negotiable Rules

• Never read process.env directly; use src/config/env.ts.
• Never use console.*; use src/config/logger.ts.
• Never send ad-hoc error responses from controllers; throw typed errors from src/errors/ and let global middleware format responses.
• No any, no floating promises, and use import type for type-only imports.
• Public class methods and properties must have explicit return types.
• Prefer ?? over || for nullish handling.

Implementation Patterns

• Controller handlers should be arrow-function properties to preserve this binding.
• Validation should be Zod v4 in src/validations/ using helpers from src/lib/validate.ts.
• Repository update/delete operations must wrap Prisma calls in try/catch and pass errors through handlePrismaError.
• Apply doubleCsrfProtection on all mutating routes (POST, PUT, PATCH, DELETE).
• Attach route-group-specific limiters from src/middleware/limiter.middleware.ts.

New Resource Order

1. Update prisma/schema.prisma, then run pnpm prisma:migrate and pnpm prisma:generate.
2. Add src/types/<name>.types.ts.
3. Add src/validations/<name>.validation.ts.
4. Add src/repository/<name>.repository.ts.
5. Add src/services/<name>.service.ts.
6. Add src/controllers/<name>.controller.ts.
7. Add src/routes/<name>.route.ts.
8. Register in src/container/index.ts.
9. Mount in src/app.ts at ${config.BASE_URL}/${config.API_VERSION}/<resource>.
10. Update barrel exports.
11. Add OpenAPI docs in src/docs/.
12. Run pnpm full-check and relevant tests.

Common Gotchas

• Run pnpm prisma:generate after every Prisma schema change.
• Integration tests require test DB setup (pnpm db:test:up and pnpm db:test:migrate).
• CSRF token comes from GET /api/v1/auth/csrf-token and must be sent as x-csrf-token.