Eight rules and a sensible stopping point

The current release contains eight active rules. Four target persistent configuration: context bloat, duplicated lint or formatting guidance, vague or unresolved references, and files that appear to have been generated once but not maintained. Four target workflow documents: missing acceptance criteria, missing verification commands, incomplete handoffs, and tasks with an overly broad file scope.

Three harder rules remain reserved: conflict detection, skill leakage, and mixed judgment and execution. The project says dependable detection would require semantic analysis. That is a sensible boundary. A deterministic program can count lines, resolve a path, and check whether a task contains an acceptance section. Word matching is not enough to decide whether two qualified instructions truly conflict.

Many agent tools package subjective judgments as authoritative scores. katalint is more useful as a set of named, inspectable findings, not a universal measure of “agent readiness.” PyPI marks the project Alpha. Its output should start a review, not settle one.

The smell catalogue has evidence behind it

The configuration rules draw from “Configuration Smells in AGENTS.md Files”. Its authors analyzed 100 popular open-source repositories containing either AGENTS.md or CLAUDE.md and proposed six smells with automated detection heuristics. In the paper's current version, lint leakage occurred in 62% of the files, context bloat in 42%, and skill leakage in 35%.

Those percentages show prevalence in one sample. They do not show that a smell caused an agent to fail, and they should not be generalized to every private codebase. The study does provide a vocabulary more useful than saying a prompt “feels messy.”

Lint leakage is the easiest example to fix. If a formatter already controls indentation, quote style, or import ordering, repeating those rules in an agent file spends context and creates another policy copy that can drift. “Run the formatter and report whether it changed files” is easier to verify than a paragraph restating the formatter.

Context bloat also has a mechanical cost. OpenAI's AGENTS.md documentation says Codex builds an instruction chain from global and project files, walking from the project root toward the working directory. Root guidance reaches every task. Package-specific detail therefore belongs closer to the package, not in a root file every session must carry.

Try it before making it a gate

katalint requires Python 3.11 or newer. Install it from PyPI or run it through uv:

pip install katalint
katalint check

# Or, with uv:
uvx katalint check

Default discovery covers the common instruction files and task or handoff paths under .agent/ and docs/agent/. Dependency and build directories are ignored. The command can produce text or JSON for CI. Baseline support records known findings so later runs can filter them:

katalint check --format json
katalint check --write-baseline katalint-baseline.json
katalint check --baseline katalint-baseline.json

The default fail_on: error policy leaves warnings visible but blocks on errors. Thresholds and severities can be changed in katalint.yml. Inline suppressions work too, but the comment must include a reason. Exceptions then remain readable during review.

Run the tool locally before adding its CI job. Sort real defects from acceptable exceptions, then tune the paths and thresholds. A 200-line ceiling and five-file task limit are defaults, not laws. Monorepos, generated compatibility notes, and migrations may need different boundaries.

A clean run proves very little

The linter cannot tell whether an instruction is correct, whether an agent obeyed it, or whether the resulting code is safe. It does not measure task success. It sits at a different layer from the runtime controls in our article on Dogwood's sequence policies, or the fail-closed review behavior in orangu's output handling.

A serious agent workflow has at least three separate checks:

1. Are the instructions structurally usable?
2. Did the agent's actions remain within policy?
3. Did tests, review, and product checks validate the result?

katalint covers part of the first. A clean result means eight heuristics produced no findings. It does not certify a repository for autonomous changes. Put that limitation beside the CI check, because green badges tend to acquire more meaning than their authors intended.

Treat instruction files as maintained interfaces

AGENTS.md and CLAUDE.md are becoming shared project interfaces rather than personal prompt notes. They affect repeated coding sessions, remain in place as models change, and can quietly fall out of step with the commands that enforce project policy.

Anthropic's project-memory documentation also recommends concise, specific instructions and separates memory by scope. Agents differ in filenames and precedence, but the maintenance questions are the same: who owns these files, and what proves that their instructions still match the repository?

That matters more when a team uses several models through ish.chat or one compatible endpoint such as api.ish.chat. Portable repository guidance should favor commands, constraints, and verification criteria a person can audit. Model-specific coaching can live in the appropriate model-specific scope.

katalint is early and incomplete. A practical trial is still worthwhile: run it, review each finding, keep only the rules your repository can defend, and assign an owner to the instruction files. That is ordinary maintenance, which is exactly what this increasingly important layer needs.