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

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/