Skip to content

P1.LOC.001 — Root of the repository has agent-facing documentation

Field Value
Principle P1 (Locality)
Severity warn
Evidence strong
Stability experimental

What it checks

The resolver asks a single, deterministic question: is there a file named CLAUDE.md or AGENTS.md at the repository root?

Case-insensitive matching is applied at the root level so Claude.md, agents.md, etc. are recognized. Subdirectory copies do not count — the rule is specifically about the top-level entry point.

Why it matters

A coding agent landing in an unfamiliar repository has no cheap way to know what conventions, constraints, or review gates apply. A single, discoverable document at the root is the smallest reliable signal. Without it, agents reason from filenames and file contents alone — locally plausible but repo-incoherent changes are the common failure mode.

When to care

  • Always care when starting a new project; the cost is minutes and pays off forever.
  • Care less when the repository is a single-file snippet, a disposable experiment, or an import-only module — suppress via .archfit.yaml with a written rationale and expiry.

How to fix

  1. Create CLAUDE.md (preferred for repos where Claude Code is the primary agent) or AGENTS.md (preferred for a vendor-neutral signal) at the root.
  2. Cover at minimum: what this repo is, the top-level layout, the rules that apply to changes, and the fast verification loop.
  3. Keep it short. CLAUDE.md itself says "when in doubt, link out rather than inline."

Suppressing this rule

.archfit.yaml:

ignore:
  - rule: P1.LOC.001
    reason: "Single-file snippet — an AGENTS.md would be larger than the snippet"
    expires: 2027-01-01

History

  • 0.1.0 — introduced at stability: experimental.