diff --git a/AGENTS.md b/AGENTS.md
index 409016367..11ddac8bd 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -163,6 +163,15 @@ Built on `mongo-migrate-ts`. Migrations are TypeScript files with `up()` and `do
 - Run: `pnpm migrate:up`, `pnpm migrate:down`, `pnpm migrate:status`
 - Framework docs: [docs/architecture/db-migrations.md](docs/architecture/db-migrations.md)
 
+## Code Readability
+
+- Write for humans: descriptive names, small focused functions, simple control flow, minimal abstraction.
+- Separate logical steps with blank lines; avoid dense one-liners and unrelated statements packed together.
+- Give every non-trivial function and logical code block a short comment explaining what it does; add intent, assumptions, invariants, or surprising reasons where useful.
+- Document function parameters, types, and their fields/properties with concise JSDoc/TSDoc explaining meaning, constraints, units, optionality, and defaults where relevant.
+- Do not narrate trivial or self-evident code. Document public contracts and failure behavior when names and types are insufficient.
+- Follow local conventions and formatters; review readability as well as correctness.
+
 ## Development
 
 ```bash
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 000000000..58dbb4b3c
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,3 @@
+@AGENTS.md
+
+Keep this file as a loader only. Never add instructions here; put them in AGENTS.md.