Ready to supercharge your AI agents?

Install any skill in seconds. Free to start, no credit card required.

NestJS Best Practices · asymmetric-al | DecimalAI

asymmetric-al/nestjs-best-practices

NewSkillScoreMaintained

NestJS best practices and architecture patterns for building production-ready applications. This skill should be used when writing, reviewing, or refactoring NestJS code to ensure proper patterns for modules, dependency injection, security, and performance.

codingby asymmetric-al

Links this skill to your agents and keeps it current with the author’s updates.

Automatic

Coding pack

1 · One-time — install the CLI (docs ↗)

pip install decimalai

2 · Get the skill — writes .claude/skills/asymmetric-al-nestjs-best-practices/SKILL.md

decimalai skills pull asymmetric-al-nestjs-best-practices --out .claude/skills/

No CLI? Get the same file — curl · raw file

curl -fsSL --create-dirs -o .claude/skills/asymmetric-al-nestjs-best-practices/SKILL.md https://app.decimal.ai/s/asymmetric-al-nestjs-best-practices/SKILL.md

Raw file: /s/asymmetric-al-nestjs-best-practices/SKILL.md ↗ · machine-readable summary at /s/asymmetric-al-nestjs-best-practices.json ↗

In productionGlobal

how this skill behaves on real traffic · last 30 days

No production data for this skill yet — usage numbers appear here once agents start running it.

Anonymized aggregate across every org using this skill — proof from real production use, not a demo.

Does this skill help? · Benchmark: with vs. withoutsign in to run this on your agents

23 test cases from the publisher’s eval.yaml · each run twice on gemini-3.6-flash — with the skill injected, then without · last run 23h ago

Yes — +4% lift · at higher cost+40% tokens0% turns100% of whole cases pass with skill (23/23)

Test case	Without → With	Effect	Δ tokens	Δ turns
case-05	✗→✓	▲ Improved	38%	0%
case-04	✓→✓	＝ Same ✓	21%	0%
case-01	✓→✓	＝ Same ✓	45%	0%
case-02	✓→✓	＝ Same ✓	31%	0%
case-03	✓→✓	＝ Same ✓	36%	0%

Showing 5 of 23 cases

SkillSafety

✓ 3 of 3 passed

Code scan15 of 15 checks clean

0 critical · 0 warning · 0 info — scanner v4 — 8/3/2026

live_secretremote_code_executionreverse_shelldata_exfiltrationssrf_metadataagent_snoopinganti_refusaldestructive_commandsobfuscated_unicodeunicode_homoglyphopaque_blobsuspicious_urltool_overreachtrigger_abuseprompt_injection_phrasing

IntentSafe

LLM judge · does the skill do what it claims

ContentClean

LLM judge · policy & harmful-content review

Source

Imported

asymmetric-al / core

.agents/skills/nestjs-best-practices/SKILL.md

View on GitHub ↗

License MITImported 8/3/2026Version v1Bundled 4 files · scripts

Skill contents

scripts/

SKILL.md

NestJS Best Practices

Comprehensive best practices guide for NestJS applications. Contains 40 rules across 10 categories, prioritized by impact to guide automated refactoring and code generation.

When to Apply

Reference these guidelines when:

Writing new NestJS modules, controllers, or services
Implementing authentication and authorization
Reviewing code for architecture and security issues
Refactoring existing NestJS codebases
Optimizing performance or database queries
Building microservices architectures

Rule Categories by Priority

| Priority | Category | Impact | Prefix | |----------|----------|--------|--------| | 1 | Architecture | CRITICAL | arch- | | 2 | Dependency Injection | CRITICAL | di- | | 3 | Error Handling | HIGH | error- | | 4 | Security | HIGH | security- | | 5 | Performance | HIGH | perf- | | 6 | Testing | MEDIUM-HIGH | test- | | 7 | Database & ORM | MEDIUM-HIGH | db- | | 8 | API Design | MEDIUM | api- | | 9 | Microservices | MEDIUM | micro- | | 10 | DevOps & Deployment | LOW-MEDIUM | devops- |

