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/