{"slug": "claude-code-in-a-large-codebase-review-workflows-that-actually-help", "title": "Claude Code in a Large Codebase: Review Workflows That Actually Help", "summary": "Darius Tran, an engineer at AI Hive, described a workflow for using Claude Code as a first-pass code reviewer on large codebases, centered on a repository-level CLAUDE.md file that lists review priorities and explicit items to ignore. Tran said the ignore list cut most of the noise, and recommended piping git diffs into non-interactive runs with a fixed output format, running a separate narrow security pass, and tracking how many AI comments lead to code changes.", "body_md": "AI code review sounds great until it leaves forty comments on a pull request and thirty-eight of them are about naming. I've spent a while figuring out how to make Claude Code useful on a large codebase without that noise. Here's the workflow that stuck.\n\nThe biggest quality jump came from writing down the things a senior engineer would tell a new hire. Claude Code reads a `CLAUDE.md` file in the repository, so that's where this goes.\n\n```\n# CLAUDE.md\n\n## Review priorities\n1. Correctness: logic errors, unhandled errors, race conditions.\n2. Security: input validation, secrets, permission checks.\n3. Breaking changes to public APIs or database schemas.\n\n## Ignore in reviews\n- Formatting and import order (handled by the linter).\n- Naming preferences unless a name is actively misleading.\n\n## Project facts\n- All money values are integers in cents.\n- Database access goes through the repository layer, never raw SQL in handlers.\n```\n\nThis file does two jobs. It tells the model what to care about, and, just as important, what to skip. The \"ignore\" list cut most of the noise for me.\n\nOn a large codebase, asking for a review of \"the project\" produces vague, generic feedback. Point it at the change instead. A simple pattern is to pipe the diff into a non-interactive run:\n\n```\ngit diff main...HEAD | claude -p \"Review this diff using the priorities in CLAUDE.md. \\\nList only issues that could cause a bug, a security problem, or a breaking change. \\\nFor each, give the file, the line, and a one-sentence reason.\"\n```\n\nThe explicit output format matters. Without it, you get essays. With it, you get a list a human reviewer can check in two minutes. Check the current Claude Code documentation for the exact flags in your version before wiring this into scripts.\n\nI treat the AI review as a first pass, not an approval. A person still owns the merge decision. In practice, the AI catches the tedious things (a missing null check, an error swallowed in a catch block), and the human spends their attention on design and intent.\n\nTwo rules that helped the team trust the output:\n\n`CLAUDE.md` so it doesn't happen again.\nThat second rule turns false positives into documentation. After a few weeks, the file becomes a useful description of how the codebase actually works. I wrote up a longer look at [real costs and production results from Claude Code reviews](https://aihive.global/blog/claude-code-review/), including where it falls short.\n\nI don't mix security review into the general review prompt. A single prompt that tries to check correctness, style, and security tends to do all three halfway. Instead, I run a second, narrow pass that only looks for things like secrets in code, missing permission checks, and unvalidated input reaching a database query.\n\nThe output goes into the same PR, labelled separately. Reviewers know that anything in the security list deserves a closer look, even when the general review looks clean.\n\nLarge diffs cost more and get worse reviews. I ask for smaller pull requests anyway, and the AI review is one more reason. If a diff is huge, split the review by directory.\n\nI also don't run it on every push. It runs when a PR is opened or marked ready, which keeps costs predictable.\n\nThe question isn't \"is the AI smart?\" It's \"are we catching more real issues before merge, with less reviewer time?\" Track how many AI comments lead to a code change, and how many get dismissed. If dismissals stay high, tighten the priorities in `CLAUDE.md`.\n\nWhat's in your review context file, and which instruction cut the most noise for you?\n\nI'm Darius Tran, and I work on getting AI into real engineering and operations workflows at [AI Hive](https://aihive.global/).", "url": "https://wpnews.pro/news/claude-code-in-a-large-codebase-review-workflows-that-actually-help", "canonical_source": "https://dev.to/dariustran/claude-code-in-a-large-codebase-review-workflows-that-actually-help-1ko8", "published_at": "2026-11-06 02:16:32+00:00", "updated_at": "2026-11-06 02:22:47.122872+00:00", "lang": "en", "topics": ["ai-tools", "ai-agents", "developer-tools", "artificial-intelligence"], "entities": ["Claude Code", "Anthropic", "AI Hive", "Darius Tran"], "also_reported_by": [], "alternates": {"html": "https://wpnews.pro/news/claude-code-in-a-large-codebase-review-workflows-that-actually-help", "markdown": "https://wpnews.pro/news/claude-code-in-a-large-codebase-review-workflows-that-actually-help.md", "text": "https://wpnews.pro/news/claude-code-in-a-large-codebase-review-workflows-that-actually-help.txt", "jsonld": "https://wpnews.pro/news/claude-code-in-a-large-codebase-review-workflows-that-actually-help.jsonld"}}