Quick Reference

1. Architecture (CRITICAL)

arch-avoid-circular-deps - Avoid circular module dependencies
arch-feature-modules - Organize by feature, not technical layer
arch-module-sharing - Proper module exports/imports, avoid duplicate providers
arch-single-responsibility - Focused services over "god services"
arch-use-repository-pattern - Abstract database logic for testability
arch-use-events - Event-driven architecture for decoupling

2. Dependency Injection (CRITICAL)

di-avoid-service-locator - Avoid service locator anti-pattern
di-interface-segregation - Interface Segregation Principle (ISP)
di-liskov-substitution - Liskov Substitution Principle (LSP)
di-prefer-constructor-injection - Constructor over property injection
di-scope-awareness - Understand singleton/request/transient scopes
di-use-interfaces-tokens - Use injection tokens for interfaces

3. Error Handling (HIGH)

error-use-exception-filters - Centralized exception handling
error-throw-http-exceptions - Use NestJS HTTP exceptions
error-handle-async-errors - Handle async errors properly

4. Security (HIGH)

security-auth-jwt - Secure JWT authentication
security-validate-all-input - Validate with class-validator
security-use-guards - Authentication and authorization guards
security-sanitize-output - Prevent XSS attacks
security-rate-limiting - Implement rate limiting

5. Performance (HIGH)

perf-async-hooks - Proper async lifecycle hooks
perf-use-caching - Implement caching strategies
perf-optimize-database - Optimize database queries
perf-lazy-loading - Lazy load modules for faster startup

6. Testing (MEDIUM-HIGH)

test-use-testing-module - Use NestJS testing utilities
test-e2e-supertest - E2E testing with Supertest
test-mock-external-services - Mock external dependencies

7. Database & ORM (MEDIUM-HIGH)

db-use-transactions - Transaction management
db-avoid-n-plus-one - Avoid N+1 query problems
db-use-migrations - Use migrations for schema changes

8. API Design (MEDIUM)

api-use-dto-serialization - DTO and response serialization
api-use-interceptors - Cross-cutting concerns
api-versioning - API versioning strategies
api-use-pipes - Input transformation with pipes

9. Microservices (MEDIUM)

micro-use-patterns - Message and event patterns
micro-use-health-checks - Health checks for orchestration
micro-use-queues - Background job processing

10. DevOps & Deployment (LOW-MEDIUM)

devops-use-config-module - Environment configuration
devops-use-logging - Structured logging
devops-graceful-shutdown - Zero-downtime deployments

How to Use

Read individual rule files for detailed explanations and code examples:

rules/arch-avoid-circular-deps.md
rules/security-validate-all-input.md
rules/_sections.md

Each rule file contains:

Brief explanation of why it matters
Incorrect code example with explanation
Correct code example with explanation
Additional context and references

Full Compiled Document

For the complete guide with all rules expanded: AGENTS.md

Want to see if asymmetric-al/nestjs-best-practices would activate on your phrasing? Try it before you install — no LLM call, no signup.

Latest benchmark · publisher runVerified

8/20/2026, 06:27 UTC · 23 cases

Lift

+4%

100% vs 96%

Agent turns

1.0 vs 1.0

Tokens

+40%

3,203 vs 2,292.48

fail → pass · 1pass → pass · 22

Per-case results (23)

