Claude Code Rules for Production React/TypeScript

Battle-tested engineering standards for Claude Code, extracted from production trading platforms handling real-time data, WebSocket feeds, and financial transactions.

These aren't theoretical best practices. Every rule exists because its absence caused a bug, a performance regression, or a maintenance nightmare in production.

Quick Start

Copy to your project's .claude/ directory:

# Clone the repo
git clone https://github.com/antoni0dev/claude-code-rules.git

# Copy rules to your project
cp claude-code-rules/CLAUDE.md your-project/.claude/CLAUDE.md
cp -r claude-code-rules/rules/ your-project/.claude/rules/
cp -r claude-code-rules/skills/ your-project/.claude/skills/

Or copy individual rules you care about — they're modular by design.

What's Included

CLAUDE.md — Global Standards

The root instruction file that Claude Code reads on every session. Covers core principles, TypeScript philosophy, React patterns, git conventions, and performance guidelines in one concise document.

Rules

Granular, file-type-scoped rules that activate based on what you're editing:

Rule	Scope	What It Enforces
typescript.md	*.ts, *.tsx	type over interface, zero as assertions, derived types from const arrays, satisfies, ensurePresent()
react.md	*.tsx	React Compiler (no manual memoization), component autonomy, MatchQuery pattern, hook conventions
pattern-matching.md	*.ts, *.tsx	Record lookups over switch/case, match(), discriminated unions, config arrays
functions.md	*.ts, *.tsx	Object params, attempt() over try-catch, pure mappers, naming conventions
code-quality.md	all	DRY enforcement, no magic numbers, descriptive errors, no console.log
file-structure.md	src/**	Feature-based organization, module conventions, barrel exports
performance.md	*.ts, *.tsx	State colocation, derived values over redundant state, config-driven patterns
systems-architecture.md	all	Data flows, caching strategies, real-time data, failure handling, CAP theorem
execution-strategy.md	all	Complexity gating for Claude Code — when to use subagents vs direct execution
git-identity.md	all	Multi-account GitHub identity management (template — customize with your accounts)

Skills

Reusable Claude Code slash commands:

Skill	Command	What It Does
commit	/commit	Stage, create conventional commit, optionally push
create-pr	/create-pr	Create draft PR with optional ticket linking
delegate	/delegate	Generate a step-by-step plan for a faster model to execute
resolve-pr-comments	/resolve-pr-comments	Address code review feedback critically (AI reviewers can be wrong)

Philosophy

These rules encode a specific engineering philosophy. If you agree with most of these, this repo will save you weeks of configuring Claude Code:

• Types are truth. Never add ?. or ?? on non-optional types. If a value must exist, ensurePresent() — fail fast, don't silently propagate undefined.
• Pattern matching over control flow. Record lookups, match(), and config arrays replace every switch/case and if/else chain. Code becomes data.
• React Compiler handles memoization. Never useMemo or useCallback. Write natural code. (One exception: values used as useEffect deps that trigger expensive side effects.)
• Component autonomy. Domain components access state via hooks, not props. Only truly reusable/generic components receive props.
• attempt() over try-catch. Error handling as discriminated unions ({ data: T } | { error: E }), not exception control flow.
• Feature-based file organization. No generic components/, hooks/, or utils/ folders. Code lives next to what uses it.
• Systems thinking for frontend engineers. Understand caching strategies, consistency models, and failure modes — even if you never write a backend.

Key Patterns

attempt() — Error handling without try-catch

type Result<T, E> = { data: T } | { error: E }

const result = await attempt(() => saveOrder(order))
if ('data' in result) showSuccess()
else showError(result.error.message)

Pattern matching — No switch/case, ever

// Record for value mapping
const statusToColor: Record<Status, Color> = {
  active: 'green',
  inactive: 'gray',
  error: 'red',
}

// match() for logic branching
const sound = match(animal, {
  dog: () => 'woof',
  cat: () => 'meow',
})

// MatchQuery for React Query states
<MatchQuery
  value={tokenQuery}
  pending={() => <Skeleton />}
  error={(e) => <ErrorState error={e} />}
  success={(data) => <TokenCard token={data} />}
/>

Derived types from const arrays

const sortOptions = ['trending', 'newest', 'volume'] as const
type SortOption = (typeof sortOptions)[number]
// Runtime array AND type from single source of truth

Customization

These rules are opinionated by design — that's what makes them useful. But you should adapt them:

1. Disagree with a rule? Delete the file or edit it. They're modular.
2. Different stack? Remove react.md if you use Vue/Svelte. The TypeScript, functions, and systems architecture rules are framework-agnostic.
3. Different git workflow? Edit git-identity.md with your own account mappings.
4. Want to add rules? Follow the frontmatter pattern with paths: to scope when rules activate.

Stack Context

These rules were developed while building:

• Production trading terminals with real-time WebSocket data
• React 19 + TypeScript 5.9 + TanStack Query
• React Compiler enabled
• Supabase + Stripe integrations
• Claude Code as the primary development tool

License

MIT — use however you want.