standards-global

korallis 的头像作者 korallis

现代全栈TypeScript开发的全局编码约定和最佳实践。在实现任何代码时加载,确保整个代码库中命名一致、错误处理、文件组织、类型安全和代码风格的一致性。

📖 中文导读:现代全栈TypeScript开发的全局编码约定和最佳实践。在实现任何代码时加载,确保整个代码库中命名一致、错误处理、文件组织、类型安全和代码风格的一致性。 以下正文为该技能的原始 SKILL.md 内容(英文),上方安装命令可直接使用。

name: standards-global description: 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.

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