✨ Build NestJS with a second pair of eyes
NestJS is quick to start and surprisingly easy to make inconsistent.
An AI assistant can generate a controller, provider, interceptor, or queue consumer in seconds. The harder questions are:
- Does this belong in the current module?
- Which layer owns the decision?
- Is this retry safe?
- Does the error contract work over HTTP, GraphQL, RPC, and WebSockets?
- Can the deployment be rolled back without losing data?
That is why I built NestJS Agent Skills for Claude Code and Codex: three focused, open-source skills that help an agent inspect the real project before suggesting architecture, patterns, runtime features, or scale.
🎯 The goal is not more abstractions. The goal is better decisions with less context switching.
🚀 Start in 30 seconds
Install all three skills:
npx skills add amirtaherkhani/nestjs-agent-skills
Or install one skill for both Claude Code and Codex:
npx skills add amirtaherkhani/nestjs-agent-skills --skill nestjs-oop-design-patterns --agent claude-code --agent codex
Then open the documentation and try one of the prompts below.
🧭 Choose your path
| If you are trying to... | Start with |
|---|---|
| Reshape modules, data access, transactions, or boundaries | nestjs-architecture-principles |
| Review SOLID, dependency injection, smells, or patterns | nestjs-oop-design-patterns |
| Add Nest features, fix errors, improve performance, or prepare operations | nestjs-features-performance |
The skills are intentionally separate. A small entry point loads first, and deeper references are used only when the task needs them.
🧩 Pattern picker: choose the smallest pattern that earns its cost
A pattern is a response to a real force or failure mode, not a popularity badge.
| Pattern or approach | Use it when... |
|---|---|
| Strategy | One stable operation has several real algorithms selected by tenant, region, product, or configuration. |
| Factory | Construction is complex or depends on a validated discriminator. |
| Builder | A value has many optional or ordered parts and needs one final validation step. |
| Adapter | A vendor SDK, legacy model, or transport shape does not match your application contract. |
| Bridge | Two independent variation axes would otherwise multiply subclasses. |
| Facade | Consumers need one cohesive operation over a complex subsystem. |
| Layered controller-service-repository flow | Transport mapping, application coordination, and persistence have distinct responsibilities. |
| Decorator | Metrics, caching, tracing, or a safe retry policy should wrap a stable operation. |
| Proxy | Access, laziness, remote invocation, or caching must be controlled behind one interface. |
| Observer and domain events | Independent consumers should react to a fact without changing the source operation. |
| Command | A use-case request benefits from a named message, handler, middleware pipeline, or dispatch boundary. |
| Template Method | A workflow skeleton is stable while a small number of steps vary. |
| Chain of Responsibility | Ordered processors may handle, transform, authorize, or reject a request. |
| Repository | Application code needs collection-like persistence operations independent of ORM details. |
| Nest provider lifetime | You need shared state managed by Nest scope; use the container instead of a static Singleton. |
| Unit of Work | One use case changes several repositories or aggregates atomically. |
| Specification | A business rule or query predicate is composed and reused across contexts. |
| Transactional outbox | A database change and an integration event must not diverge. |
| Saga or process manager | A long-running workflow spans transactions and needs state, compensation, timeouts, and correlation. |
A tiny Strategy example
export interface FraudPolicy {
evaluate(input: FraudInput): Promise<FraudDecision>;
}
✅ Ask first: what varies, what stays stable, and what simpler design did you reject?
Do not add CQRS, a repository wrapper, a static Singleton, or a saga just because a pattern list contains it. The repository documents the trade-offs and the failure signals for every pattern.
Read the complete pattern catalog.
🛡️ Conflict checking is a feature
The project uses one ten-topic rules reference:
- Architecture
- Dependency Injection
- Error Handling
- Security
- Performance
- Testing
- Database and ORM
- API Design
- Microservices
- DevOps and Deployment
These are navigation categories, not ten competing sources of truth.
- 🏗️ Architecture decides whether a boundary should exist.
- 🧩 OOP and patterns decide how collaborators should be shaped inside it.
- ⚙️ Features and performance decide how runtime behavior is implemented and operated.
The handoff keeps advice consistent. For example, a controller should not become the owner of a transaction just because a pattern guide mentioned repositories.
See the rules reference.
🚨 Error Handling: make failure behavior explicit
Error handling is more than a global exception filter.
The skill helps an agent reason about:
- an application-owned failure taxonomy;
- stable public contracts, including RFC 9457 Problem Details where appropriate;
- precise HTTP, GraphQL, RPC, gRPC, and WebSocket mapping;
- NestJS filter coverage and lifecycle placement;
- deadline and cancellation propagation;
- retry classification and idempotency;
- partial effects and uncertain outcomes;
- privacy-safe logs and responses;
- fatal process behavior;
- failure-path tests.
⚠️ A timeout does not prove that a write failed. Check idempotency and reconciliation before recommending a blind retry.
Try this prompt:
Trace one representative NestJS request across guards, pipes, interceptors,
the handler, providers, persistence, and external calls. For every failure,
show the public contract, retry policy, timeout, and test that proves it.
🚀 DevOps: from commit to recovery
Deployment advice should not stop at a Dockerfile.
The DevOps guidance covers:
- immutable CI/CD and build-once artifact promotion;
- container and supply-chain controls;
- Kubernetes probes, rollout state, resources, autoscaling, and graceful termination;
- compatible database migrations;
- configuration and secret handling;
- logs, metrics, traces, SLOs, and actionable alerts;
- incident response, rollback, and tested recovery.
🔎 Desired configuration is not live state. Verify the running workload, image, environment, probes, and telemetry before calling a rollout healthy.
Try this prompt:
Review this NestJS service for production readiness. Inspect the image,
deployment, probes, configuration, secrets, migrations, logs, metrics,
SLOs, rollback path, and graceful shutdown. Report evidence before advice.
💬 Prompts you can copy
Architecture review:
Inspect the current NestJS module graph and version. Recommend the smallest
architecture change that solves the observed problem. Do not introduce CQRS,
microservices, or a new layer without repository evidence.
Pattern review:
Find the concrete force behind each proposed pattern. Keep direct code when
there is one algorithm or one construction path. For every abstraction,
state its owner, runtime cost, and contract test.
Performance review:
Trace one hot request and identify whether the bottleneck is event loop,
database, network, memory, serialization, or capacity. Measure first, then
propose the smallest safe change and a verification plan.
✅ A quick review loop
- Inspect the real repository, NestJS version, transport, ORM, and conventions.
- Trace one request, message, or job end to end.
- Assign ownership to the architecture, OOP, or features skill.
- Choose the smallest design that satisfies the actual force.
- Test failure paths, not only the happy path.
- Verify live state before claiming performance or deployment success.
⭐ If this helps your next NestJS decision
- Star the GitHub repository.
- Browse the interactive documentation site.
- Open an issue with a real conflict, failed retry, transport edge case, or rollout lesson.
- Share the article with a NestJS teammate who is building with Claude Code or Codex.
What pattern has helped your NestJS project most: Strategy, Adapter, Outbox, Saga, or something simpler?
The best contribution is a real example that makes the next agent answer more precise.
