NestJS Best Practices

📖 For Humans <3

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

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

• 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

1. Build AGENTS.md from rules:

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

Creating a New Rule

1. Copy rules/_template.md to 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)

1. Fill in the frontmatter and content
2. Ensure you have clear examples with explanations
3. 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):**

// Bad code example

**Correct (description of what's right):**

// Good code example

Optional explanatory text after examples.

Reference: [NestJS Documentation](https://docs.nestjs.com)


## 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

| Level | Description |
|-------|-------------|
| CRITICAL | Violations cause runtime errors, security vulnerabilities, or architectural breakdown |
| HIGH | Significant impact on reliability, security, or maintainability |
| MEDIUM-HIGH | Notable impact on quality and developer experience |
| MEDIUM | Moderate impact on code quality and best practices |
| LOW-MEDIUM | Minor improvements for consistency and maintainability |

## 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](https://github.com/Kadajett/agent-nestjs-skills/tree/docs/website). 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](https://github.com/vercel-labs/agent-skills) skill structure
- Compatible with [skills](https://github.com/vercel-labs/skills) for easy installation across coding agents

## Compatible Agents

These NestJS skills work with:

- [Claude Code](https://claude.ai/code) - Anthropic's official CLI
- [AdaL](https://sylph.ai/adal) - Self-evolving AI coding agent with MCP support