Seiso: A Markdown Convention and Linter for AI-Written, Human- and Agent-Read Docs
Key Highlights
Seiso, written in Rust, tackles a growing problem: when docs are generated by AI yet must be read by both humans and agents, messy formatting hurts everyone. It provides a set of Markdown authoring conventions plus a linter that enforces them automatically, so documents written "for people" and "for machines" no longer have to compromise with each other.
What It Does
Seiso defines conventions for document structure, heading levels, code-block annotations, and frontmatter, then ships a CLI checker that scans repositories and flags violations. It can block bad docs in CI on commit and also fix batches locally, turning convention enforcement into a single command rather than relying on humans to spot formatting in code review.
Technical Details
The Rust implementation delivers high speed and low overhead, which matters for running frequently across large repositories. Rules are designed around "stable machine parsing"—for example, every code block must declare its language, ambiguous headings are forbidden, and link styles are unified to reduce agent misreads and make human skimming easier by lowering cognitive load.
Versus Alternatives
Compared with general Markdown linters such as markdownlint, Seiso focuses on the specific need of "human-and-agent co-reading" in AI-assisted workflows. Its rules lean toward structure and parseability rather than pure typographic polish, positioning it closer to engineering than to writing, and answering a new generation of documentation workflows.
Who Should Use It
It fits teams where AI assistants generate READMEs, specs, or runbooks that both engineers and other agents consume. Platform and developer-experience groups that care about reproducible doc quality in monorepos will get the most value, because it converts "documentation quality" from a subjective feeling into a measurable gate.
Getting Started
Adopting it is usually a two-step change: add the CLI to CI and run the autofix locally once to normalize history. From then on, new AI-written docs are checked on every pull request, and the lint output doubles as onboarding for what "good doc shape" means on the team.
Industry Impact
As AI increasingly writes documentation, a shared machine-readable standard becomes critical. Seiso gives teams a low-cost path to make AI write, humans review, and agents read from one discipline. In short, it is the gatekeeper of doc quality in the AI era, and a small dependency with outsized leverage.
Closing
As agents start writing more of our docs, a linter that keeps those docs machine-friendly is quietly becoming essential infrastructure.
Further Reading
Further Reading
If you adopt Seiso, the highest-leverage move is to wire it into the pull-request flow on day one rather than treating it as an occasional local check. When the linter blocks a merge, it teaches the whole team the house style through friction instead of through a wiki page nobody reads, and over a few weeks the AI-generated docs converge to a shape agents can parse reliably. A subtlety worth planning for is scope: start with a tight, opinionated ruleset and expand only when a real failure justifies it, because an over-strict linter gets disabled faster than a loose one gets tightened. Pair it with a short contributor guide that explains the why behind each rule, so the checks feel like shared standards rather than mysterious gatekeeping. For organizations already using an agent to write documentation, Seiso is the difference between "docs that happen to be machine-readable by accident" and "docs that are machine-readable by design."
Practical Notes
Practical Notes
The most effective way to roll out Seiso is to wire it into the pull-request flow on day one, because a linter that blocks a merge teaches the whole team the house style through friction rather than through a wiki nobody reads. Within weeks, AI-generated docs converge to a shape agents can parse reliably. A subtlety worth planning is scope: begin with a tight, opinionated ruleset and expand only when a real failure justifies it, because an over-strict linter gets disabled faster than a loose one gets tightened. Pair it with a short contributor guide explaining the why behind each rule, so checks feel like shared standards rather than mysterious gatekeeping. For organizations already using an agent to write documentation, Seiso is the difference between docs that are machine-readable by accident and docs that are machine-readable by design—and that difference compounds across every downstream tool that consumes them.