P0002 agent-file-links¶
Rule: Links and @imports in agent files resolve.
| Code | P0002 (stable, never reused) |
| Id | agent-file-links |
| Category | agents |
| Source | spirit_level |
| Fix | by hand |
Level per tier¶
| Tier | Level | Reason |
|---|---|---|
| small | off | |
| small-workspace | off | |
| medium | off | |
| big | off | |
| ai | deny |
an agent that follows a dead link guesses or stops |
| embedded | off | |
| ui | off | |
| egui | off | |
| units-strict | off | |
| units-paranoid | off |
Parameters¶
| Name | Type | Default | Meaning |
|---|---|---|---|
files |
list of strings | ["AGENTS.md", "CLAUDE.md"] |
the agent files, relative to the root |
Why¶
An agent follows links in its rules. A link to a moved or deleted file sends it nowhere, and it either guesses or stops.
The rule checks Markdown links [text](path) and @path imports (an @ at a word start followed by a path with a . or /) in each file of files. Paths resolve from the file's directory; a leading / means the project root. URLs, anchors-only links and ~ paths are not checked; links inside code are ignored.
How to fix¶
Fix the path, or drop the link.
Configure¶
[lints.agent-file-links]
level = "deny"
files = ["AGENTS.md", "CLAUDE.md"]
reason = "why this project wants it at this level"
Allow one finding in the code with // spirit-level: allow(agent-file-links) <reason> (waivers); the code works there too, as in [lints.P0002].