How Oblique handles code review etiquette

Code reviews can be a source of immense anxiety for engineering teams. Many of us have had bad experiences with nitpicking, bike-shedding, or that’s-not-how-I-would-have-done-it-itis. This is such a common pain point that there are entire research projects built around code review anxiety and how to reduce it.

The age of agentic coding brings a whole new layer to this dynamic: a fellow engineer disappearing into a cave and coming back with 12,000 lines of code you were expected to review that same day used to be a cautionary horror story; now that could be an average Tuesday with a poorly supervised agent. Do you let it by with a cursory LGTM? Do you throw another agent at it to do the review for you? Do you even still have coworkers?

It doesn’t have to be like this.

The fun thing about building a startup is you also get to build an engineering team from scratch, with your own engineering culture: one that hopefully avoids the worst of the friction from past jobs. We’re small enough now that we can talk as a group about how things should be done, but we won’t stay this size forever. Given how quickly norms are changing across the industry, we wanted to take some time to write down how we navigate code reviews at Oblique so that we’re all on the same page about how we want to collaborate as a team.

Here’s where our internal guidance landed.

Know what the goal is

The explicit goal of code review is to ensure high-quality engineering. The implicit goal, which is just as important, is to ensure high-quality communication among team members. Even on a small team it is easy to lose track of how our product and codebase are changing, and code reviews are a crucial tool for sharing context and thinking.

That means both authors and reviewers should treat code reviews primarily as an act of collaborative learning. Do not send slop PRs, which are disrespectful of the reviewer’s time. Do not send slop reviews, which are disrespectful of the author’s effort.

PRs are not a good venue for debating architecture, and should not replace engineering discussions and design documents. Good communication starts long before the code gets written. If you as a reviewer are surprised by the contents of PR, that’s a sign that there’s a gap in the team’s communication somewhere. If a reviewer has concerns about the fundamental approach of a change, that should be expressed as a top-level comment or, better yet, through a conversation with the author.

Optimize for the reviewer

We all have different styles of working, but at the end of the day, someone else has to be able to read and understand your code. Oftentimes that someone else is you, six months (or days) from now.

Consider how diffs read and attempt to minimize them. Before sending a PR for review, authors should read through their own change in the GitHub UI—you’d be amazed at what mistakes you’ll suddenly spot when you’re looking at your own code in a different context. Reduce changes that aren’t relevant to the core logic, ensure tests have clear names, comment complicated blocks, follow the existing style of the surrounding code.

PR size is more of an art than a science. Keep PRs self-contained, brief, and reviewable. Large PRs can become functionally impossible to review, while extremely small ones lose the context of the change. Always attempt to compose the smallest PR that stands on its own. Wherever possible, work iteratively and merge code behind feature flags instead of developing out-of-tree.

Author responsibilities

We trust one another to use the best tools for the job, and we also expect that authors are responsible for all code they send. This means that authors should read, review, and understand any changes generated by coding agents. Authors are not required to disclose their use of AI tools, and reviewers should have the same standards regardless of how a change was created.

What is important to disclose is the maturity and intent of your change. If you threw a prototype together just to explore a concept and you don’t care if it ever gets merged, regardless of whether that prototype was handcrafted by you or by Claude, that should be expressed clearly in the PR description so that reviewers know what kind of feedback to provide.

Agentic tools have a tendency to produce functions with long names and flowery multi-line comments. These often have little substance despite their verbosity. Reviewers will always appreciate a hand written test name, or a few comments on the key lines over a spaghetti of helpers.

Every commit to main must work. This means if a backend change introduces something that breaks the frontend or vice-versa, it must be feature-flagged or the exception must be handled. Authors alone bear the risks for large branches and conflicts that occur because of them. Moving fast is not an excuse for breaking things.

Reviewer responsibilities

Prioritize code reviews over writing code. A reviewer that lets their queue get out of hand blocks the whole team. Each reviewer is expected to set up their notification workflow such that they can provide timely responses. (At Oblique, we rely heavily on the Slack and Linear integrations for GitHub.)

Trust your teammates to take your feedback seriously. Where possible, approve the PR with comments to avoid a second round-trip.

Ask for help when you need it. If a PR feels too unwieldy to understand, it’s okay (encouraged even!) to ask for it to be broken up into smaller pieces. Everyone benefits from a better shared understanding of the logic. Alternatively, don’t underestimate the power of asking to walk through a review together.

It’s also okay to ask an agent to help you digest the PR, as long as you remember that the end goal is for you to understand the PR. If you’re just copying and pasting an agent’s review output into GitHub, you’re not exactly adding anything the author couldn’t have done themselves.

Reviews should focus on APIs and the tests for those APIs. Don’t overindex on style or internal details, unless those have a noticeable impact on performance, security, or readability. Critiques should be constructive and substantive - there are many different ways of accomplishing the same thing, and someone else choosing a different path than you does not necessarily mean they’re wrong. If there is a substantive reason to align on a specific style, add a linter or update the relevant AGENTS.md files.

Always remember that your teammate is on the receiving end of the review. A good reviewer takes a moment or two to digest the change as a whole before providing feedback. Avoid knee-jerk reactions and brigading, and consider the tone of your comments. When in doubt, discuss face-to-face.

Conclusion

Our team is still small, so these expectations seem obvious to all of us now. The good thing about writing this down is that when we fall short of our ideals, we have documented guidance that we can revisit to course-correct. It also means we have a historical snapshot of our thinking, which makes it easier to see if our old practices are no longer serving us. Software engineering has always been a dynamic practice, and these days it’s changing faster than ever. Now we have a baseline.