node-express-boilerplate AGENTS.md

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