Case	Status	Duration (ms)			Turns			Tokens			Tool calls
Case	Status	Without	With	Δ	Without	With	Δ	Without	With	Δ	Without	With	Δ
case-04 When a user registers in our NestJS app, the UserController calls UserService.createUser(), which directly calls EmailService.sendWelcomeEmail(), AnalyticsService.trackSignup(), and AuditService.logAction() sequentially within the registration transaction. How should these secondary actions be handled?	pass→pass	15,804	11,929	-25%	1	1	0%	2,791	3,385	+21%	0	0	—
case-05 In a NestJS route handler, a developer injected ModuleRef into the controller and called this.moduleRef.get(PaymentService) inside the checkout method to dynamically retrieve the service. How should PaymentService be provided to the controller?	fail→pass	9,395	7,164	-24%	1	1	0%	1,742	2,409	+38%	0	0	—
case-01 We have ServiceA needing ServiceB, and ServiceB needing ServiceA in a NestJS app. A developer proposed wrapping both injected parameters in forwardRef() as the standard solution across our codebase. How should this dependency loop be resolved?	pass→pass	13,622	12,055	-12%	1	1	0%	2,317	3,352	+45%	0	0	—
case-02 I am structuring a new NestJS codebase for an e-commerce platform. I plan to create top-level directories named controllers/, services/, and interfaces/ to put all controllers and services across the app into their respective layer folders. How should I structure these modules?	pass→pass	12,816	8,919	-30%	1	1	0%	2,221	2,908	+31%	0	0	—
case-03 Our NestJS OrderService currently handles validating user cart items, calculating tax, writing orders to Postgres, generating PDF invoices, sending confirmation emails, and dispatching analytics events. Is this design acceptable, and how should it be structured?	pass→pass	16,267	14,154	-13%	1	1	0%	2,827	3,836	+36%	0	0	—
case-06 In a NestJS injectable service, a developer used @Inject(COMPUTATION_SERVICE) directly on a class field property instead of declaring it in the constructor. Which injection style should be preferred for class dependencies?	pass→pass	10,159	7,071	-30%	1	1	0%	1,617	2,403	+49%	0	0	—
case-07 To store request-specific tenant IDs easily, a team set the database repository provider scope to Scope.REQUEST across the entire NestJS application. What performance impact does this have, and how should service scope be configured?	pass→pass	16,127	14,964	-7%	1	1	0%	2,713	3,748	+38%	0	0	—
case-08 A NestJS developer is adding try-catch blocks to every single method in every controller, manually mapping errors to HTTP status codes and returning custom JSON error payloads. How should error responses be handled cleanly across NestJS routes?	pass→pass	12,812	12,306	-4%	1	1	0%	2,393	3,577	+49%	0	0	—
case-09 When a resource is missing in a NestJS service, the code currently executes 'throw new Error("User not found")'. What error class should be thrown when handling HTTP request failures in NestJS?	pass→pass	6,832	6,076	-11%	1	1	0%	1,340	2,284	+70%	0	0	—
case-10 In a NestJS POST /users endpoint, incoming request body validation is performed using manual 'if (!body.email)' conditional statements inside the controller method body. How should request body validation be implemented?	pass→pass	9,261	9,419	+2%	1	1	0%	1,762	2,745	+56%	0	0	—
case-11 A developer wrote authorization logic directly inside a NestJS controller handler method by decoding the Bearer token manually from req.headers.authorization and checking user roles in an if statement. How should access control be managed in NestJS?	pass→pass	13,173	11,781	-11%	1	1	0%	2,354	3,415	+45%	0	0	—
case-12 We need to prevent brute-force login attempts on a NestJS auth endpoint. A developer suggests writing a custom Express inline middleware with a global JavaScript object tracking IP timestamps. How should rate limiting be implemented in NestJS?	pass→pass	14,264	12,136	-15%	1	1	0%	2,526	3,342	+32%	0	0	—
case-13 A NestJS application queries an external database on every API request to retrieve configuration settings that change only once a month. How should this read heavy, static data access be optimized?	pass→pass	13,419	11,501	-14%	1	1	0%	2,409	3,224	+34%	0	0	—
case-14 In a unit test for a NestJS service, a developer manually instantiated dependencies using 'new UserService(new UserRepository(), new ConfigService())', making it hard to mock database calls. How should dependencies be managed in NestJS service unit tests?	pass→pass	11,748	9,664	-18%	1	1	0%	2,186	3,037	+39%	0	0	—
case-15 In a NestJS controller fetching posts, the code retrieves all posts and then executes 'await authorRepository.findOne({ where: { id: post.authorId } })' inside a Array.map loop. How should this query pattern be refactored?	pass→pass	11,974	12,122	+1%	1	1	0%	2,134	3,461	+62%	0	0	—
case-16 To handle database schema changes in production, a developer configured TypeORM with 'synchronize: true' in the production NestJS configuration file. Is this safe, and how should database schema changes be deployed?	pass→pass	12,722	12,041	-5%	1	1	0%	2,178	3,219	+48%	0	0	—
case-17 A NestJS controller route returns raw TypeORM entity instances directly from service calls to the client, exposing internal database column names and password hashes. How should response data be sanitized and formatted?	pass→pass	13,478	12,649	-6%	1	1	0%	2,490	3,507	+41%	0	0	—
case-18 To support API version 2 alongside version 1 in a NestJS backend, a developer is adding 'if (req.query.v === "2")' branches inside every controller action. How should API versioning be configured in NestJS?	pass→pass	10,877	8,427	-23%	1	1	0%	2,073	2,732	+32%	0	0	—
case-19 Across several services in a NestJS app, developers are directly referencing process.env.DATABASE_URL, process.env.JWT_SECRET, and process.env.PORT. How should application configuration be managed?	pass→pass	13,814	9,754	-29%	1	1	0%	2,629	3,053	+16%	0	0	—
case-20 A NestJS backend application uses console.log() and console.error() statements throughout services and controllers for application logging. How should logging be handled in NestJS?	pass→pass	13,731	12,703	-7%	1	1	0%	2,486	3,746	+51%	0	0	—
case-21 How do I configure CORS for a plain Express.js application running on Node.js without using NestJS or any NestJS modules?	pass→pass	11,666	10,855	-7%	1	1	0%	2,176	3,256	+50%	0	0	—
case-22 How do I implement client-side data fetching cache in a React single-page frontend application using TanStack Query?	pass→pass	15,381	12,170	-21%	1	1	0%	2,836	3,493	+23%	0	0	—
case-23 How do I author a multi-stage Dockerfile for a generic Node.js application to minimize final image size and leverage build caching?	pass→pass	14,005	13,135	-6%	1	1	0%	2,527	3,537	+40%	0	0	—

