standards-global

Global coding conventions and best practices for modern full-stack TypeScript development. Load when implementing any code to ensure consistent naming, error handling, file organization, type safety, and code style across the entire codebase.

⭐2stars🔀0forks📁View on GitHub🕐Updated Dec 18, 2025⬇️1downloads

When & Why to Use This Skill

This Claude skill establishes a comprehensive framework of global coding conventions and best practices specifically tailored for modern full-stack TypeScript development. It serves as a definitive style guide to ensure consistency in naming, error handling, file organization, and type safety across an entire codebase, significantly reducing technical debt and improving maintainability.

Use Cases

  • Standardizing Project Structure: Automatically apply kebab-case for files and camelCase for functions to maintain a clean and predictable directory hierarchy.
  • Enhancing Type Safety: Implement advanced TypeScript patterns such as discriminated unions and the 'satisfies' operator to ensure robust compile-time checks.
  • Unified Error Management: Deploy a centralized error hierarchy and Result patterns to handle operational errors consistently across both frontend and backend.
  • Environment Variable Validation: Use Zod-based schemas to strictly validate environment variables, preventing runtime crashes due to missing configurations.
  • Code Quality Enforcement: Apply strict rules for file length, function complexity, and parameter counts to keep the codebase modular and readable.
  • Onboarding and Code Reviews: Use the standards as a checklist during peer reviews or as a guide for onboarding new developers to ensure they follow team conventions from day one.
namestandards-global
descriptionGlobal coding conventions and best practices for modern full-stack TypeScript development. Load when implementing any code to ensure consistent naming, error handling, file organization, type safety, and code style across the entire codebase.

Global Standards

Universal coding conventions that apply to all code in modern TypeScript-first projects.

When to Use

  • Starting any implementation task
  • Reviewing code for consistency
  • Setting up new files or modules
  • Onboarding new team members

Resources

Resource Use When
coding-conventions.md Naming, formatting, organization
common-patterns.md Reusable TypeScript patterns
communication-style.md Documentation standards

Quick Reference

Naming Conventions

Type Convention Example
Files kebab-case user-service.ts
Functions camelCase getUserById
Types/Interfaces PascalCase UserConfig
Constants SCREAMING_SNAKE_CASE MAX_RETRIES
Booleans is, has, should, can isLoading
Hooks use prefix useAuth
Event handlers handle prefix handleSubmit

Type Safety

// ✅ Use satisfies for type checking with inference
const config = {
  apiUrl: 'https://api.example.com',
  timeout: 5000,
} satisfies Config;

// ✅ Discriminated unions for state
type AsyncState<T> = 
  | { status: 'idle' }
  | { status: 'loading' }
  | { status: 'success'; data: T }
  | { status: 'error'; error: Error };

// ❌ Never use any
function processData(data: any) { /* ... */ }

Error Handling

// Unified error hierarchy
class AppError extends Error {
  constructor(
    message: string,
    public readonly code: string,
    public readonly statusCode: number = 500,
    public readonly isOperational: boolean = true,
    public readonly context?: Record<string, unknown>
  ) {
    super(message);
    this.name = this.constructor.name;
  }
}

class NotFoundError extends AppError {
  constructor(resource: string, id: string) {
    super(`${resource} not found: ${id}`, 'NOT_FOUND', 404, true, { resource, id });
  }
}

// Result pattern
type Result<T, E = AppError> = 
  | { success: true; data: T }
  | { success: false; error: E };

Environment Variables

// lib/env.server.ts - Server-only (NEVER import in client code)
import { z } from 'zod';

const serverEnvSchema = z.object({
  DATABASE_URL: z.string().url(),
  STRIPE_SECRET_KEY: z.string().startsWith('sk_'),
});

export const serverEnv = serverEnvSchema.parse(process.env);

// lib/env.client.ts - Safe for client bundles
const clientEnvSchema = z.object({
  NEXT_PUBLIC_API_URL: z.string().url(),
});

export const clientEnv = clientEnvSchema.parse({
  NEXT_PUBLIC_API_URL: process.env.NEXT_PUBLIC_API_URL,
});

Code Quality Rules

  • Maximum file length: 300 lines
  • Maximum function length: 50 lines
  • Maximum parameters: 3 (use object if more)
  • No magic numbers: Use named constants
  • No nested ternaries: Use if/else or early returns

Strict TypeScript

{
  "compilerOptions": {
    "strict": true,
    "noImplicitAny": true,
    "strictNullChecks": true,
    "noUncheckedIndexedAccess": true,
    "noImplicitReturns": true
  }
}

Amp Tools to Use

  • finder - Find existing patterns to follow
  • Read - Check neighboring files for conventions
  • oracle - Guidance on complex architectural decisions
  • standards-frontend - Frontend-specific patterns
  • standards-backend - Backend-specific patterns
  • standards-testing - Testing conventions