NestJS Best Practices

I am back to NestJS, and have a few hours a week to get back to maintaining my few OSS repos. Sorry for the delay all!

📖 For Humans <3

A structured repository for creating and maintaining NestJS Best Practices optimized for agents and LLMs.

<div align="center">
  <a href="https://semfora.ai">
    <img src="assets/semfora-logo.svg" alt="Semfora" width="380">
  </a>
</div>

From the maintainer: I built this skill because agents write better NestJS when they can see real context. Context is also my day job: I founded Semfora, a semantic code analysis engine that hands coding agents call graphs, module maps, and change blast radius through nine MCP tools.

Semfora launches on Product Hunt on Tuesday, July 28. Support there on launch day means a lot.

Installation

Install this skill using skills:

# GitHub shorthand
npx skills add Kadajett/agent-nestjs-skills

# Install globally (available across all projects)
npx skills add Kadajett/agent-nestjs-skills --global

# Install for specific agents
npx skills add Kadajett/agent-nestjs-skills -a claude-code -a cursor

Supported Agents

• Claude Code
• OpenCode
• Codex
• Cursor
• Antigravity
• Roo Code

Structure

• skills/nestjs-best-practices/ - The installable skill (this is what skills add copies into your project)
  • SKILL.md - Skill entry point and quick reference
  • rules/ - Individual rule files (one per rule)
    • _sections.md - Section metadata (titles, impacts, descriptions)
    • _template.md - Template for creating new rules
    • area-description.md - Individual rule files
• scripts/ - Build scripts and utilities
• metadata.json - Document metadata (version, organization, abstract)
• AGENTS.md - Compiled output (generated)

Getting Started

1. Install dependencies:

   cd scripts && npm install
   

2. Build AGENTS.md from rules:

   npm run build
   # or
   ./scripts/build.sh
   

Creating a New Rule

1. Copy skills/nestjs-best-practices/rules/_template.md to skills/nestjs-best-practices/rules/area-description.md
2. Choose the appropriate area prefix:
   • arch- for Architecture (Section 1)
   • di- for Dependency Injection (Section 2)
   • error- for Error Handling (Section 3)
   • security- for Security (Section 4)
   • perf- for Performance (Section 5)
   • test- for Testing (Section 6)
   • db- for Database & ORM (Section 7)
   • api- for API Design (Section 8)
   • micro- for Microservices (Section 9)
   • devops- for DevOps & Deployment (Section 10)
3. Fill in the frontmatter and content
4. Ensure you have clear examples with explanations
5. Run the build script to regenerate AGENTS.md

Rule File Structure

Each rule file should follow this structure:

---
title: Rule Title Here
impact: MEDIUM
impactDescription: Optional description
tags: tag1, tag2, tag3
---

## Rule Title Here

Brief explanation of the rule and why it matters.

**Incorrect (description of what's wrong):**

```typescript
// Bad code example

Correct (description of what's right):

// Good code example

Optional explanatory text after examples.

Reference: NestJS Documentation

File Naming Convention

• Files starting with _ are special (excluded from build)
• Rule files: area-description.md (e.g., arch-avoid-circular-deps.md)
• Section is automatically inferred from filename prefix
• Rules are sorted alphabetically by title within each section
• IDs (e.g., 1.1, 1.2) are auto-generated during build

Impact Levels

Scripts

• npm run build (in scripts/) - Compile rules into AGENTS.md

Contributing

When adding or modifying rules:

1. Use the correct filename prefix for your section
2. Follow the _template.md structure
3. Include clear bad/good examples with explanations
4. Add appropriate tags
5. Run the build script to regenerate AGENTS.md
6. Rules are automatically sorted by title - no need to manage numbers!

Documentation Website

The documentation website source code lives on the docs branch. This separation keeps the skill installation lightweight while maintaining the full documentation site.

To contribute to the website:

git checkout docs
cd website
npm install
npm run dev

Acknowledgments

• Inspired by the Vercel React Best Practices skill structure
• Compatible with skills for easy installation across coding agents

Compatible Agents

These NestJS skills work with:

• Claude Code - Anthropic's official CLI
• AdaL - Self-evolving AI coding agent with MCP support