Skip to content

ai

Code and docs written with AI agents: agent files, terse output, AI-isms, stop-gap smells, agent-config hygiene.

Use it with extends = "ai" in spirit_level.toml.

Lints enabled (with what it extends)

Code Lint Level Reason Set in
A0001 agent-config-permissions deny committed settings apply to every agent; a blanket grant lets any of them run anything ai
A0002 agent-config-secrets deny a committed key is public to every reader and stays in history ai
A0003 agent-session-files deny transcripts and per-person agent files hold private context and secrets ai
A0004 leftover-files deny merge, editor and scratch leftovers and session notes do not belong in history ai
A0005 commented-out-code deny git keeps the old code; commented-out code is a decision not taken ai
A0006 dead-features warn a feature that enables nothing and gates nothing is left over ai
A0007 lint-table-allow-reason deny a lint allowed for a whole crate in Cargo.toml says why ai
A0008 near-duplicate-fns warn a rewrite that keeps the old function leaves two copies to fix ai
A0009 near-duplicate-modules deny a rewrite that keeps the old module is not finished ai
A0010 stop-gap-comments deny a TODO or a 'for now' marks a path the final design throws away; tracked work names its id ai
A0011 fixme-before-land deny an agent may leave itself a FIXME on its branch; the landing refuses it ai
A0012 large-blobs warn a large tracked file stays in every clone forever; agents commit dumps and binaries with git add -A ai
C0002 allow-without-reason deny an allowed lint says why, so it can be turned back on ai
C0008 todo-macros deny todo!() and unimplemented!() are stop-gaps that compile ai
C0018 unit-suffix warn agents write units last in names from the start; a warning, since it reads names only and fires widely in older code ai
C0019 unbounded-read warn input from outside sets the memory a read to the end takes; candidates only, a place to look ai
M0018 repo-files deny AGENTS.md holds the rules every agent reads; CLAUDE.md points to it ai
P0001 agent-file-lines deny agents read the file whole every session; a long one is skimmed, not followed ai
P0002 agent-file-links deny an agent that follows a dead link guesses or stops ai
P0003 agent-rules-match-lints deny a stated limit the lints check differently teaches agents a rule the repo does not hold ai
P0004 claude-md-duplicate deny two copies of the rules drift apart ai
P0005 commit-body-lines warn a body holds why, not a retelling of the diff ai
P0006 commit-prose warn commit messages follow the prose rules of the docs ai
P0007 commit-subject-length deny the subject is what one-line logs and reviews show ai
P0008 changelog-describes-diff warn an entry says what changed for the user; the diff already shows the files ai
P0009 changelog-entry-length deny a CHANGELOG is a list: one line per change ai
P0010 emoji warn emoji do not grep, diff or render the same everywhere ai
P0011 filler-phrases deny filler adds words and no meaning ai
P0012 narration deny docs and comments state facts, not the conversation that produced them ai
P0013 paragraph-sentences warn result first, then what the reader must do; more facts are a list ai
P0014 restating-comments warn a comment says what the code cannot ai
P0015 sentence-words warn short sentences are read once and understood ai
P0016 thinking-comments deny a comment holds the conclusion, not the reasoning that led to it ai
P0017 fixes-tag deny an agent copies the culprit's hash and subject from git; a wrong one sends the next reader astray ai
P0018 fix-without-test warn an agent writes the failing test first; a warning, since a fix is judged from its subject ai
P0019 commit-tested-line warn an agent says how it tested, or that it did not; a warning while branches begun before the rule land ai
P0020 commit-mixed-move warn a move edited in the same commit cuts every line's history; a warning, since it judges lines by their start ai
P0021 url-tracking-params warn a link pasted from a browser or a chat app carries an id that tells the reader nothing and goes stale ai

Clippy set (with what it extends)

The project turns these on in its own [workspace.lints.clippy] (allow rows are accepted opt-outs, pasted with their reason); tier-clippy-set checks it.

Clippy lint Level Reason Set in
allow_attributes warn #[expect] fails once the lint stops firing, so an exception cannot outlive its cause ai
cognitive_complexity warn agents grow functions branch by branch; a tangled one is split ai
print_stderr warn agents leave debugging prints behind ai
print_stdout warn agents leave debugging prints behind ai
self_named_module_files warn one module layout, mod.rs, across the workspace ai
str_to_string warn to_owned says what happens: a copy of a borrowed str ai
too_long_first_doc_paragraph warn agents write long doc summaries; the first paragraph is one short sentence ai
use_self warn Self follows a rename ai

clippy.toml (an integer is a limit the project may lower):

Setting Value Reason Set in
cognitive-complexity-threshold 20 set on samples: 17 read fine, 21 and 25 were too long; spl's function-complexity (cyclomatic, 15) counts paths ai

The file

# Beside the size tiers: code and docs written with AI agents. Combine it with one: extends = ["medium", "ai"].
[tier]
description = "Code and docs written with AI agents: agent files, terse output, AI-isms, stop-gap smells, agent-config hygiene"

# Agent files

[lints.repo-files]
level = "deny"
reason = "AGENTS.md holds the rules every agent reads; CLAUDE.md points to it"

[lints.agent-file-lines]
level = "deny"
reason = "agents read the file whole every session; a long one is skimmed, not followed"

[lints.claude-md-duplicate]
level = "deny"
reason = "two copies of the rules drift apart"

