diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
new file mode 100644
index 0000000..7fafe25
--- /dev/null
+++ b/.github/copilot-instructions.md
@@ -0,0 +1,12 @@
+# Copilot Instructions
+
+This project's authoritative agent instructions live in `CLAUDE.md` at the
+repository root, with supplementary rules under `.claude/rules/`.
+
+At the start of every session, before doing any other work, read:
+
+- `CLAUDE.md`
+- All files under `.claude/rules/`
+
+Treat their contents as binding project instructions for the remainder of the
+session, equivalent to instructions in this file.
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..5b4f381
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,36 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Before opening a PR or pushing a branch
+
+Run a self-check on the diff before creating a PR or pushing:
+1. Compute effective LoC — exclude lockfiles, generated files, snapshots, and vendor code.
+2. Count effective touched files — exclude the above plus one-to-one test pairs.
+3. If effective LoC > 400 or effective files > 10, stop and propose a split before proceeding.
+4. Report the result inline before continuing.
+
+## Key Principles
+
+- Search the codebase before assuming something isn't implemented
+- Write comprehensive tests with clear documentation
+- Follow Test-Driven Development when refactoring or modifying existing functionality
+- Always write tests for new functionality you implement
+- Keep changes focused and minimal
+- Follow existing code patterns
+- Prefer the `ddt` package for parameterized tests to reduce code duplication
+
+## Documentation & Institutional Memory
+
+- Document new functionality in `docs/references/`
+- When you learn something important about how this codebase works (gotchas, non-obvious
+  patterns, integration quirks), capture it in the relevant `docs/references/` file or
+  in `docs/architecture-patterns.md`
+- These docs are institutional memory - future sessions (yours or others) will benefit
+  from what you record here
+
+## Testing Notes
+
+- Uses pytest with Django integration
+- Coverage reporting enabled by default
+- PII annotation checks required for Django models