ITADN

Reduce CLAUDE.md to durable guidance and add a tool-neutral AGENTS.md

#856Openrealmarcin 创建于 9 天前
documentation
R
realmarcincommented
**Priority: P2 — do after CLI/workflow behavior is settled so documentation records stable contracts.** ## Problem `CLAUDE.md` is 457 lines and mixes durable agent rules with volatile measurements, historical debugging notes, and duplicated environment configuration. Several statements are stale or unverifiable: - `kg holdouts` is documented although it is currently a no-op. - The SPARQL example points to missing `queries/sparql/example_query.yaml`. - The test inventory names files that no longer exist. - The standard edge schema omits `knowledge_level` and `agent_type`. - Formatting guidance says Black although the repository uses Ruff formatting. - Type hints are described as required but CI does not enforce that rule. - `make run-summary` expects loose TSVs while the default merge produces an archive and removes extracted files. ## Proposed change - Reduce `CLAUDE.md` to roughly 100–150 lines of commands, invariants, safety rules, and links. - Add a concise, tool-neutral `AGENTS.md` containing critical repository conventions. - Move PREGO measurements and ontology failure history into versioned ADR/runbook documents. - Put supported environment variables, defaults, and warnings in `.env.example`; link to it instead of duplicating the list. - Validate every referenced command, path, test file, and schema field. ## Acceptance criteria - [ ] `CLAUDE.md` contains only durable operational guidance and is approximately 100–150 lines. - [ ] `AGENTS.md` exposes the critical conventions without Claude-specific assumptions. - [ ] Detailed historical/measurement material remains available in linked ADRs or runbooks. - [ ] `.env.example` is the canonical inventory of supported environment variables and contains no secrets. - [ ] Holdout, SPARQL, test inventory, edge schema, formatter, typing, and run-summary statements match repository behavior. - [ ] Documentation link/path checks cover the files referenced by agent guidance. ## Related issues - #523 — remove obsolete Black configuration - #553 — release artifacts and download documentation
0 条评论