SKILL.md

Coding Standards & Best Practices

Universal coding standards applicable across all projects.

Code Quality Principles

1. Readability First

Code is read more than written

Clear variable and function names

Self-documenting code preferred over comments

Consistent formatting

2. KISS (Keep It Simple, Stupid)

Simplest solution that works

Avoid over-engineering

No premature optimization

Easy to understand > clever code

3. DRY (Don't Repeat Yourself)

Extract common logic into functions

Create reusable components

Share utilities across modules

Avoid copy-paste programming

4. YAGNI (You Aren't Gonna Need It)

Don't build features before they're needed

Avoid speculative generality

Add complexity only when required

Start simple, refactor when needed

TypeScript/JavaScript Standards

Variable Naming

// ✅ GOOD: Descriptive names

const marketSearchQuery = 'election'

const isUserAuthenticated = true

const totalRevenue = 1000

// ❌ BAD: Unclear names

const q = 'election'

const flag = true

const x = 1000

Function Naming

// ✅ GOOD: Verb-noun pattern

async function fetchMarketData(marketId: string) { }

function calculateSimilarity(a: number[], b: number[]) { }

function isValidEmail(email: string): boolean { }

// ❌ BAD: Unclear or noun-only

async function market(id: string) { }

function similarity(a, b) { }

function email(e) { }

Immutability Pattern (CRITICAL)

// ✅ ALWAYS use spread operator

const updatedUser = {

  ...user,

  name: 'New Name'

}

const updatedArray = [...items, newItem]

// ❌ NEVER mutate directly

user.name = 'New Name'  // BAD

items.push(newItem)     // BAD

Error Handling

// ✅ GOOD: Comprehensive error handling

async function fetchData(url: string) {

  try {

    const response = await fetch(url)

    if (!response.ok) {

      throw new Error(`HTTP ${response.status}: ${response.statusText}`)

    }

    return await response.json()

  } catch (error) {

    console.error('Fetch failed:', error)

    throw new Error('Failed to fetch data')

  }

}

// ❌ BAD: No error handling

async function fetchData(url) {

  const response = await fetch(url)

  return response.json()

}

Async/Await Best Practices

// ✅ GOOD: Parallel execution when possible

const [users, markets, stats] = await Promise.all([

  fetchUsers(),

  fetchMarkets(),

  fetchStats()

])

// ❌ BAD: Sequential when unnecessary

const users = await fetchUsers()

const markets = await fetchMarkets()

const stats = await fetchStats()

Type Safety

// ✅ GOOD: Proper types

interface Market {

  id: string

  name: string

  status: 'active' | 'resolved' | 'closed'

  created_at: Date

}

function getMarket(id: string): Promise<Market> {

  // Implementation

}

// ❌ BAD: Using 'any'

function getMarket(id: any): Promise<any> {

  // Implementation

}

React Best Practices

Component Structure

// ✅ GOOD: Functional component with types

interface ButtonProps {

  children: React.ReactNode

  onClick: () => void

  disabled?: boolean

  variant?: 'primary' | 'secondary'

}

export function Button({

  children,

  onClick,

  disabled = false,

  variant = 'primary'

}: ButtonProps) {

  return (

    <button

      onClick={onClick}

      disabled={disabled}

      className={`btn btn-${variant}`}

    >

      {children}

    </button>

  )

}

// ❌ BAD: No types, unclear structure

export function Button(props) {

  return <button onClick={props.onClick}>{props.children}</button>

}

Custom Hooks

// ✅ GOOD: Reusable custom hook

export function useDebounce<T>(value: T, delay: number): T {

  const [debouncedValue, setDebouncedValue] = useState<T>(value)

  useEffect(() => {

    const handler = setTimeout(() => {

      setDebouncedValue(value)

    }, delay)

    return () => clearTimeout(handler)

  }, [value, delay])

  return debouncedValue

}

// Usage

const debouncedQuery = useDebounce(searchQuery, 500)

State Management

// ✅ GOOD: Proper state updates

const [count, setCount] = useState(0)

// Functional update for state based on previous state

setCount(prev => prev + 1)

// ❌ BAD: Direct state reference

setCount(count + 1)  // Can be stale in async scenarios

Conditional Rendering

// ✅ GOOD: Clear conditional rendering

{isLoading &#x26;&#x26; <Spinner />}

{error &#x26;&#x26; <ErrorMessage error={error} />}

{data &#x26;&#x26; <DataDisplay data={data} />}

// ❌ BAD: Ternary hell

{isLoading ? <Spinner /> : error ? <ErrorMessage error={error} /> : data ? <DataDisplay data={data} /> : null}

API Design Standards

REST API Conventions

GET    /api/markets              # List all markets

GET    /api/markets/:id          # Get specific market

POST   /api/markets              # Create new market

PUT    /api/markets/:id          # Update market (full)

PATCH  /api/markets/:id          # Update market (partial)

DELETE /api/markets/:id          # Delete market

# Query parameters for filtering

GET /api/markets?status=active&#x26;limit=10&#x26;offset=0

Response Format

// ✅ GOOD: Consistent response structure

interface ApiResponse<T> {

  success: boolean

  data?: T

  error?: string

  meta?: {

    total: number

    page: number

    limit: number

  }

}

// Success response

return NextResponse.json({

  success: true,

  data: markets,

  meta: { total: 100, page: 1, limit: 10 }

})

// Error response

return NextResponse.json({

  success: false,

  error: 'Invalid request'

}, { status: 400 })

Input Validation

import { z } from 'zod'

// ✅ GOOD: Schema validation

const CreateMarketSchema = z.object({

  name: z.string().min(1).max(200),

  description: z.string().min(1).max(2000),

  endDate: z.string().datetime(),

  categories: z.array(z.string()).min(1)

})

export async function POST(request: Request) {

  const body = await request.json()

  try {

    const validated = CreateMarketSchema.parse(body)

    // Proceed with validated data

  } catch (error) {

    if (error instanceof z.ZodError) {

      return NextResponse.json({

        success: false,

        error: 'Validation failed',

        details: error.errors

      }, { status: 400 })

    }

  }

}

File Organization

Project Structure

src/

├── app/                    # Next.js App Router

│   ├── api/               # API routes

│   ├── markets/           # Market pages

│   └── (auth)/           # Auth pages (route groups)

├── components/            # React components

│   ├── ui/               # Generic UI components

│   ├── forms/            # Form components

│   └── layouts/          # Layout components

├── hooks/                # Custom React hooks

├── lib/                  # Utilities and configs

│   ├── api/             # API clients

│   ├── utils/           # Helper functions

│   └── constants/       # Constants

├── types/                # TypeScript types

└── styles/              # Global styles

File Naming

components/Button.tsx          # PascalCase for components

hooks/useAuth.ts              # camelCase with 'use' prefix

lib/formatDate.ts             # camelCase for utilities

types/market.types.ts         # camelCase with .types suffix

Comments & Documentation

When to Comment

// ✅ GOOD: Explain WHY, not WHAT

// Use exponential backoff to avoid overwhelming the API during outages

const delay = Math.min(1000 * Math.pow(2, retryCount), 30000)

// Deliberately using mutation here for performance with large arrays

items.push(newItem)

// ❌ BAD: Stating the obvious

// Increment counter by 1

count++

// Set name to user's name

name = user.name

JSDoc for Public APIs

/**

 * Searches markets using semantic similarity.

 *

 * @param query - Natural language search query

 * @param limit - Maximum number of results (default: 10)

 * @returns Array of markets sorted by similarity score

 * @throws {Error} If OpenAI API fails or Redis unavailable

 *

 * @example

 * ```typescript

 * const results = await searchMarkets('election', 5)

 * console.log(results[0].name) // "Trump vs Biden"

 * ```

 */

export async function searchMarkets(

  query: string,

  limit: number = 10

): Promise<Market[]> {

  // Implementation

}

Performance Best Practices

Memoization

import { useMemo, useCallback } from 'react'

// ✅ GOOD: Memoize expensive computations

const sortedMarkets = useMemo(() => {

  return markets.sort((a, b) => b.volume - a.volume)

}, [markets])

// ✅ GOOD: Memoize callbacks

const handleSearch = useCallback((query: string) => {

  setSearchQuery(query)

}, [])

Lazy Loading

import { lazy, Suspense } from 'react'

// ✅ GOOD: Lazy load heavy components

const HeavyChart = lazy(() => import('./HeavyChart'))

export function Dashboard() {

  return (

    <Suspense fallback={<Spinner />}>

      <HeavyChart />

    </Suspense>

  )

}

Database Queries

// ✅ GOOD: Select only needed columns

const { data } = await supabase

  .from('markets')

  .select('id, name, status')

  .limit(10)

// ❌ BAD: Select everything

const { data } = await supabase

  .from('markets')

  .select('*')

Testing Standards

Test Structure (AAA Pattern)

test('calculates similarity correctly', () => {

  // Arrange

  const vector1 = [1, 0, 0]

  const vector2 = [0, 1, 0]

  // Act

  const similarity = calculateCosineSimilarity(vector1, vector2)

  // Assert

  expect(similarity).toBe(0)

})

Test Naming

// ✅ GOOD: Descriptive test names

test('returns empty array when no markets match query', () => { })

test('throws error when OpenAI API key is missing', () => { })

test('falls back to substring search when Redis unavailable', () => { })

// ❌ BAD: Vague test names

test('works', () => { })

test('test search', () => { })

Code Smell Detection

Watch for these anti-patterns:

1. Long Functions

// ❌ BAD: Function > 50 lines

function processMarketData() {

  // 100 lines of code

}

// ✅ GOOD: Split into smaller functions

function processMarketData() {

  const validated = validateData()

  const transformed = transformData(validated)

  return saveData(transformed)

}

2. Deep Nesting

// ❌ BAD: 5+ levels of nesting

if (user) {

  if (user.isAdmin) {

    if (market) {

      if (market.isActive) {

        if (hasPermission) {

          // Do something

        }

      }

    }

  }

}

// ✅ GOOD: Early returns

if (!user) return

if (!user.isAdmin) return

if (!market) return

if (!market.isActive) return

if (!hasPermission) return

// Do something

3. Magic Numbers

// ❌ BAD: Unexplained numbers

if (retryCount > 3) { }

setTimeout(callback, 500)

// ✅ GOOD: Named constants

const MAX_RETRIES = 3

const DEBOUNCE_DELAY_MS = 500

if (retryCount > MAX_RETRIES) { }

setTimeout(callback, DEBOUNCE_DELAY_MS)

Remember: Code quality is not negotiable. Clear, maintainable code enables rapid development and confident refactoring.

When to Use

This skill is applicable to execute the workflow or actions described in the overview.

Limitations

Use this skill only when the task clearly matches the scope described above.

Do not treat the output as a substitute for environment-specific validation, testing, or expert review.

Stop and ask for clarification if required inputs, permissions, safety boundaries, or success criteria are missing.

cc-skill-coding-standards