CLAUDE.md template for Node API
A TypeScript HTTP service with thin handlers and validated input.
CLAUDE.md
# Node API service A Node.js HTTP API written in TypeScript. Change any command below that differs from the scripts in package.json. ## Commands ```bash npm install # install dependencies npm run dev # start the server with reload npm run lint # lint npx tsc --noEmit # type-check npm test # run the tests npm run build # compile, run before calling a change done ``` Run the tests and the linter after every code change, and fix failures before saying a task is done. ## Layout - Route handlers stay thin: parse and validate input, call a service function, return the result. - Business logic lives in services, data access in a separate layer. Handlers do not talk to the database directly. - Tests sit next to the code or in tests/, and cover each route's success and failure paths. ## Conventions - TypeScript strict mode. Validate every request body, query and header at the edge with a schema before using it. - Return consistent error shapes with the right status code. Never leak stack traces or internal messages to clients. - Log with the project logger, not console.log, and never log tokens, passwords or full request bodies. - Match the style of the file you are editing. Do not reformat files you did not change. ## Database - Database changes go through migration files in the repo. Never edit a migration that has shipped; add a new one. - Never run destructive commands (drop, truncate, reset) against a shared or production database. - Use parameterized queries only. Never build SQL by string concatenation. ## Secrets - Never read, print, edit or commit .env files, credentials, API keys or private keys. - Use placeholder values in examples and tests. If a secret shows up in a file or a log, stop and tell me. ## Deploys - Never deploy to production. I run production deploys myself. - Do not change deployment config, Dockerfiles, CI workflows or host environment variables without asking. ## Git - Make small commits on a branch and write messages that say why the change was made. - Never run git push --force, git reset --hard, git clean, git checkout -- <file>, git stash or git rebase, and never use --no-verify. Ask first. - Do not push unless I ask. ## Do not touch - Lockfiles: do not edit by hand, and do not add or upgrade dependencies without asking. - Shipped migrations, the dist/ or build/ output folder, and anything marked generated or do not edit. - Public API contracts (route paths, response shapes) must not change without asking, since clients depend on them.
AGENTS.md
# AGENTS.md: Node API service Instructions for any coding agent working in this repository. A Node.js HTTP API written in TypeScript. Change any command below that differs from the scripts in package.json. ## Commands ```bash npm install # install dependencies npm run dev # start the server with reload npm run lint # lint npx tsc --noEmit # type-check npm test # run the tests npm run build # compile, run before calling a change done ``` Run the tests and the linter after every code change, and fix failures before saying a task is done. ## Layout - Route handlers stay thin: parse and validate input, call a service function, return the result. - Business logic lives in services, data access in a separate layer. Handlers do not talk to the database directly. - Tests sit next to the code or in tests/, and cover each route's success and failure paths. ## Conventions - TypeScript strict mode. Validate every request body, query and header at the edge with a schema before using it. - Return consistent error shapes with the right status code. Never leak stack traces or internal messages to clients. - Log with the project logger, not console.log, and never log tokens, passwords or full request bodies. - Match the style of the file you are editing. Do not reformat files you did not change. ## Database - Database changes go through migration files in the repo. Never edit a migration that has shipped; add a new one. - Never run destructive commands (drop, truncate, reset) against a shared or production database. - Use parameterized queries only. Never build SQL by string concatenation. ## Secrets - Never read, print, edit or commit .env files, credentials, API keys or private keys. - Use placeholder values in examples and tests. If a secret shows up in a file or a log, stop and tell me. ## Deploys - Never deploy to production. I run production deploys myself. - Do not change deployment config, Dockerfiles, CI workflows or host environment variables without asking. ## Git - Make small commits on a branch and write messages that say why the change was made. - Never run git push --force, git reset --hard, git clean, git checkout -- <file>, git stash or git rebase, and never use --no-verify. Ask first. - Do not push unless I ask. ## Do not touch - Lockfiles: do not edit by hand, and do not add or upgrade dependencies without asking. - Shipped migrations, the dist/ or build/ output folder, and anything marked generated or do not edit. - Public API contracts (route paths, response shapes) must not change without asking, since clients depend on them.
Why it says what it says
Thin handlers
Agents tend to pile logic into route handlers. Stating the split keeps code testable and reviews short.
Validate at the edge
Unvalidated input is the usual source of API bugs. A single rule covers every new route the agent writes.
No secrets in logs
Agents add debug logging freely. Naming what must never be logged prevents leaks that are easy to miss in review.
Migrations and queries
Destructive database commands and string-built SQL are the two ways an agent can do lasting damage. Both are named.
Contracts stay put
Clients depend on route paths and response shapes. Asking before changing them avoids silent breakage.