docs(claude-md): trim root, move eval suite to evals/AGENTS.md#3288
Merged
Conversation
tupizz
approved these changes
May 14, 2026
Root CLAUDE.md goes from 316 to 85 lines. Net -264 / +33. Keeps the load-bearing parts: Architecture: Rendering with the placement table compressed to 7 rows, direction-aware mirroring rule, one boundary-check rg command, Style Resolution Boundary with the 'why', Document API Contract, Commands, Testing matrix. Cuts content that's either derivable, redundant with the placement table, or has a nested home: Project Structure tree (ls works), the old 'Where to Look' table (subsumed), 'When to Modify Which System' (subsumed), per-test-suite detail (already in tests/ behavior/AGENTS.md and tests/visual/AGENTS.md). Eval suite (~60 lines) moves intact to a new evals/AGENTS.md so the documentation isn't dropped; evals/CLAUDE.md symlinks to it for cross-agent compatibility. Brand, comments, JSDoc types, and generated-artifact tables are move candidates for follow-up PRs (path-scoped rules under .claude/rules/ or per-package AGENTS.md). Not in this PR to keep it small. Background: based on an N=3 exploratory benchmark + static audit comparing variants of the root CLAUDE.md (baseline / lean / lean+scoped-rules / organic bloat) against two SuperDoc tasks (add doc-api operation, refactor RTL paragraph feature module). Lean root matched baseline correctness in the final scored sample at ~17% lower cost on the complex doc-api task; architecture- violation rate was 0% in the final scored sample. C-lean-rules had one incomplete-implementation run that flagged a real failure mode (operation not wired into public API). N=3 per cell, Claude Sonnet only, grep-based correctness. Directional only.
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 5fb0d3523e
ℹ️ About Codex in GitHub
Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".
caio-pizzol
force-pushed
the
caio/agent-docs-b-prime-trim
branch
from
5fb0d35 to
d11b227
Compare
… any cwd Per PR review: eval scripts live in evals/package.json, not the root, so bare 'pnpm run eval'/'eval:e2e'/'view' fail with ERR_PNPM_NO_SCRIPT from the repo root. Switched all references to 'pnpm --filter @superdoc-testing/evals run ...' form. Bare-form usage from inside evals/ called out separately for operators already cd'd in.
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
2 participants
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.
The root CLAUDE.md had grown to 316 lines. An exploratory benchmark plus a static audit pointed at a smaller load-bearing core, so this PR trims it to 85 lines and moves the eval-suite content to evals/AGENTS.md.
ls), old "Where to Look" and "When to Modify" sections (subsumed by the placement table), per-test-suite detail (already intests/behavior/AGENTS.mdandtests/visual/AGENTS.md), and AI Eval Suite detail (nowevals/AGENTS.md, withCLAUDE.mdsymlinked for Claude compatibility)..claude/rules/with path scoping, and a recurring audit workflow.