Reduce CLAUDE.md to durable guidance and add a tool-neutral AGENTS.md
documentation
**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 条评论