diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..9893c3d
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,20 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Build/Test Commands
+- Setup: `mix setup`, `mix deps.get`, `mix ecto.setup`
+- Run server: `mix phx.server`
+- Tests: `mix test`, `mix test path/to/test_file.exs`, `mix test path/to/test_file.exs:line_number`
+- Format/Lint: `mix format`, `mix credo`
+- Assets: `mix assets.setup`, `mix assets.build`, `mix assets.deploy`
+
+## Code Style Guidelines
+- Formatting: Max line length 120, use `mix format`
+- Naming: snake_case for variables/functions, descriptive module namespacing (Core.Accounts.User)
+- Organization: Boundary-driven modules (core/, schema/, web/)
+- Error handling: Return {:ok, result} or {:error, changeset} tuples, pattern matching
+- Testing: Descriptive test names, fixtures, shared setup, tagged tests
+- Imports: Organize at top, import frequently used functions, follow boundary pattern
+- Documentation: `@doc` for public functions, `@moduledoc false` for internal modules
+- Use `@impl` for callback implementations
\ No newline at end of file