Skip to content

CLAUDE.md - Development Guidelines

📘 Core development standards and autonomous working principles for this monorepo

🎯 Autonomous Working Principles

Work boldly and confidently without hesitation. Institute best practices immediately. Act decisively on:

  • Refactoring: Convert to async/await, eliminate dead code, modernize patterns
  • Architecture: Apply clean architecture, DDD, and dependency injection
  • Security: Strengthen validation, enforce strict TypeScript, implement safeguards
  • Testing: Add/refactor tests with modern frameworks (Vitest/Jest)
  • Quality: Auto-fix linting, use modern abstractions, prefer clear code over TODOs

✅ Finishing Rules

  • No TODOs: Resolve or remove them entirely
  • Pass all checks: Ensure linting, type-checking, and tests pass
  • Self-documenting code: Prioritize clarity over verbose documentation

🏗️ Repository Structure

NX Monorepo with two main directories:

  • apps/ - Backend services (datastream, orderbook, relayer, sequencer, etc.)
  • libs/ - Shared libraries (commons-ts, connections-ts, tools, risk, etc.)

🔧 Core Tools & Standards

Package Manager

Yarn ≥4.0.0 (never npm/pnpm)

yarn install
yarn add <package>
yarn add -D <dev-package>

Code Style

  • TypeScript with ESM modules ("type": "module")
  • 2 spaces, 120 char width, double quotes
  • Biome + Prettier for formatting
  • Zod schemas for validation
  • Service architecture with dependency injection

Key Principles

  • Early returns over nested conditions
  • Descriptive names (prefix handlers with "handle")
  • Functional/immutable style when possible
  • Minimal changes - only modify what's needed

🛠️ Essential Commands

NX Workspace

nx show projects                    # List all projects
nx build <project>                  # Build specific project
nx test <project>                   # Test specific project
nx affected -t build               # Build affected projects

Common Operations

yarn nx:build                      # Build all
yarn nx:lint                       # Lint all
yarn nx:test                       # Test all
yarn validate                      # Full validation

Docker Testing

./scripts/docker-test-build.sh     # Test builds
./scripts/docker-cleanup.sh        # Clean up space issues

📝 Naming Conventions

  • PascalCase: Interfaces (IService), Types (UserType)
  • camelCase: Variables, functions, methods
  • kebab-case: Files (base.service.ts)
  • Tests: .spec.ts (unit), .test.ts (integration)

🔒 Security Standards

  • Never commit secrets - use environment variables
  • Validate all inputs with proper type checking
  • Follow least privilege for service accounts
  • Use encrypted storage for sensitive state

🧪 Testing Approach

  • Vitest for modern testing
  • Tenderly for blockchain testing (not Anvil)
  • Mock services using vi.fn() patterns
  • Comprehensive coverage for new/modified code

📦 Publishing (GitHub Packages)

yarn publish:commons               # Patch version
yarn publish:commons:minor         # Minor version
yarn publish:commons:major         # Major version

🚀 Development Workflow

  1. Understand the architecture before making changes
  2. Follow conventions from existing codebase
  3. Use available libraries - don't reinvent
  4. Test thoroughly with proper mocks
  5. Validate with linting and type checking
  6. Document complex logic only when necessary

🔧 Build System

Standardized targets across all projects:

  • build: Main build target
  • typecheck: Strict type checking
  • validate: Full validation (lint + test + build)
  • build:retry: For flaky builds

For flaky builds: nx run [project]:build:retry

🎯 File Creation Policy

  • Prefer editing existing files over creating new ones
  • Never create documentation files unless explicitly requested
  • Clean up temporary files after use
  • Focus changes only on task-related sections

💡 Detailed documentation: See CLAUDE.local.md for comprehensive guides on infrastructure, troubleshooting, and advanced configurations.