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/

project-standards