These cases were also screened by the skill’s intent / safety pass.See the Trust review ↗Reproduce this benchmark in Colab ↗

How this skill was measured

DecimalAI ran this skill against gemini-3.6-flash twice over the same eval suite — once with the skill loaded and once without — and compared the two runs case by case. 23 cases were attempted. The headline lift of +4 percentage points is the difference between those two pass rates over the 23 comparable cases.

Model measured: gemini-3.6-flash
Graded by: gemini-3.6-flash
Grading method: judged
Verification: verified
Pass rate without the skill: 95.7%
Pass rate with the skill: 100%
Cases attempted: 23
Cases counted toward lift: 23
Cases that regressed: 0
Skill version measured: v1
Run completed: 8/20/2026, 06:27 UTC

Measured example — same prompt, with vs. without the skill · from the benchmark run · case case-05

Prompt

In a NestJS route handler, a developer injected ModuleRef into the controller and called this.moduleRef.get(PaymentService) inside the checkout method to dynamically retrieve the service. How should PaymentService be provided to the controller?

Without the skill loaded, the model failed this case. With it loaded, the same prompt on the same model passed. This is one improved case from the latest verified run; every case, including any that regressed, is in the table above.

Show both answers

SkillScore blends 4 signalsno signals yet

BenchmarkRun a verified benchmark with positive lift

Live evalNeeds ≥20 evaluated traces in 30 days

AI ratingNeeds ≥10 rated traces

AdoptionNeeds ≥10 serves across ≥2 orgs in 30 days

No signals yet — run a benchmark or collect evaluated traces to earn a score.

Verified on gemini-3.6-flash · re-tested today

Other measured skills in the registry, with their headline benchmark lift.