Skip to content

Commit 5484e56

Browse files
JoelVR17JoelVR17
authored
Merge pull request #9 from Ding-Payments/main
Main
2 parents c34489e + ced4440 commit 5484e56

155 files changed

Lines changed: 39420 additions & 0 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.agents/skills/nestjs-best-practices/AGENTS.md‎

Lines changed: 5958 additions & 0 deletions
Large diffs are not rendered by default.

‎.agents/skills/nestjs-best-practices/README.md‎

Lines changed: 163 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,163 @@
1+
# NestJS Best Practices
2+
3+
📖 [For Humans <3](https://kadajett.github.io/agent-nestjs-skills/)
4+
5+
A structured repository for creating and maintaining NestJS Best Practices optimized for agents and LLMs.
6+
7+
## Installation
8+
9+
Install this skill using [skills](https://github.com/vercel-labs/skills):
10+
11+
```bash
12+
# GitHub shorthand
13+
npx skills add Kadajett/agent-nestjs-skills
14+
15+
# Install globally (available across all projects)
16+
npx skills add Kadajett/agent-nestjs-skills --global
17+
18+
# Install for specific agents
19+
npx 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+
43+
1. Install dependencies:
44+
```bash
45+
cd scripts && npm install
46+
```
47+
48+
2. 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+
57+
1. Copy `rules/_template.md` to `rules/area-description.md`
58+
2. 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)
69+
3. Fill in the frontmatter and content
70+
4. Ensure you have clear examples with explanations
71+
5. Run the build script to regenerate AGENTS.md
72+
73+
## Rule File Structure
74+
75+
Each rule file should follow this structure:
76+
77+
```markdown
78+
---
79+
title: Rule Title Here
80+
impact: MEDIUM
81+
impactDescription: Optional description
82+
tags: tag1, tag2, tag3
83+
---
84+
85+
## Rule Title Here
86+
87+
Brief 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+
101+
Optional explanatory text after examples.
102+
103+
Reference: [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+
130+
When adding or modifying rules:
131+
132+
1. Use the correct filename prefix for your section
133+
2. Follow the `_template.md` structure
134+
3. Include clear bad/good examples with explanations
135+
4. Add appropriate tags
136+
5. Run the build script to regenerate AGENTS.md
137+
6. Rules are automatically sorted by title - no need to manage numbers!
138+
139+
## Documentation Website
140+
141+
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.
142+
143+
To contribute to the website:
144+
145+
```bash
146+
git checkout docs
147+
cd website
148+
npm install
149+
npm 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+
159+
These 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+

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

Lines changed: 130 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,130 @@
1+
---
2+
name: nestjs-best-practices
3+
description: 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.
4+
license: MIT
5+
metadata:
6+
author: Kadajett
7+
version: "1.1.0"
8+
---
9+
10+
# NestJS Best Practices
11+
12+
Comprehensive best practices guide for NestJS applications. Contains 40 rules across 10 categories, prioritized by impact to guide automated refactoring and code generation.
13+
14+
## When to Apply
15+
16+
Reference these guidelines when:
17+
18+
- Writing new NestJS modules, controllers, or services
19+
- Implementing authentication and authorization
20+
- Reviewing code for architecture and security issues
21+
- Refactoring existing NestJS codebases
22+
- Optimizing performance or database queries
23+
- Building microservices architectures
24+
25+
## Rule Categories by Priority
26+
27+
| Priority | Category | Impact | Prefix |
28+
|----------|----------|--------|--------|
29+
| 1 | Architecture | CRITICAL | `arch-` |
30+
| 2 | Dependency Injection | CRITICAL | `di-` |
31+
| 3 | Error Handling | HIGH | `error-` |
32+
| 4 | Security | HIGH | `security-` |
33+
| 5 | Performance | HIGH | `perf-` |
34+
| 6 | Testing | MEDIUM-HIGH | `test-` |
35+
| 7 | Database & ORM | MEDIUM-HIGH | `db-` |
36+
| 8 | API Design | MEDIUM | `api-` |
37+
| 9 | Microservices | MEDIUM | `micro-` |
38+
| 10 | DevOps & Deployment | LOW-MEDIUM | `devops-` |
39+
40+
## Quick Reference
41+
42+
### 1. Architecture (CRITICAL)
43+
44+
- `arch-avoid-circular-deps` - Avoid circular module dependencies
45+
- `arch-feature-modules` - Organize by feature, not technical layer
46+
- `arch-module-sharing` - Proper module exports/imports, avoid duplicate providers
47+
- `arch-single-responsibility` - Focused services over "god services"
48+
- `arch-use-repository-pattern` - Abstract database logic for testability
49+
- `arch-use-events` - Event-driven architecture for decoupling
50+
51+
### 2. Dependency Injection (CRITICAL)
52+
53+
- `di-avoid-service-locator` - Avoid service locator anti-pattern
54+
- `di-interface-segregation` - Interface Segregation Principle (ISP)
55+
- `di-liskov-substitution` - Liskov Substitution Principle (LSP)
56+
- `di-prefer-constructor-injection` - Constructor over property injection
57+
- `di-scope-awareness` - Understand singleton/request/transient scopes
58+
- `di-use-interfaces-tokens` - Use injection tokens for interfaces
59+
60+
### 3. Error Handling (HIGH)
61+
62+
- `error-use-exception-filters` - Centralized exception handling
63+
- `error-throw-http-exceptions` - Use NestJS HTTP exceptions
64+
- `error-handle-async-errors` - Handle async errors properly
65+
66+
### 4. Security (HIGH)
67+
68+
- `security-auth-jwt` - Secure JWT authentication
69+
- `security-validate-all-input` - Validate with class-validator
70+
- `security-use-guards` - Authentication and authorization guards
71+
- `security-sanitize-output` - Prevent XSS attacks
72+
- `security-rate-limiting` - Implement rate limiting
73+
74+
### 5. Performance (HIGH)
75+
76+
- `perf-async-hooks` - Proper async lifecycle hooks
77+
- `perf-use-caching` - Implement caching strategies
78+
- `perf-optimize-database` - Optimize database queries
79+
- `perf-lazy-loading` - Lazy load modules for faster startup
80+
81+
### 6. Testing (MEDIUM-HIGH)
82+
83+
- `test-use-testing-module` - Use NestJS testing utilities
84+
- `test-e2e-supertest` - E2E testing with Supertest
85+
- `test-mock-external-services` - Mock external dependencies
86+
87+
### 7. Database & ORM (MEDIUM-HIGH)
88+
89+
- `db-use-transactions` - Transaction management
90+
- `db-avoid-n-plus-one` - Avoid N+1 query problems
91+
- `db-use-migrations` - Use migrations for schema changes
92+
93+
### 8. API Design (MEDIUM)
94+
95+
- `api-use-dto-serialization` - DTO and response serialization
96+
- `api-use-interceptors` - Cross-cutting concerns
97+
- `api-versioning` - API versioning strategies
98+
- `api-use-pipes` - Input transformation with pipes
99+
100+
### 9. Microservices (MEDIUM)
101+
102+
- `micro-use-patterns` - Message and event patterns
103+
- `micro-use-health-checks` - Health checks for orchestration
104+
- `micro-use-queues` - Background job processing
105+
106+
### 10. DevOps & Deployment (LOW-MEDIUM)
107+
108+
- `devops-use-config-module` - Environment configuration
109+
- `devops-use-logging` - Structured logging
110+
- `devops-graceful-shutdown` - Zero-downtime deployments
111+
112+
## How to Use
113+
114+
Read individual rule files for detailed explanations and code examples:
115+
116+
```
117+
rules/arch-avoid-circular-deps.md
118+
rules/security-validate-all-input.md
119+
rules/_sections.md
120+
```
121+
122+
Each rule file contains:
123+
- Brief explanation of why it matters
124+
- Incorrect code example with explanation
125+
- Correct code example with explanation
126+
- Additional context and references
127+
128+
## Full Compiled Document
129+
130+
For the complete guide with all rules expanded: `AGENTS.md`

‎.agents/skills/nestjs-best-practices/rules/_sections.md‎

Lines changed: 56 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,56 @@
1+
# Sections
2+
3+
This file defines all sections, their ordering, impact levels, and descriptions.
4+
The section ID (in parentheses) is the filename prefix used to group rules.
5+
6+
---
7+
8+
## 1. Architecture (arch)
9+
10+
**Impact:** CRITICAL
11+
**Description:** Proper module organization and dependency management are the foundation of maintainable NestJS applications. Circular dependencies and god services are the #1 architecture killer.
12+
13+
## 2. Dependency Injection (di)
14+
15+
**Impact:** CRITICAL
16+
**Description:** NestJS's IoC container is powerful but can be misused. Understanding scopes, injection tokens, and proper patterns is essential for testable code.
17+
18+
## 3. Error Handling (error)
19+
20+
**Impact:** HIGH
21+
**Description:** Consistent error handling improves debugging, user experience, and API reliability. Centralized exception filters ensure uniform error responses.
22+
23+
## 4. Security (security)
24+
25+
**Impact:** HIGH
26+
**Description:** Security vulnerabilities can be catastrophic. Input validation, authentication, authorization, and data protection are non-negotiable.
27+
28+
## 5. Performance (perf)
29+
30+
**Impact:** HIGH
31+
**Description:** Optimizing request handling, caching, and database queries directly impacts application responsiveness and scalability.
32+
33+
## 6. Testing (test)
34+
35+
**Impact:** MEDIUM-HIGH
36+
**Description:** Well-tested applications are more reliable. NestJS testing utilities enable comprehensive unit and e2e coverage.
37+
38+
## 7. Database & ORM (db)
39+
40+
**Impact:** MEDIUM-HIGH
41+
**Description:** Proper database access patterns, transactions, and query optimization are crucial for data-intensive applications.
42+
43+
## 8. API Design (api)
44+
45+
**Impact:** MEDIUM
46+
**Description:** RESTful conventions, versioning, DTOs, and consistent response formats improve API usability and maintainability.
47+
48+
## 9. Microservices (micro)
49+
50+
**Impact:** MEDIUM
51+
**Description:** Building distributed systems requires understanding message patterns, health checks, and inter-service communication.
52+
53+
## 10. DevOps & Deployment (devops)
54+
55+
**Impact:** LOW-MEDIUM
56+
**Description:** Configuration management, structured logging, and graceful shutdown ensure production readiness and zero-downtime deployments.

‎.agents/skills/nestjs-best-practices/rules/_template.md‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,28 @@
1+
---
2+
title: Rule Title Here
3+
impact: MEDIUM
4+
impactDescription: Optional description of impact (e.g., "20-50% improvement")
5+
tags: tag1, tag2
6+
---
7+
8+
## Rule Title Here
9+
10+
**Impact: MEDIUM (optional impact description)**
11+
12+
Brief explanation of the rule and why it matters. This should be clear and concise, explaining the performance implications.
13+
14+
**Incorrect (description of what's wrong):**
15+
16+
```typescript
17+
// Bad code example here
18+
const bad = example()
19+
```
20+
21+
**Correct (description of what's right):**
22+
23+
```typescript
24+
// Good code example here
25+
const good = example()
26+
```
27+
28+
Reference: [Link to documentation or resource](https://example.com)

0 commit comments

Comments
 (0)