1# NestJS Best Practices
2 
3📖 [For Humans <3](https://kadajett.github.io/agent-nestjs-skills/)
4 
5A structured repository for creating and maintaining NestJS Best Practices optimized for agents and LLMs.
6 
7## Installation
8 
9Install this skill using [skills](https://github.com/vercel-labs/skills):
10 
11```bash
12# GitHub shorthand
13npx skills add Kadajett/agent-nestjs-skills
14 
15# Install globally (available across all projects)
16npx skills add Kadajett/agent-nestjs-skills --global
17 
18# Install for specific agents
19npx skills add Kadajett/agent-nestjs-skills -a claude-code -a cursor
20```
21 
22### Supported Agents
23 
24- Claude Code
25- OpenCode
26- Codex
27- Cursor
28- Antigravity
29- Roo Code
30 
31## Structure
32 
33- `rules/` - Individual rule files (one per rule)
34  - `_sections.md` - Section metadata (titles, impacts, descriptions)
35  - `_template.md` - Template for creating new rules
36  - `area-description.md` - Individual rule files
37- `scripts/` - Build scripts and utilities
38- `metadata.json` - Document metadata (version, organization, abstract)
39- __`AGENTS.md`__ - Compiled output (generated)
40 
41## Getting Started
42 
431. Install dependencies:
44   ```bash
45   cd scripts && npm install
46   ```
47 
482. Build AGENTS.md from rules:
49   ```bash
50   npm run build
51   # or
52   ./scripts/build.sh
53   ```
54 
55## Creating a New Rule
56 
571. Copy `rules/_template.md` to `rules/area-description.md`
582. Choose the appropriate area prefix:
59   - `arch-` for Architecture (Section 1)
60   - `di-` for Dependency Injection (Section 2)
61   - `error-` for Error Handling (Section 3)
62   - `security-` for Security (Section 4)
63   - `perf-` for Performance (Section 5)
64   - `test-` for Testing (Section 6)
65   - `db-` for Database & ORM (Section 7)
66   - `api-` for API Design (Section 8)
67   - `micro-` for Microservices (Section 9)
68   - `devops-` for DevOps & Deployment (Section 10)
693. Fill in the frontmatter and content
704. Ensure you have clear examples with explanations
715. Run the build script to regenerate AGENTS.md
72 
73## Rule File Structure
74 
75Each rule file should follow this structure:
76 
77```markdown
78---
79title: Rule Title Here
80impact: MEDIUM
81impactDescription: Optional description
82tags: tag1, tag2, tag3
83---
84 
85## Rule Title Here
86 
87Brief explanation of the rule and why it matters.
88 
89**Incorrect (description of what's wrong):**
90 
91```typescript
92// Bad code example
93```
94 
95**Correct (description of what's right):**
96 
97```typescript
98// Good code example
99```
100 
101Optional explanatory text after examples.
102 
103Reference: [NestJS Documentation](https://docs.nestjs.com)
104 
105 
106## File Naming Convention
107 
108- Files starting with `_` are special (excluded from build)
109- Rule files: `area-description.md` (e.g., `arch-avoid-circular-deps.md`)
110- Section is automatically inferred from filename prefix
111- Rules are sorted alphabetically by title within each section
112- IDs (e.g., 1.1, 1.2) are auto-generated during build
113 
114## Impact Levels
115 
116| Level | Description |
117|-------|-------------|
118| CRITICAL | Violations cause runtime errors, security vulnerabilities, or architectural breakdown |
119| HIGH | Significant impact on reliability, security, or maintainability |
120| MEDIUM-HIGH | Notable impact on quality and developer experience |
121| MEDIUM | Moderate impact on code quality and best practices |
122| LOW-MEDIUM | Minor improvements for consistency and maintainability |
123 
124## Scripts
125 
126- `npm run build` (in scripts/) - Compile rules into AGENTS.md
127 
128## Contributing
129 
130When adding or modifying rules:
131 
1321. Use the correct filename prefix for your section
1332. Follow the `_template.md` structure
1343. Include clear bad/good examples with explanations
1354. Add appropriate tags
1365. Run the build script to regenerate AGENTS.md
1376. Rules are automatically sorted by title - no need to manage numbers!
138 
139## Documentation Website
140 
141The 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.
142 
143To contribute to the website:
144 
145```bash
146git checkout docs
147cd website
148npm install
149npm run dev
150```
151 
152## Acknowledgments
153 
154- Inspired by the [Vercel React Best Practices](https://github.com/vercel-labs/agent-skills) skill structure
155- Compatible with [skills](https://github.com/vercel-labs/skills) for easy installation across coding agents
156 
157## Compatible Agents
158 
159These NestJS skills work with:
160 
161- [Claude Code](https://claude.ai/code) - Anthropic's official CLI
162- [AdaL](https://sylph.ai/adal) - Self-evolving AI coding agent with MCP support
163 
164