[lints.agent-file-links]
level = "deny"
reason = "an agent that follows a dead link guesses or stops"

[lints.agent-rules-match-lints]
level = "deny"
reason = "a stated limit the lints check differently teaches agents a rule the repo does not hold"

# Terse output

[lints.changelog-entry-length]
level = "deny"
reason = "a CHANGELOG is a list: one line per change"

[lints.changelog-describes-diff]
level = "warn"
reason = "an entry says what changed for the user; the diff already shows the files"

[lints.commit-subject-length]
level = "deny"
reason = "the subject is what one-line logs and reviews show"

[lints.commit-body-lines]
level = "warn"
reason = "a body holds why, not a retelling of the diff"

[lints.commit-prose]
level = "warn"
reason = "commit messages follow the prose rules of the docs"

[lints.fixes-tag]
level = "deny"
reason = "an agent copies the culprit's hash and subject from git; a wrong one sends the next reader astray"

[lints.fix-without-test]
level = "warn"
reason = "an agent writes the failing test first; a warning, since a fix is judged from its subject"

[lints.commit-tested-line]
level = "warn"
reason = "an agent says how it tested, or that it did not; a warning while branches begun before the rule land"

[lints.commit-mixed-move]
level = "warn"
reason = "a move edited in the same commit cuts every line's history; a warning, since it judges lines by their start"

[lints.sentence-words]
level = "warn"
reason = "short sentences are read once and understood"

[lints.paragraph-sentences]
level = "warn"
reason = "result first, then what the reader must do; more facts are a list"

# AI-isms

[lints.filler-phrases]
level = "deny"
reason = "filler adds words and no meaning"

[lints.narration]
level = "deny"
reason = "docs and comments state facts, not the conversation that produced them"

[lints.thinking-comments]
level = "deny"
reason = "a comment holds the conclusion, not the reasoning that led to it"

[lints.emoji]
level = "warn"
reason = "emoji do not grep, diff or render the same everywhere"

[lints.restating-comments]
level = "warn"
reason = "a comment says what the code cannot"

[lints.url-tracking-params]
level = "warn"
reason = "a link pasted from a browser or a chat app carries an id that tells the reader nothing and goes stale"

# Stop-gap smells (the top rule)

[lints.stop-gap-comments]
level = "deny"
reason = "a TODO or a 'for now' marks a path the final design throws away; tracked work names its id"

[lints.fixme-before-land]
level = "deny"
reason = "an agent may leave itself a FIXME on its branch; the landing refuses it"

[lints.unit-suffix]
level = "warn"
reason = "agents write units last in names from the start; a warning, since it reads names only and fires widely in older code"

[lints.unbounded-read]
level = "warn"
reason = "input from outside sets the memory a read to the end takes; candidates only, a place to look"

[lints.todo-macros]
level = "deny"
reason = "todo!() and unimplemented!() are stop-gaps that compile"

[lints.commented-out-code]
level = "deny"
reason = "git keeps the old code; commented-out code is a decision not taken"

[lints.allow-without-reason]
level = "deny"
reason = "an allowed lint says why, so it can be turned back on"

[lints.lint-table-allow-reason]
level = "deny"
reason = "a lint allowed for a whole crate in Cargo.toml says why"

[lints.near-duplicate-fns]
level = "warn"
reason = "a rewrite that keeps the old function leaves two copies to fix"

[lints.near-duplicate-modules]
level = "deny"
reason = "a rewrite that keeps the old module is not finished"

[lints.dead-features]
level = "warn"
reason = "a feature that enables nothing and gates nothing is left over"

# Agent-config hygiene

[lints.leftover-files]
level = "deny"
reason = "merge, editor and scratch leftovers and session notes do not belong in history"

[lints.large-blobs]
level = "warn"
reason = "a large tracked file stays in every clone forever; agents commit dumps and binaries with git add -A"

[lints.agent-config-secrets]
level = "deny"
reason = "a committed key is public to every reader and stays in history"

[lints.agent-config-permissions]
level = "deny"
reason = "committed settings apply to every agent; a blanket grant lets any of them run anything"

[lints.agent-session-files]
level = "deny"
reason = "transcripts and per-person agent files hold private context and secrets"

# The Clippy lints that catch what agents write: allow without expect, stray prints, verbose conversions,
# repeated type names, long doc summaries, tangled functions.

[clippy.lints]
allow_attributes = { level = "warn", reason = "#[expect] fails once the lint stops firing, so an exception cannot outlive its cause" }
print_stdout = { level = "warn", reason = "agents leave debugging prints behind" }
print_stderr = { level = "warn", reason = "agents leave debugging prints behind" }
str_to_string = { level = "warn", reason = "to_owned says what happens: a copy of a borrowed str" }
use_self = { level = "warn", reason = "Self follows a rename" }
self_named_module_files = { level = "warn", reason = "one module layout, mod.rs, across the workspace" }
too_long_first_doc_paragraph = { level = "warn", reason = "agents write long doc summaries; the first paragraph is one short sentence" }
cognitive_complexity = { level = "warn", reason = "agents grow functions branch by branch; a tangled one is split" }

[clippy.config]
cognitive-complexity-threshold = { value = 20, reason = "set on samples: 17 read fine, 21 and 25 were too long; spl's function-complexity (cyclomatic, 15) counts paths" }