Skip to content

docs(claude-md): fix 8 code-drift findings in the agent authority file

Jérôme Revillard requested to merge docs/claude-md-drift-audit into main

CLAUDE.md is the AI-agent authority file — drift here actively misleads agents. A focused read-only auditor verified every concrete claim against the codebase; this MR fixes the 8 valid findings (2 CRITICAL, 6 MAJOR).

CRITICAL (would break agent actions)

  • config/appConfig.js does not exist → the backend config is config.js at the backend root. An agent told to "edit the centralized config" would chase a nonexistent path.
  • /api/files/* is not a backend route → document upload/management lives in the separate document-repository service. An agent looking for file routes in the BFF would find nothing.

MAJOR (stale / misleading)

  • /api/categories/* → real routes /api/services/* + /api/service-categories/*.
  • CI "4 stages (lint/test/config/e2e)" → the actual multi-stage pipeline (lint/test/build/scan/config/e2e/promote + scheduled/manual/deploy).
  • "10 pre-built Grafana dashboards" → 9 (the real count).
  • env.t4/env.rtx6000 description overstated (claimed "TEI image versions" + "batch configs") → accurate: GPU utilization, model-length limits, sequence limits only.
  • Documentation-structure section list (7 sections) → the actual 11 (added knowledge-base, observability, operations, rag — the sections created in !219 (merged)).
  • Key Directories table: added mobile/, deploy/ansible, tests/rag-benchmarks, tests/config-validator, site/, and the embedding//textgen/ overlays.

Invalid findings (rejected)

Two audit findings ("phantom test:contract/test:coverage scripts") were invalid — those commands are not in CLAUDE.md (they live in .claude/rules/TESTING.md). Verified by grep before skipping.

Merge request reports

Loading