docs: root CLAUDE.md + benchmark guide overhaul + code-health report - #37
Open
duanyiqun wants to merge 1 commit into
Open
docs: root CLAUDE.md + benchmark guide overhaul + code-health report#37duanyiqun wants to merge 1 commit into
duanyiqun wants to merge 1 commit into
Conversation
- CLAUDE.md (new): commands, architecture map + layering rules, conventions, testing reality, benchmark quick-ref, branch/PR rules, gotchas. Two docs already declared themselves "extensions of CLAUDE.md" — it now exists. - docs/BENCHMARK.md: remove 5 dead links to nonexistent docs/benchmark/, align File Map/status tables with the 9 real benchmark dirs (7 retired ones removed), fix the --event-stream guidance (flag exists only in locomo; other runners consolidate unconditionally in base_runner), document longmemeval entry points, correct the auto-download claim, add an environment-variable table and a "Contributing a new benchmark" guide. - docs/CODE_HEALTH.md (new): evidence-based structural findings (file:line) in three tiers with fix directions and sequencing. - .env.example: document benchmark env vars; fix duplicate COGNIFOLD_SESSION_BACKEND definition. Docs-only change; no src/ code touched. Co-Authored-By: Claude <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01VnAaidzJkganncouErUp3m
This was referenced Aug 25, 2026
Open
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.
Summary
Docs-only change establishing the repo's development guide and cleaning up benchmark documentation. No
src/code touched.CLAUDE.md(new) — the root development guide thatdocs/BENCHMARK.mdanddocs/PHILOSOPHY.mdalready declared themselves extensions of (it never existed until now). Covers: commands (with the pinned ruff/pyright versions and lint scope), architecture map + dependency-layering rules, code conventions (typing, logging, Pydantic-vs-dataclass split, node ID prefixes), testing reality (pytest is smoke-only; what real verification looks like), benchmark quick-reference with the judge/branch locks, branch & deployment model, and gotchas.docs/BENCHMARK.md(overhauled) —--event-streamguidance: the flag exists only in the locomo runner (README's description was correct; the old "ALWAYS pass it to every benchmark" instruction was an argparse error on 8 of 9 runners)docs/benchmark/directoryMODELdefault vs paper-stack mismatchdocs/CODE_HEALTH.md(new) — evidence-based structural findings withfile:linecitations, three tiers, fix directions, and a suggested sequencing. Tier-1 items are also filed as issues..env.example— documented the benchmark env vars (previously undocumented) and fixed the duplicateCOGNIFOLD_SESSION_BACKENDdefinition.Verification
CLAUDE.mdchecked againstMakefile/scripts/(all exist)grepfor the removed dead links returns zero matchesCODE_HEALTH.mdline references spot-checked against source (dispatch dictquery/agent.py:789-808,config.py:161service import,session.py:346/365key persistence,serve.pyuvicorn workers,register_domain:1494, deprecated embeddings call sites inexecutor/runner.py).env.examplecomments — outside theruff/pyright/CI lint scope🤖 Generated with Claude Code
https://claude.ai/code/session_01VnAaidzJkganncouErUp3m
Generated by Claude Code