diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..56735b4
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,30 @@
+# Paper Dynasty Discord Bot
+
+Baseball card game Discord bot. discord.py with cog-based commands, SQLModel for database ops.
+
+## Commands
+
+```bash
+python -m pytest                    # Run tests
+python paperdynasty.py              # Start bot
+pip install -r requirements.txt     # Install dependencies
+```
+
+## Architecture
+
+- **Cogs** (`cogs/`): Command modules — gameplay, economy, players, admins
+- **Game engine** (`in_game/`): Turn-based simulation, AI manager, dice mechanics, WPA calculations
+- **UI** (`utilities/`): Buttons, dropdowns, embeds
+- **Database**: Production uses FastAPI database directly; dev may use separate PostgreSQL via SQLModel
+
+## Key Patterns
+
+- Cards generated from MLB statistics with complex rating calculations
+- Card ratings split by handedness (`vs_hand: 'R'` or `'L'`)
+- Multiple cardsets (seasons) with different priorities for gameplay
+- Use factory data in testing as often as possible
+
+## Development Notes
+
+- Connect to proper docker socket when running tests
+- Plans go in `./.claude/plans/` with descriptive filenames