A CLAUDE.md Template for NestJS Projects

A CLAUDE.md for NestJS should describe your API’s module boundaries, input checks, dependency wiring, and test commands. It gives Claude Code the project choices that are easy to miss when copying a framework example, including which behavior must stay compatible.

Keep the reasons behind those choices in a shared work record. fenbs holds approved API decisions, implementation tasks, and the next step, so a short repository instruction can point to a current agreement without collecting every development conversation.

What should you confirm about the API first?

Inspect the manifest, lockfile, application entry point, a representative feature module, and its tests. Identify the NestJS version, package manager, transport, and existing validation approach. A project serving HTTP requests may have different testing needs from one handling messages or a combination of transports.

Read the scripts rather than guessing their names. Confirm which command runs a focused test and which command runs the broader checks. Record any required local services using safe descriptions, with secrets kept outside the instruction file and outside the shared task record.

• Find an endpoint whose request, response, and error behavior the team wants new work to follow.
• Identify where the project checks identity and permission, and keep those controls in the actual application.
• Check how configuration and external clients enter services.
• Mark generated clients, database files, and deployment configuration that need separate authorization to change.

The CLAUDE.md file overview covers the instruction mechanism. Here the useful output is a verified NestJS working agreement, with enough detail to review an API change without inventing a new architecture.

What can you copy as a starting point?

This example describes a hypothetical pnpm-based HTTP API. Verify every command and replace the example paths before using it. If your repository uses a different package manager or validation system, name the existing choice rather than changing the project to match this example.

# NestJS project instructions

## Scope and commands
Work in the requested feature only. Use the locked dependency versions.
Example verified scripts, run from this API folder:
pnpm test -- --runInBand
pnpm test:e2e
pnpm build
Confirm the manifest before using these commands in another repository.
Do not run database changes, deployments, or live-service writes as checks.

## Module boundaries
Follow the neighboring feature module.
Keep request handling in controllers and application behavior in services.
Use the existing public service boundary between features.
Do not add a global module to solve an unexplained dependency error.

## Validation and contracts
Use the existing input validation and response conventions.
Confirm the configured validation pipe and its options before changing a DTO.
Do not treat a TypeScript type annotation as runtime input validation.
Preserve authorization checks and existing response/error contracts.

## Dependency injection
Inject dependencies through the established providers and tokens.
Keep provider scope unchanged unless the task requires a reviewed change.
Do not construct an external client inside a controller as a shortcut.

## Tests and review
Check ordinary behavior, invalid input, and relevant permission failures.
Use isolated test dependencies rather than production services.
Report exact commands, outcomes, and checks that remain unverified.

Keep the instructions specific enough to disagree with. “Use the existing public service boundary” should point to a real example when the repository has more than one pattern. If maintainers disagree about that example, resolve the choice before presenting either pattern as a standing requirement.

Use the instruction examples for alternative wording. Avoid filling this template with generic advice that would apply equally to any server; the valuable lines are the ones that change how someone safely edits this API.

How should you describe module and provider boundaries?

A feature module organizes the related parts of an application. A provider is a dependency, such as a service, that Nest supplies to the code that needs it. Nest’s providers documentation↗ (opens in a new tab) shows constructor injection and registering services in a module’s providers list.

Your instructions should explain how your project uses those mechanisms. Name the service that other features should call and any implementation details they should leave private. Describe the expected test boundary so an assistant can replace external dependencies without rebuilding the application structure.

A dependency error should trigger diagnosis, not an automatic architecture change. Ask Claude to identify the missing registration or token and compare it with an existing working feature. Making a module global or constructing a dependency manually may hide the immediate error while changing assumptions elsewhere.

If changing a boundary is necessary, record it as a human-approved architecture decision with its reason. Decisions and rules in fenbs preserve that choice for the next assistant, while the local file states the resulting convention.

Which validation choices belong in the instructions?

Describe what happens to input before a handler uses it. Nest documents runtime validation through pipes, including ValidationPipe, in its validation guide↗ (opens in a new tab). A DTO, meaning a class describing data passed into or out of an operation, needs to fit the validation approach configured in your application.

Verify how the project treats unknown properties and converts incoming values. With ValidationPipe, stripping unknown fields and rejecting them are different options. Do not ask an assistant to change those options merely because a tutorial uses a different setting; the choice can change what clients observe.

State the project’s expected behavior in plain words. For example: an order request with an unrecognized field is rejected, and an invalid quantity produces the established error shape. Then add tests at the layer that actually performs the check, rather than only testing the service after invalid input has already been excluded.

Keep authorization separate from input shape. A correctly formed request can still come from someone who lacks permission to perform it. The file should direct Claude to preserve and test the relevant application control; the Markdown instruction does not enforce that control itself.

How do you turn review criteria into useful checks?

Start with the changed behavior and its most important failure case. For a hypothetical address endpoint, a focused service test might check normalization, while an endpoint-level test checks invalid input and the public error response. A successful compilation cannot establish all of those behaviors.

Keep commands honest. If an end-to-end check needs a local database that is unavailable, report that limitation with the command attempted and the observed result. Do not silently substitute a different check and call the original requirement complete.

• Check the returned status and response shape when the public contract changes.
• Test a relevant invalid input through the configured validation layer.
• Check permission failures when the task touches access-sensitive behavior.
• Confirm external calls use isolated test replacements and do not write to live accounts.

Also verify that Claude actually read the instructions before judging their wording. Anthropic’s project memory documentation↗ (opens in a new tab) explains instruction loading; the separate not-working guide helps distinguish a missing file from an unclear requirement.

How to do this with fenbs

1. Create a free account and add the API as a project on your kanban board.
2. Record the approved response, validation, and module-boundary choices in Decisions and rules, with the people who made them.
3. Save the reviewed NestJS template in Skills and prompts. Create the implementation task with its scope and planned checks.
4. Connect a supported assistant using Integrations, then ask it to read the project context and the repository instructions before changing code.
5. Save progress with the commands run, results, contract questions still open, and the next step for the following session.

fenbs does not validate API requests or run your NestJS tests. It may be unnecessary for a one-off local change with no continuing decisions; it becomes useful when several sessions or assistants need the same approved API agreement and current task state.

The AI prompts collection offers other focused prompts for reviewing and explaining work. Keep this file centered on the NestJS conventions that a maintainer can check, and keep temporary debugging details with the task.