Blog
How to review pull requests against your own team's rules
Published
Generic review tools flag generic problems. Your team has rules they don't know. Never reset the database, write a migration. Money is integer cents, never floats. Images go through the upload service, never straight to S3.
There are three ways to check a pull request against rules like these. Each fits a different kind of rule.
1. Write the rule as code: Semgrep, ESLint, ArchUnit
Use this for rules that are a code pattern. Semgrep rules are YAML that match your internal APIs or forbidden calls. ESLint takes custom rules and no-restricted-imports. ArchUnit and dependency-cruiser enforce module boundaries.
- Strength: deterministic. The same code gets the same result, and it runs in CI.
- Limit: someone has to write and maintain every rule in the tool's syntax.
- Limit: it cannot check a rule that is a judgment, like “queue the billing call, never inline” or “this change needs a migration.”
If a rule is a pattern, write it as a lint rule. Harbor does not replace that.
2. Write review instructions: CodeRabbit, Copilot code review, Qodo
Use this when you want an AI reviewer to follow your standards. You write path-specific instructions or a guidelines file, and the reviewer applies them.
- Strength: handles rules written in plain language.
- Limit: you write and update the instructions by hand, per tool. They go stale as the code moves.
Which rule files each of these reviewers reads, and from which branch, is in which AI code reviewers read AGENTS.md and CLAUDE.md.
3. Let the rules come from how your team already works: Harbor
Harbor reviews every pull request against your team's rules, and it learns those rules instead of waiting for you to write them.
- It reads
CLAUDE.md,AGENTS.md,.claude/rules, Cursor and Copilot rules, andCONTRIBUTING.md, from the base branch. A pull request cannot rewrite the rules it is checked against. - It also learns rules from coding sessions, review threads, Slack and docs. Dana tells Claude Code not to reset the database, and she says it a single time. That becomes a rule, and the next pull request on a private repo that breaks it gets a comment on the line.
- It comments on the line that breaks a rule or has a bug. It never fails your build. Turn on Block merging until the review finishes if you want a merge to wait until the review has run.
- Anyone who can push can reply
@harbor-brain wrongto Harbor's comment on a pull request to dispute a rule. Rules that go stale are flagged or retired. - Every rule shows how often it was served and cited, so you can retire one with evidence.
Example comment on a pull request that adds user avatars:
The same rules also go to your coding agents before they write the code, so fewer pull requests break a rule in the first place.
Which should you pick?
| Your rule is | Use |
|---|---|
| A code pattern or import boundary | Semgrep, ESLint, ArchUnit |
| Plain language, and you will maintain it | Review instructions in your reviewer |
| Something the team already says in sessions, reviews and Slack | Harbor |
Most teams combine approaches. Keep the lint rules in CI. Add Harbor for the rules that live in people's heads and review threads.
Try it on a repo
Connect GitHub in Harbor and turn on Code review. Nothing is installed on anyone's machine. From the first pull request it checks the rule files your repo already has. The Free plan lets you try it with no card, and includes 10 reviews. Setup is in the GitHub App tutorial, and what the review reads and keeps is in the code review docs. To connect your coding agents as well, use the install command on the Harbor home page.
Limits, stated plainly: Harbor's review is a model, not a deterministic checker, so it can miss a rule or flag one wrongly. Use the dispute reply to correct it. For hard pattern rules, keep a linter.
Questions
How do I review pull requests against my own team's rules?
There are three ways. Write rules that are a code pattern as code, with Semgrep, ESLint or ArchUnit, and run them in CI. Write plain-language rules as review instructions in an AI reviewer such as CodeRabbit, Copilot code review or Qodo. Or use Harbor, which reads the rule files your repo already has and learns more rules from coding sessions, review threads, Slack and docs, then comments on the line that breaks one.
When is a linter like Semgrep or ESLint the right tool?
When the rule is a code pattern or an import boundary. A linter is deterministic, so the same code gets the same result in CI. It cannot check a rule that needs judgment, like "this change needs a migration", and someone has to write and maintain each rule in its syntax.
Can a pull request change the rules it is reviewed against?
With Harbor, no. It reads CLAUDE.md, AGENTS.md, .claude/rules, Cursor and Copilot rules and CONTRIBUTING.md from the base branch, so a pull request cannot rewrite the rules it is checked against.
Does Harbor fail the build when a pull request breaks a team rule?
No. It comments on the line and never fails the check. Turn on Block merging until the review finishes, and require the Harbor review check in GitHub, if you want a merge to wait until the review has run.
What if Harbor flags a rule that is wrong?
Anyone who can push to the repo can reply @harbor-brain wrong to the comment and say why, which marks the rule disputed for its owner. Harbor's review is a model, not a deterministic checker, so keep a linter for hard pattern rules.