Quality Must Survive the Agent's Shortest Path to Green
For addyosmani/agent-skills, a passing test is an important signal but not a complete definition of quality. This chapter diagnoses the “green but weak” result: code that satisfies a narrow check while becoming harder to review, less secure, more coupled, slower, or less honest about what was verified. It then follows the repository’s response—five-axis review, written constraints, cost-based gates, ratchets, atomic history, and behavior-preserving simplification—so readers can see how a quality floor becomes enforceable instead of remaining advice.
The risk is not unique to agents, but agents make it more visible. An agent is rewarded by the immediate state of the task: a failing check is an obstacle, while a green check looks like permission to continue. If the cheapest route to green is to weaken the test, lower the threshold, add a suppression, or leave a stub, the project needs controls that make those moves visible and costly.
Passing tests are necessary but insufficient
Tests answer a bounded question about the behavior they cover. They can show that a function returns the expected result, that a bug reproduction now passes, or that a known flow has not regressed. They do not automatically show that the change fits the architecture, uses a stable interface, handles secrets safely, stays within a performance budget, or can be understood and reverted by the next engineer.
That is why the repository’s review workflow uses five axes: correctness, readability, architecture, security, and performance. Correctness asks whether the code matches its requirements, handles error paths, and has tests that actually exercise the intended behavior. Readability asks whether another engineer can follow the names and control flow without a private explanation. Architecture asks whether dependencies and responsibilities remain in the right places. Security asks how inputs, authorization, secrets, and external data are handled. Performance asks whether the change introduces unbounded work, N+1 access, unnecessary rendering, or another measurable bottleneck.
The axes are not five independent compliments or five opportunities for personal taste. They are a differential diagnosis for a green result. If a test passes but the file now carries unrelated branches, readability or architecture may explain why the change is weak. If the feature works in a happy-path test but accepts unvalidated external input, security explains the missing evidence. If a list endpoint passes its unit tests while fetching an unbounded dataset, performance identifies a user-facing consequence the unit test did not observe.
The review process therefore begins by understanding the intent and reading the tests, then walks through the implementation with all five dimensions in view. It asks what was verified, which commands were run, whether runtime behavior was checked, and whether a UI change has before-and-after evidence where relevant. “All tests pass” is a data point in the verification story, not the story itself.
A constraint is enforceable only when it has a mechanism
Prose standards are easy to agree with and easy to renegotiate under deadline pressure.