---

name: project-standards description: Core coding standards, SOLID principles, Clean Code, and naming conventions. Use this skill for any coding task to ensure consistency.

Project Standards

This skill provides the foundational coding standards that apply to ALL projects regardless of tech stack.

When to Use

• Use this skill for ANY coding task
• This skill is the foundation that other stack-specific skills build upon
• Always read this skill FIRST before reading stack-specific skills

Instructions

1. Analyze Environment First

Before applying any rules, READ the dependency files:

• package.json (Node/TS projects)
• composer.json (PHP/Laravel)
• go.mod (Go projects)
• requirements.txt / pyproject.toml (Python)

Principle: Respect legacy. If the project already uses a specific library, USE IT.

---

SOLID Principles (Strict Enforcement)

S - Single Responsibility

A class/function must have ONE and only ONE reason to change.

• Violation: A UserService that handles DB queries AND sends Emails.
• Fix: Split into UserRepository and EmailNotificationService.

O - Open/Closed

Open for extension, closed for modification. Use Interfaces/Abstract classes.

L - Liskov Substitution

Subtypes must be substitutable for their base types.

I - Interface Segregation

Clients should not be forced to depend on interfaces they do not use. Split large interfaces.

D - Dependency Inversion

Depend on abstractions, not concretions.

• Rule: Always inject dependencies via Constructor. Never use new Class() inside business logic.

---

Clean Code Core

• DRY (Don't Repeat Yourself): Logic duplicated > 2 times must be extracted.
• KISS (Keep It Simple, Stupid): Simplest solution is usually best. Avoid Over-Engineering.
• YAGNI (You Ain't Gonna Need It): Do not implement features "just in case".

---

Function/Method Rules

• Max Lines: < 30 lines ideally.
• Max Params: < 3 parameters. Use DTO/Object if more needed.
• No Boolean Flags: Split functions instead of createUser(isSuperAdmin: boolean).

---

Naming Conventions

By Language

Category	JS/TS	Python	Go	PHP
Files	kebab-case	snake_case	snake_case	PascalCase
Classes	PascalCase	PascalCase	PascalCase	PascalCase
Functions	camelCase	snake_case	camelCase	camelCase
Variables	camelCase	snake_case	camelCase	$camelCase
Constants	SCREAMING_SNAKE	SCREAMING_SNAKE	PascalCase	SCREAMING_SNAKE

Structural Naming

• Helpers: Module-specific support. Location: modules/<name>/helpers/
• Common/Shared: Generic reusable. Location: src/common/ or src/shared/
• Services: Must end with Service, Handler, or UseCase.
• DTOs/Types: Must include suffix (e.g., user.dto.ts, order_response.go).

---

Comments & Documentation

Commenting Rules

• Zero-Comment Policy: Do not comment obvious code.
• Complex Logic Only: Only comment algorithms or counter-intuitive decisions.
• NO ICONS/EMOJIS: Absolutely NO decorations in comments. Raw text only.
  • Bad: // Fast calculation function
  • Good: // Uses binary search for O(log n) complexity.

Function Documentation (JSDoc/GoDoc/Docstring)

• Public API Only: Only document exported functions.
• Concise: 1-2 sentences max. Do not restate parameter names.

// Bad: Redundant
/**
 * Adds two numbers.
 * @param a First number
 * @param b Second number
 * @returns The sum
 */
const add = (a: number, b: number) => a + b;

// Good: Necessary context only
/**
 * Calculates tax based on local VAT rules (2024 reform).
 */
const calculateTax = (price: number, region: string) => { ... }

---

RESTful API Standards

HTTP Verbs

• GET - Read (Idempotent, Safe)
• POST - Create
• PUT - Full Update
• PATCH - Partial Update
• DELETE - Remove

Status Codes

• 200 OK - Success (Read/Update)
• 201 Created - Success (Create)
• 204 No Content - Success (Delete)
• 400 Bad Request - Validation Error
• 401 Unauthorized - Auth missing
• 403 Forbidden - No permission
• 404 Not Found - Resource not exist
• 500 Internal Server Error - App crash

Response Envelope

{
  "success": true,
  "data": {},
  "meta": { "page": 1, "limit": 10, "total": 100 },
  "error": { "code": "ERROR_CODE", "message": "...", "details": [] },
  "timestamp": "2024-01-20T10:00:00Z"
}

URL Naming

• Collection: /users (Plural, kebab-case)
• Resource: /users/123
• Sub-resource: /users/123/orders

---

Database Standards

• Naming: snake_case for tables/columns.
• Primary Keys: UUID (distributed) or BigInt.
• Audit Fields: created_at, updated_at, deleted_at mandatory.

---

Folder Structure

Option A: Feature-based (Recommended)

src/
├── features/
│   ├── auth/
│   │   ├── components/
│   │   ├── hooks/
│   │   ├── api/
│   │   └── index.ts
│   └── dashboard/

Option B: Layer-based (Classic)

src/
├── components/
├── pages/
├── services/
├── utils/
└── hooks/