diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..a29f1e0
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,68 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Development Commands
+
+This is a client-side JavaScript application that runs directly in the browser:
+
+- **Run the application**: Open `index.html` in a web browser
+- **No build process**: The application uses vanilla JavaScript with no build tools
+- **No package manager**: No npm/yarn dependencies, all code is self-contained
+
+## Project Architecture
+
+### Core Architecture Pattern
+The project uses an **Entity-Component-System (ECS)** pattern with event-driven communication:
+
+- **Entities**: `Player` and `Puck` classes represent game objects
+- **Systems**: Modular systems handle specific concerns (rendering, physics, AI, rules, audio)
+- **Game Engine**: Central orchestrator that manages all systems and entities
+- **Game State**: Centralized state management for scores, time, penalties, etc.
+
+### System Dependencies
+The application loads scripts in a specific order due to class dependencies:
+
+1. **Utilities**: `vector.js`, `physics.js` (foundational math/physics)
+2. **Entities**: `player.js`, `puck.js` (game objects)
+3. **Systems**: `renderer.js`, `physics-system.js`, `ai-system.js`, `rules-system.js`, `audio-system.js`
+4. **Engine**: `game-state.js`, `game-engine.js`, `main.js` (orchestration)
+
+### Key Classes and Responsibilities
+
+- **HockeyManager** (`main.js`): Application lifecycle, canvas setup, global events
+- **GameEngine** (`game-engine.js`): 60 FPS game loop, system coordination, player/puck management
+- **GameState** (`game-state.js`): Score tracking, time management, penalty system
+- **Player** (`player.js`): Hockey player with AI, physics, and role-based behavior
+- **Puck** (`puck.js`): Physics-based puck with collision detection
+- **Renderer** (`renderer.js`): 2D canvas rendering with camera system
+- **AISystem** (`ai-system.js`): Team formations and strategic AI behaviors
+- **RulesSystem** (`rules-system.js`): Hockey rule enforcement (offside, icing, penalties)
+
+### Game Loop Architecture
+The engine runs at 60 FPS using `requestAnimationFrame` with these phases:
+1. Input processing
+2. Physics simulation
+3. AI decision making
+4. Rules enforcement
+5. Rendering
+6. Audio updates
+
+### Hockey-Specific Features
+- **12 players** (6 per team) with distinct roles: Center (C), Left/Right Wing (LW/RW), Left/Right Defense (LD/RD), Goalie (G)
+- **Formation system** with offensive/defensive positioning
+- **Rule enforcement**: Offside detection, icing calls, penalty system
+- **Realistic physics**: Collision detection, momentum conservation, board bouncing
+
+## Controls Reference
+- `SPACE` - Pause/Resume game
+- `D` - Toggle debug information
+- `R` - Reset game
+- `F11` - Toggle fullscreen
+- `Mouse Wheel` - Camera zoom
+
+## File Structure Notes
+- All code is vanilla JavaScript (ES6 classes)
+- No modules or imports - everything is global
+- Canvas-based 2D rendering
+- Self-contained with no external dependencies
\ No newline at end of file