Code review has been and will always be an important part of software engineering, and it’s even more important now.
Agents like Claude Code and Codex have given us back a lot of our time. So it only makes sense for us to take back this time and do more important work on our projects and repositories. One of those things is proper code review.
Code review is so important that the team at Anthropic updated a skill called /simplify to /code-review. The idea behind this was very simple. When developers were done building a feature or fixing a bug, they called /code-review, and it did exactly as the name implies. It reviewed the code and reported the bugs.
But let us talk about why reporting just bugs is a problem.
How /code-review works
We invited Claude Code into our repository and gave it a task: build us a simple checkout page. It did wonderful work.
Then we ran /code-review. It reviewed our code and found bugs and issues that shouldn’t go to production.
But we are not satisfied. So let us take a look at the code itself.
Code review is bigger than bugs
Looking at the file we’re about to push to production, we see a couple of issues. First, it’s a very lengthy file. It’s an actual behemoth of a file. It’s also importing from modules it shouldn’t be importing from.
In a lot of engineering teams, this is not acceptable, mainly because it is hard to maintain, and it is almost a nightmare to scale features and products like this.
The /code-review we ran earlier did not catch these issues, but it caught a lot of bugs. And the thing about that is, code review is bigger than bugs.
Our job as engineers is to make sure that we push code and product that is easy to scale and easy to maintain, that anyone, a new engineer or even an agent, can pick up and do wonderful work with.
The solution is in two words: coding conventions
Before agentic development, a lot of engineering teams had something called documentation. It contained a coding style and a standard for how code should be written internally. It also contained rules for how files and folders should be structured and named.
Teams shared this documentation with their members and even new hires. It helped everyone stay aligned on how code is written at that company.
When agents like Claude Code and Codex were introduced, it would make sense to just copy the entire conventions into CLAUDE.md. But there is a problem with that.
The problem is the length. The team at Anthropic suggests that the CLAUDE.md file should not be more than 200 lines long. A lot of companies have coding conventions that are about 2,000 lines long. If you have that inside your CLAUDE.md, you might have a context problem. You will either be wasting tokens, or you won’t get the results you need.
Another popular solution we’ve seen in the industry is engineers taking the link to this documentation and pasting it directly inside the CLAUDE.md file. What we expect to happen is that whenever we fire up /code-review, it accesses that link, reads our coding style guides, and applies them to the work we just did.
There are a couple of problems with this. That file could be moved by someone on your team. Your internet might be slow. Or the last one, which is more important and happens a lot: Claude might just not want to access that file. And you don’t want the maintainability and scalability of your feature to depend on the internet.
Bring your coding conventions home
So here’s a suggestion that has worked for a lot of engineering teams. Bring your coding conventions home. Have them inside the .claude/rules folder.
But don’t just paste all of your coding conventions in one file. Have them in different modules. Have a module for your naming conventions, for structure, for databases, for errors, for APIs.
And then you can have a prompt that looks like this inside your CLAUDE.md file.
The reason it’s best to split them into different modules is so that whenever /code-review is fired up and Claude is trying to read your conventions, it doesn’t have to read all of them. It reads just the conventions that matter to the work it has done.
Back to the checkout
To see this in action, let us go back to the project we had earlier. We have brought our coding conventions home. Inside the .claude/rules folder, we have different modules that contain our coding conventions, style guides and standards. Now let us fire up /code-review again.
As we can see, the file is way more modular and easier to read, and the imports are safer. So this feature is ready for production.
The truth is that Claude Code and Codex will keep getting better and better, and in turn will give us more time to work on other important stuff in our codebases and repositories. Code review will always be one of those important things for us to give our time to.
So let us keep looking for maintainable ways to write our code and review our code, not just for bugs, but to make sure that it’s able to scale, and more importantly, that it’s safer for our customers.