trackgo-be/.agents/skills/project-guidelines-example/SKILL.md

name, description

name	description
project-guidelines-example	NestJS modular TDD project guidelines with Drizzle and PostgreSQL. Use when scaffolding features, reviewing structure, or aligning code with this repo's conventions.

Project Guidelines

Project skill for this NestJS API. Contains architecture, file structure, code patterns, testing, and deployment conventions.

When to Use

Reference this skill when working on this project. It contains:

• Architecture overview
• File structure
• Code patterns
• Testing requirements
• Deployment workflow

---

Architecture Overview

Tech Stack:

• Backend: NestJS
• Database: PostgreSQL using Drizzle ORM
• Testing: NestJS TestingModule (unit) and Supertest (E2E)

---

File Structure

project/
├── src/
│   ├── main.ts                          # Application bootstrap
│   ├── app.module.ts                    # Root module
│   ├── common/                          # Shared cross-cutting concerns
│   │   ├── decorators/
│   │   ├── filters/
│   │   ├── guards/
│   │   ├── interceptors/
│   │   └── pipes/
│   ├── config/                          # Env and database config
│   └── modules/                         # Feature modules (one folder per domain)
│       ├── auth/
│       │   ├── auth.module.ts
│       │   ├── auth.controller.ts
│       │   ├── auth.controller.spec.ts  # Unit tests (colocated)
│       │   ├── auth.service.ts
│       │   ├── auth.service.spec.ts
│       │   ├── dto/
│       │   └── strategies/
│       └── users/
│           ├── users.module.ts
│           ├── users.controller.ts
│           ├── users.controller.spec.ts
│           ├── users.service.ts
│           ├── users.service.spec.ts
│           └── dto/
├── test/                                # E2E tests (NestJS convention)
│   ├── jest-e2e.json
│   ├── app.e2e-spec.ts
│   ├── auth.e2e-spec.ts
│   └── users.e2e-spec.ts
├── drizzle/                             # Schema and migrations
│   ├── schema.ts
│   └── migrations/
├── drizzle.config.ts                    # Drizzle Kit config
├── deploy/                              # Deployment configs
├── docs/                                # Documentation
└── scripts/                             # Utility scripts

---

Code Patterns

Controller + DTO

export class CreateUserDto {
  @IsEmail()
  email: string;

  @IsString()
  @MinLength(8)
  password: string;
}

@Controller('users')
export class UsersController {
  constructor(private readonly usersService: UsersService) {}

  @Post()
  create(@Body() dto: CreateUserDto) {
    return this.usersService.create(dto);
  }
}

Drizzle Repository

@Injectable()
export class UsersRepository {
  constructor(@Inject(DRIZZLE) private readonly db: DrizzleDB) {}

  findById(id: string) {
    return this.db.query.users.findFirst({
      where: eq(users.id, id),
    });
  }

  create(data: typeof users.$inferInsert) {
    return this.db.insert(users).values(data).returning();
  }
}

---

Testing Requirements

# Unit tests
npm test

# Coverage
npm run test:cov

# E2E
npm run test:e2e

Unit test (colocated *.spec.ts):

const moduleRef = await Test.createTestingModule({
  providers: [
    UsersService,
    { provide: UsersRepository, useValue: { findById: jest.fn() } },
  ],
}).compile();

const service = moduleRef.get(UsersService);

E2E test (test/*.e2e-spec.ts):

describe('UsersController (e2e)', () => {
  it('/users (POST)', () => {
    return request(app.getHttpServer())
      .post('/users')
      .send({ email: 'ada@example.com', password: 'secret123' })
      .expect(201);
  });
});

---

Deployment Workflow

Pre-Deployment Checklist

• All tests passing locally
• npm run build succeeds
• npm run test:e2e passes
• No hardcoded secrets
• Environment variables documented
• Drizzle migrations applied

Deployment Commands

npm run build
npx drizzle-kit migrate
# deploy the NestJS API (Cloud Run, Fly, or similar)

Environment Variables

DATABASE_URL=postgresql://user:pass@host:5432/tracking
PORT=3000
JWT_SECRET=...

---

Critical Rules

1. No emojis in code, comments, or documentation
2. Immutability - never mutate objects or arrays
3. TDD - write tests before implementation
4. 80% coverage minimum
5. Many small files - 200-400 lines typical, 800 max
6. No console.log in production code
7. Exception filters for HTTP errors, not raw try/catch in controllers
8. Input validation with class-validator DTOs

---

Related Skills

• .agents/skills/coding-standards/ - General coding best practices
• .agents/skills/backend-patterns/ - API and database patterns
• .agents/skills/nestjs-best-practices/ - NestJS architecture and security
• .agents/skills/tdd-workflow/ - Test-driven development methodology