AI keeps getting better.
At the beginning of 2026, coding agents could do a lot in a codebase like ours at Clay. Yet, they still needed close supervision to write code that worked reliably and was well organized. Sometime this summer, we turned a corner: AI models now rarely write bugs, and the bugs they write are usually caught by review agents. Given a large task, they can usually produce a decent first draft with minimal guidance. In the pre-AI world, it was near-impossible for a human to be productive in an unfamiliar codebase; now, with an agent’s help, this is shockingly feasible.
Historically, human code review has been incredibly important for preventing bugs from getting merged and for making sure that at least two people are familiar with any given piece of code. But these two goals are much less important than they used to be. More than ever, code review can feel like a chore and even a waste of time: “I’m sure Codex already checked this more carefully than I can; am I really going to find a bug it didn’t?”
The new goals of code review
Code review is still valuable, but we’ve shifted its goals toward high-level review and any aspects that are risky or hard to change later. For example:
- “Is this PR solving the right things?”
- “Is the code’s overall architecture good?”
- “Has enough validation been done?”
- “Is it okay to ship now and iterate later if needed, or is this one of the rare cases where we need to get it right upfront?”
For any larger change, these are the areas we scrutinize and discuss more closely, because they’re important to get right the first time:
- Data schemas and what pieces of infrastructure we’re using. These affect how other code is written and require careful backfills to change later. Adding new third-party libraries also tends to have larger impacts on code structure.
- How the code is organized at a high level. Which service handles what things? Where are the boundaries between large components? Essentially, which areas of the code are responsible for what things? As one example, we generally want to avoid product-specific logic in our shared foundations.
- Establishing new code patterns that will be repeated throughout our codebase. Even if we aren’t reading every line of code, we should still keep the codebase understandable by humans. And good helper functions help future agents, too! Likewise, new code that doesn’t follow preexisting best practices can contribute to “rot” that spreads and reduces the consistency and quality of our codebase.
- Security and reliability. If a change could compromise the rest of our system, it’s important to get it right.
By count, most PRs probably won’t affect any of these, and we can spend less time on them. As we focus more on technical design, we’ve given ourselves permission to spend less time on every detail of the code. For most pull requests, we no longer need to try to find bugs by hand, and we don’t need to read and check every single line of code.
Not reading all the code might be scary. It sure sounds scary to me! But the agents have our backs, and we need to focus our valuable engineering time on what agents can’t do for us.
Shifting left
If you’re working on a large change, when’s the right time and place to discuss these higher-level technical design questions? Having the discussion in the PR itself is often not the best place!
At Clay, architecture discussions should happen before anyone reviews a complex PR in detail.
Before a reviewer even opens a diff, it’s helpful for everyone to discuss and agree on the overall technical design and on answers to the biggest decisions. It’s easier for reviewers to understand the high-level points if they don’t have to jump through thousands of lines of code just to tell what’s going on. It’s also helpful to talk about an entire plan upfront rather than independently reviewing each PR in a series.
As an engineering team, our aim is to have more conversations about technical designs than we’ve had historically. Compared to before, our engineering team is bigger, we are building more ambitious products, and our standards for engineering excellence are higher (performance, reliability, security, and more — which our customers depend on). All of these factors make good technical architecture more important.
These discussions don’t need to be heavyweight, and we don’t require engineers to write a structured document. If discussing in a quick Slack thread or at the end of a team meeting is enough for everyone to get on the same page, that’s great! Oftentimes discussing live is the most effective way to get on the same page. But if someone is proposing a more complex change (or if they could use a hand in figuring out how to), we recommend writing up a proper document and socializing it with other teams.
More than anything, we’re making a point to talk to each other more! We spend so much time these days typing to our coding agents, and it can be isolating. Talking more about technical decisions helps us choose well, but it also lets us learn from each other more often and collaborate more deeply.
It’s now easier than ever to quickly throw together a proof-of-concept PR for a potential direction, even when it changes an enormous amount of code. Contrast this with the olden days, when even trying out a possible direction could take weeks of work, which was an additional reason to do an architecture review beforehand. The speed with which you can now produce a big PR can be very helpful — oftentimes, prototyping a solution and finding what parts are tricky teaches us a lot — but it isn’t a substitute for writing up or discussing the technical design with coworkers.
If one of our engineers receives a complex PR without context on what the author is trying to do or how, they should ask the author to write a high-level document about what they’re proposing and hold off on reviewing the PR until after that architecture discussion.
When our engineers put up a proof-of-concept PR, they are asked to make it clear to reviewers that it is a proof of concept and to avoid getting too attached to their initial prototype since it might need to change. Part of the beauty of being able to try things quickly is that it’s also less costly to throw things away.
How good is “good enough”?
As an engineer doing a review, when should you accept it and when should you request changes?
Different engineering teams at Clay may be optimizing for different things in their technical approach. Some teams focus on getting a product out in the world and then iterating quickly on feedback; others focus on building a reliable, scalable platform. This is expected!
If an engineer at Clay proposes a change to a system maintained by another team, the receiving team decides what their “bar” is for the systems they maintain. For example, changes to our product platforms typically require added care, and architecture discussions are even more valuable. Conversely, teams that own areas of the codebase that other teams contribute to should help those contributors get it right the first time by providing good AGENTS.md guidance and documentation about what not to do.
We expect each author to make sure their work meets a minimum quality bar before bothering anyone else with it. When an engineer authors a change, they’re always the primary person responsible for its correctness and appropriateness.
When designers and PMs send small contributions to our codebase, it’s on our engineers to help them understand what “good” looks like. Contributions from non-engineers can save time on back-and-forth and often help us meet a higher bar of product quality. But because the authors may not have even opened the code, it’s important for our engineers to review these PRs a little more carefully than they might for a similar PR from an engineering teammate, since they are the engineers responsible.
When our engineers receive a PR from a non-engineer whose code is low quality, not following our standards, or that would take a long time to review, they can reject it and help the author understand what’s missing (and perhaps make the changes themselves, if they’re important). In tandem, we’re building prompts and tools that help designers and PMs create PRs that are more likely to be good out of the box, and that help them understand what types of changes they should expect success with.
Speedy reviews are everyone’s job
Waiting for someone to look at your PR is no fun.
One of the goals of holding architecture discussions earlier is to make the PRs themselves quicker to review.
For complex PRs, more time should be spent by the creator of a change than by the person reviewing it: the burden is on the author to make a change easy to review. As an author, the best way to do this is to make sure reviewers already have context on what changes you’re making and what type of review would be most helpful, by just talking about your plans with them! It also often helps to split up your PR into a stack of smaller changes. Reviewers can request changes on a PR if the author hasn’t structured it in a digestible way and properly reviewing it would take a disproportionate amount of time — again, just go talk to the author!
Being a good engineering citizen means responding to PRs quickly when they’re sent to you. We encourage engineers to clear their pending reviews whenever they sit down at their desk, before doing other work. We also recommend setting up Slack notifications for review requests.
If we all do our part, the whole team moves faster.
The agents are on it
To recap, here’s our revised internal position on code reviews:
- Let’s spend more time on the bigger technical decisions and do so earlier in the development process
- Let’s spend less time on the smaller details of the code and trust the agents to get it right
- Let’s review each other’s PRs quickly whenever possible so we can all move faster
- In general, let’s just talk to each other more so that we build shared context and learn from each other, and avoid slinging big PRs out of the blue with a “just sent you a big PR, can you please review today”
Coding agents will certainly continue to get better, and we’ll undoubtedly need to revise this internal guidance again at some point, but this is a good place to be for right now.
We’ll also continue to improve our internal tooling: Our developer experience team at Clay has been working on giving agents better tools to test their app changes end-to-end while showing you what they’ve tested. They also plan to invest in a PR bot that scores how risky a PR is across a few dimensions, assess or build tools to more easily monitor changes that affect a team’s areas, and experiment with auto-approval for low-risk changes.
In the future, we could do more to help the PR review agents fight among themselves without a human needing to be in the loop, and to use agents to make it easier to understand what changes are being made. Thariq Shihipar, who formerly worked on Claude Code at Anthropic, shared one possible direction. The future is our oyster!
.avif)
.avif)
