From 2afb5cfa7308f9fa1ba64ac88ab983d6b25e75a1 Mon Sep 17 00:00:00 2001 From: Cedric Vidal Date: Wed, 21 Oct 2026 11:27:49 -0700 Subject: [PATCH] docs: share agent code readability instructions Extract the shared Code Readability guidance and Claude loader from the Taxonome spike without its runtime or spike-specific documentation. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> Copilot-Session: 8e14ffb2-96ba-4f69-bea8-cc32d70cf748 --- AGENTS.md | 9 +++++++++ CLAUDE.md | 3 +++ 2 files changed, 12 insertions(+) create mode 100644 CLAUDE.md 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.