Introducing PR-Level Rules:
Review the PR, Not Just the Code
Enforce team conventions for commit messages, PR descriptions, breaking changes, and more — automatically
Code review isn't just about the code. It's about context: Why was this change made? Is the PR focused on one thing? Are breaking changes documented? Until now, AI code review tools ignored all of this. Today, that changes.
We're excited to introduce PR-level rules — a new category of rules that analyze the entire Pull Request, not just individual files. With two new special tags, pr-level and git-history, you can now enforce your team's PR conventions automatically.
What's New
Traditional AI code review analyzes files one by one, checking for bugs, security issues, and patterns. But some of the most important aspects of a good PR can't be found in any single file:
PR Description Quality
Does it explain WHY, not just WHAT?
Commit Messages
Do they follow Conventional Commits?
PR Scope
Is it focused on one logical change?
Breaking Changes
Are they documented with migration steps?
Now diffray can check all of this — automatically, on every PR.
Two New Tags: pr-level and git-history
We added two special tags that change how the AI agent processes rules:
pr-level
For rules that analyze the entire PR holistically — description quality, scope, breaking changes documentation, test coverage for new features.
The agent looks at the big picture: What files changed? How many? What's the overall intent?
git-history
For rules that need commit history analysis — message format, atomic commits, ticket references.
The agent uses git log to inspect commit messages and patterns.
Example Rules You Can Use Today
1. PR Description Must Explain "Why"
The most common problem with PRs: they list what changed, but not why. Reviewers can see the diff — they need context.
- id: pr_description_explain_why
agent: general
title: PR description should explain motivation
importance: 7
always_run: true
match:
file_glob: ['**/*']
checklist:
- Check if PR description explains the business reason
- Verify it answers "Why is this change necessary?"
- Look for context about the problem being solved
tags:
- pr-level
- qualityBad PR Description
- Updated UserService.ts
- Added validation to login form
- Fixed payment bug
Good PR Description
## Problem
Users saw timeouts during checkout with 50+ items due to N+1 query.
## Solution
Batch loading with DataLoader pattern.
2. Conventional Commit Messages
Enforce consistent commit format for automated changelogs and semantic versioning:
- id: commit_message_format
agent: general
title: Commit messages should follow conventional format
importance: 5
always_run: true
match:
file_glob: ['**/*']
checklist:
- Use git log --oneline to check recent commits
- Verify commits follow type(scope): description format
- Check for clear messages (not "fix stuff", "WIP")
examples:
bad: |
fix stuff
WIP
update code
good: |
feat(auth): add OAuth2 login with Google
fix(api): handle null response from payment service
tags:
- git-history
- automation3. Breaking Changes Must Be Documented
Nothing breaks trust faster than undocumented breaking changes hitting production:
- id: breaking_changes_documented
agent: general
title: Breaking changes must be clearly documented
importance: 9
always_run: true
match:
file_glob: ['**/*']
checklist:
- Check if changes modify public APIs or remove features
- If breaking, verify commit messages include BREAKING CHANGE
- Check for migration guide in PR description
tags:
- pr-level
- git-history
- breaking-changes4. Single Responsibility PRs
PRs that mix features, bug fixes, and refactoring are impossible to review well:
- id: pr_single_responsibility
agent: general
title: PR mixes unrelated changes
importance: 7
always_run: true
match:
file_glob: ['**/*']
checklist:
- Review changed files to identify distinct areas of change
- Check if changes span multiple unrelated features
- Flag if PR touches auth AND payment AND styling
tags:
- pr-level
- quality5. Ticket References Required
For traceability and release notes, every PR should link to an issue:
- id: pr_ticket_reference
agent: general
title: PR should reference an issue or ticket
importance: 5
always_run: true
match:
file_glob: ['**/*']
checklist:
- Check commits for ticket references (PROJ-123, #123, ENG-456)
- Look for issue URLs in commit messages
- Only flag if NO commits have any ticket reference
tags:
- pr-level
- git-history
- traceabilityHow It Works Under the Hood
The general agent has been updated with special instructions for handling these tags:
| Tag | Agent Behavior |
|---|---|
| pr-level | Analyzes overall PR context — files changed, scope, description quality |
| git-history | Uses Bash to run git commands:git log --oneline -20 — recent commitsgit log --stat -5 — with file changesgit log --format="%s%n%b" -10 — full messages |
Rules with always_run: true execute on every PR regardless of which files changed. This makes them perfect for PR-level checks that don't depend on specific file patterns.
Getting Started
Adding PR-level rules to your project is simple:
1. Create the rules directory
mkdir -p .diffray/rules/pr-quality2. Add your rules
Create YAML files with always_run: true and the appropriate tags
3. Open a PR
diffray will automatically pick up your new rules
We've published example rules in our project-specific-rules repository that you can copy and customize.
Why This Matters
Good PRs are about more than just working code. They're documentation for future developers. They're audit trails for compliance. They're the difference between "what happened here?" and "ah, I understand."
Teams that enforce PR standards ship better software. Not because the code is different, but because the context is preserved. Now diffray can help you maintain those standards automatically.
PR-level rules turn tribal knowledge into automated enforcement. Instead of hoping everyone remembers to link tickets, document breaking changes, and write meaningful descriptions — you get consistent feedback on every PR.
Try PR-Level Rules Today
Available now for all diffray users. Add the rules to your repo and start getting feedback on your next PR.