# Claude Code NestJS: A Practical Agent Workflow

URL: https://agentvera.dev/en/blog/claude-code-for-nestjs/ · Published: 2026-11-01

Learn to use Claude Code in a NestJS project: set up CLAUDE.md, write effective prompts, run Jest tests, and avoid DI and DTO pitfalls.

**In short:**

- Put NestJS commands, module conventions, DTO rules, and DI rules in CLAUDE.md so Claude Code starts with the right context.
- Use small, test-driven prompts for module, controller, provider, and DTO changes, then review the diff and run Jest.
- Watch module imports, class-validator DTO classes, and circular dependencies when Claude Code edits multiple files.

[Claude Code](/en/agents/claude-code/) can work inside a NestJS repository when you start it with `claude` in the project root and give it a clear CLAUDE.md. It is most useful when you treat it as a fast, context-aware pair programmer for modules, controllers, providers, DTOs and tests rather than a one-shot code generator. This guide covers a practical setup and loop for using Claude Code on NestJS applications with Jest, class-validator and TypeORM or Prisma.

## Why Claude Code is a good fit for NestJS

NestJS rewards consistent structure more than many Node.js frameworks: modules, controllers, providers, DTOs and decorator-based dependency injection all create predictable files. Claude Code works well here because it can read the existing module boundaries and follow them while adding code. Instead of generating an isolated snippet, it can open the current feature module, see how the controller calls the service, and create a new endpoint in the same style. That reduces the two most common NestJS integration mistakes: forgetting to register a provider and putting validation logic in the controller.

Because NestJS testing is usually Jest-based, the agent can also create `Test.createTestingModule` setups, mock providers such as `UsersService`, and write controller e2e tests with `supertest`. The same structure that makes NestJS predictable also helps the agent produce fewer ad hoc abstractions and more module-shaped changes.

## Configuring a NestJS project for Claude Code

Start `claude` in the project root. Before assigning work, add a CLAUDE.md file that captures the commands, folder conventions and NestJS rules that the agent should not guess. The file should be short and concrete; too many rules are ignored. A practical example:

```markdown
# CLAUDE.md

## Commands
- Install: npm ci
- Build: npm run build
- Lint: npm run lint
- Unit tests: npm run test
- Test watch: npm run test:watch
- E2E tests: npm run test:e2e

## Layout
- Feature modules: src/<feature>/<feature>.module.ts, <feature>.controller.ts, <feature>.service.ts, dto/, entities/ (TypeORM) or prisma/ (Prisma).
- Shared pipes, guards, interceptors, filters: src/common/.

## NestJS rules
- Use DTO classes with class-validator decorators for all request bodies and query params.
- Keep controllers thin; providers own business logic and data access.
- Use constructor injection only; never instantiate a provider with new inside another service.
- Do not add global pipes, filters, interceptors, or new module boundaries without an explicit instruction.
- Preserve existing exception handling; use NotFoundException, BadRequestException, etc. for HTTP errors.
```

Keep TypeScript paths relative unless the repo already uses path aliases. If Prisma is used, the generated client is imported from one place and the schema lives at prisma/schema.prisma; if TypeORM, entities stay in each feature module. Update CLAUDE.md when you change the data layer or test setup so the agent does not fall back to stale assumptions. See [Claude Code best practices](/en/blog/claude-code-best-practices/) for more on making project instructions actionable.

## A reliable working loop for NestJS changes

Use [Claude Code plan mode](/en/blog/claude-code-plan-mode/) for anything that touches more than one module. A reliable loop is: describe the change with the affected module, ask the agent to inspect the existing files first, have it implement in one small step, run the unit tests, review the diff, and run e2e tests when a controller or DTO changed. Example prompts for typical NestJS tasks:

- In the UsersModule, add a `PATCH /users/:id` endpoint using an UpdateUserDto with class-validator decorators and partial validation. Update UsersController and UsersService, keep the controller thin, and add a unit test for UsersService.update.
- Create a new OrdersModule with `POST /orders` and `GET /orders/:id`. Use Prisma for data access, create an Order DTO with class-validator, and write an e2e test that sends a valid payload and expects 201.
- Refactor AuthService to remove inline JWT handling and use JwtService from @nestjs/jwt. Update AuthModule imports, keep the public method signatures stable, and adjust existing unit tests.
- Run npm run test and npm run lint. Fix only issues in files you changed. Do not reformat untouched modules.
- Review the current diff for NestJS issues: missing class-validator decorators, providers not registered in the module, and circular dependencies. Report file:line findings only, no edits.

If the agent edits a module file, ask it to show the updated `imports` and `providers` arrays in the diff. If it edits a DTO, require an e2e test that covers both valid and invalid payloads.

