docs: add CLAUDE.md pointer, tighten AGENTS.md, add coding conventions#596
Merged
Conversation
Add a CLAUDE.md that Claude Code auto-loads every session and points to AGENTS.md as the required-first read (AGENTS.md was not being auto-loaded). Compress AGENTS.md (~182 → ~150 lines) by trimming redundant prose while keeping the architecture map, directory map, build loop, and per-module pointers. Add three conventions: - always prefer fixed-width integer types (std::int32_t over int) - prefer std::ranges algorithms / range overloads over iterator pairs - bind free-function definitions to their namespace (qualified out-of-line definition) so signature drift fails at compile time, not link time; keep TU-local helpers in an anonymous namespace Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01PvSNQg6fxTXkmLj3g3RrY2
The per-module AGENTS.md files enter context whenever an agent works in that module (the PDF one alone was ~14K tokens). They had grown to narrate feature-by-feature what the code already says, plus per-test prose and duplicated pipeline walkthroughs. Cut the code-derivable narration; keep the parts the code can't tell you: design rationale, non-obvious invariants, spec-record maps / ASCII structure diagrams, module-layout tables, and open-work/roadmap design plans. Net ~1875 -> ~1094 lines (119.6KB -> 63.9KB). Largest cut is pdf/AGENTS.md (731 -> 312). All cross-links verified. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01NMkMNjHrXJszdWuYAbZnHu
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
🤖 Generated with Claude Code
Why
AGENTS.mdwas effectively ignored by Claude Code because the harnessauto-loads
CLAUDE.md, notAGENTS.md— so agents started every sessionblind to the repo's conventions.
What
CLAUDE.md— auto-loaded each session; insistsAGENTS.mdis readfirst and points at the per-module
AGENTS.mdfiles.AGENTS.md(~182 → ~150 lines): trimmed redundant prose,kept the architecture/directory maps, build loop, and pointers.
AGENTS.md:std::int32_toverint)std::rangesalgorithms / range overloads over iterator pairsout-of-line form, so a signature drifting from the header fails at
compile time rather than as an obscure linker error; keep TU-local
helpers in an anonymous namespace
Docs only — no code or build changes.