A code review that only checks whether it "runs" lets through almost everything that matters: the function that is correct but unreadable, the module that breaks the architecture's boundaries, the endpoint with no access controls. That is why review is done on several axes, each with its own questions.
The five axes
1. Correctness. Does it do what it claims? Does it handle edge cases (empty, null, extreme values, concurrency)? Do the tests prove the behaviour, or only that the code does not blow up? Is there a test that would have failed before the change?
2. Readability. Can it be understood without asking the author? Names that say what things are, functions with one responsibility, linear flows. Code that needs a spoken explanation costs on every future read.
3. Architecture. Does it respect the project's boundaries and conventions? Does it introduce a new way of doing things already solved elsewhere? Does it add dependencies? Does it duplicate an existing utility?
4. Security. Does it validate inputs at the boundaries? Does it check who can do what? Does it expose data it should not? Does it handle secrets correctly? Does it log sensitive information?
5. Performance. Are there loops that query the database for each item? Expensive operations on frequent paths? Lists with no limit? You judge on measurements or concrete risks, not imaginary optimisations.
Size matters
A change that is too big is not reviewed: it is approved out of tiredness. Small changes with a single intention are preferred, accompanied by a description that explains what changes and why. If a change exceeds what can be read carefully in one sitting, you ask for it to be split.
The severity of findings
Each finding says how much it weighs, so the author knows what must change and what can be discussed:
- Blocking: must be fixed before it goes in (defect, security hole, breaking the contract).
- Important: to be fixed, unless there is a good reason.
- Suggestion: optional improvement.
- Note: an observation with no action required.
Findings with no label turn every comment into an ultimatum.
Reviewing an agent's work
Code written by an agent is reviewed with the same rigour, and with one more point of attention: it tends to be plausible, apparently complete, with tests that reflect the code instead of the wanted behaviour. You check what was actually run, that the dependencies exist and that the scope of the change is the one requested.
What to say and how
You comment on the code, not the person. You explain why. You propose an alternative when you object. You acknowledge what is done well: it tells people what to repeat.
Warning signs
- Approving because "the tests pass" without looking at what they prove.
- A change too big to be read.
- Findings with no severity.
- No attention to security because "it is internal".
- Trusting the agent's code because "it ran the tests".
An example
A change adds an endpoint to export orders. On the correctness axis: it works. On security: no check that the user may see those orders (blocking). On performance: one query per order (important). On readability: an unclear name (suggestion). The author knows at once where to start.
When to use it
Before merging any change into the main branch, when reviewing your own code, another person's or an agent's, and when assessing quality on several dimensions.
This method derives from the open-source agent-skills family by Addy Osmani (MIT licence), rewritten and adapted.
This article is an OIAR skill
What you have just read is the content of a skill from the OIAR catalogue, written for people. Knowledge like this, but richer and deeper, written for the agents, drives the interviews, the analysis and the report inside the platform. Skills are used in OIAR: to try this one on a project of yours you need an account.
code-review-and-qualityA method for reviewing a change on five axes (correctness, readability, architecture, security, performance) with findings graded by severity, including for code written by an agent. Use it before merging a change or when assessing the quality of your own or someone else's code.