What is QUALITY.md?
QUALITY.md is an open specification, an agent "skill," and a CLI that let a project declare its quality standards in a single machine-readable file — the way README.md declares purpose or LICENSE declares terms. Its author, who posted it to Hacker News, frames the goal as shifting teams "from a reactive review/repair mindset to a proactive care mindset."
The interesting part is not the file format. It is what a file format changes about how coding agents behave. When "done" lives in a document both a person and a model can read, quality stops being tacit knowledge held in senior engineers' heads and becomes something you can point an agent at — and, crucially, something you can review the agent against.
Why does a machine-readable quality file matter now?
Because coding agents now write a large share of committed code, and most of them have no stated definition of "good." An agent optimizes for whatever the prompt implies. A QUALITY.md file — a written, versioned standard for what acceptable work looks like — gives the agent an explicit target and gives the reviewer an explicit yardstick.
The timing is not accidental. Two things are true at once in current engineering practice:
- Agents produce more code than any human can carefully read. Volume has outrun review capacity.
- Standards still live informally. They surface in code review comments, in Slack, in the tenure of whoever's been around longest.
A machine-readable standard closes that gap on one side. It does not close it on the other. A written bar tells an agent what to aim for; it does not tell you whether the agent hit it. That distinction is the whole argument of this piece.
Is QUALITY.md the same as linting or CI?
No — and the difference is the point. A linter enforces syntax and style rules mechanically. CI (continuous integration, the automated pipeline that builds and tests code on every change) runs a fixed suite and passes or fails. Both are deterministic gates: they check narrow, pre-encoded rules.
QUALITY.md operates one level up. It encodes intent — the reasoning behind "good," including things a linter can't assert, like whether an abstraction is appropriate or whether an edge case deserved a test. Think of it as the brief an agent reads before it works and a reviewer reads before they approve, rather than the gate that runs after.
That makes it complementary to CI, not a replacement. You still want deterministic gates. QUALITY.md is the thing that tells a probabilistic worker what the deterministic gates are trying to protect.
Where does the "proactive care" framing break down?
The author's "proactive, not reactive" framing is directionally right and easy to over-read. A shared, upfront standard genuinely does prevent a class of rework — you catch drift before it's committed rather than in review. That is real value.
But a written standard is not self-enforcing. This is where Vantrow's category thesis applies directly: the safe pattern is propose, never commit — software should stage a change and let a human accept it, not act on its own authority. A quality spec an agent uses to self-approve is worse than no spec, because it launders unreviewed work as compliant. The same file, used to propose against — "here's my change, here's how it measures against QUALITY.md, here's where I'm unsure" — is exactly the artifact a governed workflow needs.
In other words: QUALITY.md's value is proportional to how it's wired into control, not to the elegance of its schema.
How should a team actually adopt it?
Treat it as a governance artifact from day one. A few concrete rules:
- Write the standard for humans first. If your reviewers wouldn't sign the file, an agent shouldn't optimize against it.
- Keep it versioned and reviewed. Changes to QUALITY.md are changes to your definition of done. They deserve the same scrutiny as code.
- Make the agent report against it, not enforce it. Have the agent state how a change measures up and where it's uncertain. Keep the accept/reject decision with a person.
- Don't let it replace deterministic gates. Keep CI and linting. QUALITY.md explains their purpose; it doesn't do their job.
Adopt it that way and it earns its place. Adopt it as an autopilot rubric and you've built a machine for producing confidently non-compliant code.
The takeaway
QUALITY.md is a good idea for a specific reason: it moves the definition of quality out of people's heads and into a file that both humans and agents can read. That's useful. But a readable standard is a governance instrument, not a guarantee. Its power comes entirely from keeping a human on the accept decision — proposing against the bar, never committing on its own read of it.