## What Claude Code handles well and common NestJS pitfalls

The agent handles feature scaffolding, DTO creation, test stubs, Prisma/TypeORM query updates, and refactoring of providers. It is weakest when a change requires knowing runtime DI behavior or when it guesses module imports from memory. Keep the following checks in mind.

| Task | What Claude Code does well | Watch for |
| --- | --- | --- |
| Add user CRUD | Generates controller, service, DTOs and Jest tests in consistent style | Provider not registered in UsersModule; validation moved into controller |
| Scaffold a new module | Creates module, controller, provider, and tests with existing naming | Missing imports for TypeOrmModule.forFeature or PrismaService module; circular imports |
| Auth or guard changes | Refactors auth using @nestjs/jwt or passport while keeping public method signatures | Global guard wiring changed without an explicit ask; secrets or token logic embedded in controller |
| DTO updates | Adds class-validator decorators and e2e assertions | Uses an interface for DTO instead of a class; does not enable ValidationPipe at app level |

If you use interfaces for DTOs, class-validator cannot read metadata; Claude Code must create real classes. Always confirm the app’s main.ts has `app.useGlobalPipes(new ValidationPipe(...))` or equivalent after DTO work. The biggest source of subtle failures is a missing provider or provider import: when reviewing, open the feature module and verify each injected class appears in `providers` or `imports`.

## Verifying Claude Code changes with Jest and e2e tests

Make the agent run the npm scripts from CLAUDE.md rather than assuming a test runner. After a service change, have it run the relevant test file first, then the full unit suite. For controller or DTO changes, also run `npm run test:e2e` because validation and HTTP status are only verified through the Nest runtime. Ask the agent to use @nestjs/testing with `Test.createTestingModule` for unit tests and `supertest` for e2e tests; if a provider depends on TypeORM or Prisma, have it mock that provider or use a test database, never the production database. After tests pass, run `npm run lint` and review the diff in the CLI before accepting. If the app has global request validation, include an e2e case where an invalid DTO returns 400; this confirms the agent did not bypass class-validator by writing a plain object.

## Running multiple Claude Code agents on one NestJS repo with AgentVera

To run several Claude Code agents on a single NestJS repository without collisions, use AgentVera. It opens each agent in its own real terminal panel, and many agents can work in parallel in separate git worktrees, so one can refactor UsersService while another builds OrdersModule without overwriting files. When an agent finishes a turn, a second model reviews the code and links findings to file:line, which is valuable for catching NestJS DI and decorator mistakes. Checkpoints let you undo any turn, and token budgets stop runaway refactors. See [how to run multiple Claude Code agents in parallel](/en/blog/run-multiple-claude-code-agents/) for more.

## Closing notes on Claude Code and NestJS

Claude Code turns into a useful NestJS contributor once CLAUDE.md defines the project rules and you keep a small-step, test-first loop. The most valuable check is not the generated code itself but whether module wiring, DTO classes, and DI remain intact; that is where a careful diff review pays off.

## Frequently asked questions

**Can Claude Code build a NestJS module from scratch?** Yes, it can scaffold a feature module with a controller, provider, DTOs, and tests if you describe the endpoint and data shape. Review the generated module imports and provider registration because NestJS still requires explicit wiring.

**How do I make Claude Code follow my NestJS conventions?** Add a CLAUDE.md file in the project root with build, lint, and test commands, folder conventions, and rules such as thin controllers, constructor DI, and class-validator DTO classes. Keep the rules short and action-oriented.

**Does Claude Code run Jest tests correctly in a NestJS project?** It can run the npm scripts from your package.json or CLAUDE.md, including unit and e2e tests. Ask it to run the affected test file first, then the full unit suite and the e2e suite for controller or DTO changes.

**What should I watch for when Claude Code edits NestJS files?** Check that providers are registered in the right module, controllers stay thin, DTOs use classes rather than interfaces, and new module imports do not create circular dependencies. Missing class-validator decorators or ValidationPipe setup are common issues.

---

**About AgentVera.** AgentVera is a desktop app for macOS, Windows and Linux, built by Solviera Teknoloji. It runs 18 AI coding agents (Claude Code, Codex, Gemini CLI, Copilot, Cursor, Antigravity, opencode, Hermes, Qwen Code, Kimi Code, Kiro, Amp, Droid, Goose, Vibe, Crush, Aider, Cline) side by side, per project, in real terminals with the user's own CLI installs and logins. The free plan has unlimited agents. Download: https://agentvera.dev/en/download/ · Pricing: https://agentvera.dev/en/pricing/