Nestjs Agents

nestjs-agents

> Production-grade Claude Code subagents specialized for NestJS development. > Code review, testing, security, architecture — scoped to your recent work (uncommitted + last commit).

[](https://opensource.org/licenses/MIT) [](https://docs.claude.com/en/docs/claude-code/sub-agents)

Why this exists

Generic AI coding agents don't know about NestJS-specific patterns:

• Decorators (@Injectable, @Controller, @UseGuards)
• DI scopes (singleton vs request — and the race-condition trap)
• Layer responsibilities (Controller → Service → Repository — never mix them)
• Testing modules (Test.createTestingModule with getRepositoryToken)
• Transactional outbox patterns for Stripe / RabbitMQ events
• Validation pipelines with class-validator DTOs

This collection gives Claude Code that context — and scopes every review/test action to your recent work (uncommitted changes + last commit), so agents act on what you just wrote, not the entire codebase.

What's inside

| Agent | Purpose | Read-only? | Triggers | |---|---|---|---| | nestjs-code-reviewer | Reviews recent changes for bugs, security, NestJS anti-patterns | ✅ Yes | "review my changes", "check this code" | | nestjs-test-writer | Writes Jest unit / integration tests for changed components | ❌ Writes test files | "add tests", "cover with tests" | | nestjs-security-auditor | Maps changes to OWASP Top 10 + NestJS-specific traps | ✅ Yes | "security audit", "audit auth flow" | | nestjs-architect | Architecture consultant — DDD, hexagonal, microservices, transactional outbox | ✅ Yes | "design this feature", "should I split into microservices" | | nestjs-repository-expert | Builds entities, schemas, repositories, migrations (TypeORM / Prisma / Mongoose) | ❌ Writes code | "create entity", "add migration", "optimize query" | | nestjs-service-expert | Implements service layer — business logic, SOLID, error handling | ❌ Writes code | "create service", "implement use case" | | nestjs-controller-expert | Creates controllers, DTOs, endpoints, Swagger docs | ❌ Writes code | "add endpoint", "create controller", "add DTO" |

Install

Global (recommended — available in all projects)

mkdir -p ~/.claude/agents

# Clone or download just the agents
curl -L https://github.com/vasyl-bilous/nestjs-agents/archive/main.tar.gz | \
  tar -xz --strip-components=2 -C ~/.claude/agents \
  nestjs-agents-main/agents

# Verify
ls ~/.claude/agents/nestjs-*.md

Per-project

cd your-nestjs-project
mkdir -p .claude/agents

curl -L https://github.com/vasyl-bilous/nestjs-agents/archive/main.tar.gz | \
  tar -xz --strip-components=2 -C .claude/agents \
  nestjs-agents-main/agents

Pick specific agents only

mkdir -p ~/.claude/agents
curl -o ~/.claude/agents/nestjs-code-reviewer.md \
  https://raw.githubusercontent.com/vasyl-bilous/nestjs-agents/main/agents/nestjs-code-reviewer.md
curl -o ~/.claude/agents/nestjs-test-writer.md \
  https://raw.githubusercontent.com/vasyl-bilous/nestjs-agents/main/agents/nestjs-test-writer.md

After installing, restart Claude Code to pick up the new agents. Verify with:

/agents

Workflow examples

1. Implement → review → test (typical feature)

> implement createOrder method in OrderService with Stripe integration

(main agent writes the code)

> use nestjs-code-reviewer to review what I just wrote

(code-reviewer reads `git diff`, finds: missing idempotency on Stripe charge,
 transaction wrapper missing — returns findings with file:line)

> fix those critical findings

(main agent applies fixes)

> use nestjs-test-writer to add unit tests

(test-writer reads `git diff`, writes OrderService.spec.ts with mocked Stripe,
 covers happy path + error path + edge cases. Runs `pnpm test` to verify.)

2. Architecture decision before coding

> nestjs-architect: I'm building an order processing service that needs to call
  Stripe and send confirmation emails. Should I use a transaction across all of
  this or async events?

(architect responds with concrete recommendation:
 - Use Transactional Outbox pattern
 - Write Order + OutboxEvent in DB transaction
 - Worker reads outbox, calls Stripe with idempotency key
 - Separate worker handles email
 - Trade-offs: eventual consistency vs guaranteed delivery
 - Concrete next step: scaffold OutboxEvent entity)

3. Security audit before deploy

> use nestjs-security-auditor to audit my recent auth changes

(auditor reads `git diff`, finds:
 🔴 A2 Cryptographic — JWT secret hardcoded in module
 🔴 A4 Insecure Design — no rate limiting on /auth/login
 🟡 A7 Identification — generic 'wrong password' message enables enumeration
 → returns findings mapped to OWASP categories with fix suggestions)

4. Build new feature from scratch

> nestjs-architect: design module structure for "Subscription" feature

> nestjs-repository-expert: create Subscription entity + repository based on
  the architect's plan

> nestjs-service-expert: implement SubscriptionService with the business rules
  the architect described

> nestjs-controller-expert: add CRUD endpoints for /subscriptions with Swagger

> nestjs-test-writer: cover what I just built with tests

> nestjs-code-reviewer: review everything before I commit

Design principles applied to all agents

Every agent in this collection follows these rules:

1. Recent work is the scope

Every action-taking agent (reviewer, auditor, test-writer, even the code-writers when iterating) starts with the same three commands to find what you've been working on:

git status --short                  # uncommitted (staged + unstaged + untracked)
git diff HEAD                       # full diff of uncommitted changes
git diff HEAD~1 HEAD                # the last commit

The union of these is the agent's scope — it operates on what you've recently touched, not the rest of the repo. This prevents:

• Polluting your main agent's context with unrelated files
• Reviewing thousands of lines when you only changed 10
• "Drift" between what you intended and what the agent did
• Missing staged changes (a common bug when an agent only checks git diff without HEAD)

2. Read-only where possible

Reviewers and auditors have no Write/Edit tools — they cannot modify your code. They produce findings only, with file:line references and suggested fixes.

This is a deliberate guardrail:

• Reviews stay neutral (you decide what to fix)
• Auditors can't accidentally break code while "fixing" something
• Your changes remain reproducible

3. NestJS-specific context, not generic

Each agent knows about:

• Decorators, DI scopes, modules, providers
• Guards, pipes, interceptors, filters
• DTOs with class-validator, Entities with TypeORM/Prisma
• Testing with Test.createTestingModule, getRepositoryToken, mocked providers
• NestJS exceptions (NotFoundException, ConflictException, etc.)

4. Specific, file:line references

Findings always look like:

🔴 [src/auth/auth.service.ts:42] — Generic error message enables username enumeration
   Risk: attacker can detect valid emails by timing / response difference
   Fix: return same 'Invalid credentials' for both wrong-password and unknown-email

Not vague advice like "improve error handling".

5. model: inherit — agents follow your main session

Every agent is configured with model: inherit in its frontmatter. This means:

• The agent runs on whatever model your main Claude Code session is using — Opus, Sonnet, or Haiku.
• You stay in control of cost / capability trade-offs from one place (your main /model setting), no need to edit each agent.
• The library works across all subscription tiers — Pro users (no Opus) get Sonnet automatically; Max / API users on Opus get Opus.
• Always running on the latest available model. When Anthropic ships a new generation (e.g., Opus 5), you don't need to re-edit any frontmatter — agents pick up the upgrade the moment your main session does.

If you want to pin an agent to a specific model (e.g., always run nestjs-architect on Opus regardless of main session), change model: inherit to model: opus / model: sonnet in that one file. We don't recommend it for the shared library, but it's a one-line override per agent if you need it.

Recommended CLAUDE.md setup (auto-delegation)

Once the agents are installed, Claude Code can already route work to them automatically based on each agent's description and trigger phrases — you can just say "review my changes" and nestjs-code-reviewer runs.

But you'll get much more reliable routing if you add a short CLAUDE.md to your project that tells the main session which agent owns which part of the work. This turns soft hints (description matching) into hard rules ("always do X after Y").

Drop this into your project's root CLAUDE.md (or append to an existing one):

````markdown

NestJS subagent workflow

This project uses specialized NestJS subagents. Route work to them as follows:

When designing (BEFORE writing code):

• Architecture / module boundaries / pattern questions → nestjs-architect

When implementing:

• HTTP endpoint, DTO, Swagger docs → nestjs-controller-expert
• Business logic, use case, service-layer code → nestjs-service-expert
• Entity / schema, repository, migration, query optimization → nestjs-repository-expert

Don't write controller + service + repository in a single main-session turn — delegate each layer to its specialized agent so layer boundaries stay clean.

After implementing (run before committing):

1. nestjs-code-reviewer — review the recent diff for bugs, anti-patterns, missing transactions
2. If reviewer flags 🔴 critical findings — fix them before continuing
3. nestjs-test-writer — add Jest unit / integration tests for the changes
4. For changes touching auth, payments, user data, or external APIs — also run nestjs-security-auditor

When NOT to delegate:

• One-line typo fixes or rename refactors — just edit directly
• Scratch / experiment files outside src/ — agents are for production code

````

Why this works better than relying on auto-delegation alone:

• Claude Code treats CLAUDE.md instructions as must-follow rules, not suggestions — so the post-implementation review/test cycle actually happens every time, not "when the description happens to match"
• The mapping is explicit per layer, which prevents the main session from writing controller + service + repo in one shot (a common quality drop)
• Security audits get triggered based on what changed, not on whether the user remembered to ask

You can extend this further with project-specific rules (e.g., "always use nestjs-architect for changes touching the billing module") — the agents will pick up any extra context you give the main session.

Compatibility

• Claude Code v1.0+ (any model — agents inherit from your main session)
• NestJS v9, v10, v11
• TypeORM, Prisma, and Mongoose (MongoDB) all supported
• Jest (default) and Vitest (with adaptations)

Contributing

PRs welcome — especially:

• New agents (e2e-test-writer, performance-auditor, migration-writer)
• NestJS framework version updates (v12 when it drops)
• Additional anti-pattern examples from real projects

Please follow the existing format:

• YAML frontmatter (name, description with triggers, tools, model: inherit)
• Step 1: Identify scope using the standard 3-command pattern (git status --short, git diff HEAD, git diff HEAD~1 HEAD)
• What NOT to do section
• Concrete output format example

License

[MIT](LICENSE) — use freely in personal and commercial projects. Attribution appreciated but not required.

---

Author: Vasyl Bilous — Senior Full-Stack Developer, AI-driven dev practitioner. Other AI-tooling projects: component-library-mcp, nestjs-dev-logs-mcp.

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: vasyl-bilous
• Source: vasyl-bilous/nestjs-agents
• License: MIT

Install and usage instructions live in the source repository linked above.