Your team built something solid. You’ve got shared coding standards. They’re documented. They’re reasonable. And yet, somehow, every PR review becomes a discussion about the same issues: inconsistent naming, mixed indentation, functions that are way too long, comments that explain how instead of why.
Sound familiar?
The problem isn’t that your team doesn’t care about conventions. They do. It’s that humans are terrible at remembering conventions while they’re coding. You’re focused on solving the problem, not mentally cross-referencing the style guide you read three months ago. So by the time the PR shows up for review, you’re stuck having the same conversation again. And again. And again.
This is where Claude Code becomes your co-reviewer. Instead of humans manually checking “did you follow the naming convention?” twenty times, Claude Code can read your conventions from your documentation, scan the PR, and flag deviations. Automatically. Consistently. Every time. It’s like having a meticulous code review assistant who never gets tired or forgets a rule.
In this article, we’ll walk through how to encode your team conventions in a way Claude Code can understand, how to set up automated convention checking, and how to evolve those conventions based on what you actually learn from code review discussions. Let’s build a smarter PR review workflow.
Why Conventions Matter (And Why They’re Hard to Enforce)
Conventions aren’t rules. A missing semicolon won’t break your code. Mixed indentation won’t crash production. Inconsistent variable naming won’t cause a bug (well, usually). But conventions do something powerful: they reduce cognitive load.
When your entire codebase follows the same patterns, any developer can read any file and immediately understand the structure. Variable names are predictable. Function signatures follow a pattern. Comments explain trade-offs, not obvious logic. New developers onboard faster. Junior developers need less mentorship to be productive. Your entire team communicates through shared patterns rather than having to explain intent constantly.
The problem is enforcement. Code linters can catch syntax issues. Type checkers can catch type errors. But they can’t catch intent violations. They can’t tell you “this function should be smaller” or “this comment explains implementation details that should be obvious from the code.”
Only humans can see those issues. But humans are slow and tired and get frustrated explaining the same thing over and over. There’s a specific friction point: reviewers become gatekeepers of style, which slows down development and creates tension. Developers become frustrated that they’re told to change things that “work fine.” Both sides are right, but there’s no good path forward.
Claude Code bridges that gap. It can read your convention documentation and check if your PR actually follows it. Not as a replacement for human review—as a first pass that saves time. The human reviewer can focus on architecture, logic, and business value. Claude handles the mechanical checks.
Step 1: Document Your Conventions
You already have conventions. Maybe they’re written down, maybe they’re just “things everyone knows.” Claude Code needs them to be explicit so it can actually check them.
Let’s start by building a CONVENTIONS.md file in your repo. This is where your team documents the rules:
# Team Code Conventions
## Naming Conventions
### Variables
- Use **camelCase** for variables and parameters
- Boolean variables start with **is**, **has**, or **can**
- Constants use **SCREAMING_SNAKE_CASE**
### Functions
- Use **camelCase** for function names
- Start with a verb: `getUserData`, `validateEmail`, `computeTotal`
- Never use abbreviations: `getCurrentUser` not `getCurUser`
### Files and Directories
- Files are **lowercase-with-dashes**: `user-service.ts`, `email-validator.ts`
- Directories are **lowercase**: `services/`, `utils/`
## Function Design
### Function Length
- Aim for functions under 50 lines
- If a function is over 100 lines, strongly consider breaking it up
- Exception: auto-generated files (migrations, etc)
### Function Parameters
- Maximum 4 parameters. If you need more, use an options object
- Required parameters come first, optional parameters last
- Options objects should use camelCase keys
## Comments and Documentation
### When to Comment
- Explain **why**, not **what**
- If the code doesn't make sense without explanation, break it up instead
- Comments should justify design decisions
### When NOT to Comment
- Don't explain obvious logic: `i++` doesn't need a comment
- Don't repeat the code: `const name = user.name; // set the name`
### JSDoc/TSDoc
- Every exported function must have JSDoc
- Include @param, @returns, @throws for public APIs
This is concrete, explicit, and Claude Code can actually understand it.
To find your actual conventions, look at what your reviewers spend time discussing. What patterns do developers consistently apply? What do you push back on when someone deviates? That’s your real convention set, not aspirational ones.
Step 2: Create a Convention Checker with Claude Code
Now that you have conventions documented, Claude Code can check them automatically. You’ll create a PR review script that reads your CONVENTIONS.md, analyzes the PR changes, and flags deviations with suggestions.
The checker integrates with your PR workflow. Before merge, it runs and provides feedback on convention violations. The key insight: it’s not just pattern matching. Claude understands the intent behind conventions and can provide intelligent feedback about why something matters.
Here’s the core pattern:
// pr-conventions-checker.ts
const client = new Anthropic();
async function checkConventions(prNumber: string) {
// Get PR diff
const diff = execSync(`gh pr diff ${prNumber}`).toString();
// Read your conventions
const conventions = fs.readFileSync("CONVENTIONS.md", "utf-8");
// Ask Claude to check
const response = await client.messages.create({
model: "claude-3-5-sonnet-20241022",
max_tokens: 1500,
messages: [
{
role: "user",
content: `Review this PR diff against these team conventions.
CONVENTIONS:
${conventions}
PR DIFF:
${diff}
Check for convention violations and explain each one with:
1. Which convention was violated
2. Where in the code (file/line)
3. What should change
4. Why this matters to our team
Format as JSON for automated parsing.`,
},
],
});
// Parse and report violations
const text =
response.content[0].type === "text" ? response.content[0].text : "";
const violations = JSON.parse(text);
// Post as PR comment
if (violations.length > 0) {
const comment = formatViolations(violations);
execSync(`gh pr comment ${prNumber} --body "${comment}"`);
}
}
function formatViolations(violations: any[]) {
let report = "## 🔍 Convention Review\n\n";
violations.forEach((v) => {
report += `### ${v.convention}\n`;
report += `**Location**: ${v.file} (line ${v.line})\n`;
report += `**Issue**: ${v.description}\n`;
report += `**Fix**: ${v.suggestion}\n\n`;
});
return report;
}
checkConventions(process.argv[2]);
This approach is much more sophisticated than simple pattern matching. Claude understands intent. It can tell you “this function name violates the ‘start with verb’ convention because it uses a noun instead.” It can suggest fixes. It can explain why the convention matters.
Understanding Convention Enforcement in Practice
The real power of automated convention checking isn’t catching every violation. It’s creating feedback loops that help your team develop good habits. When a developer sees consistent, clear feedback about convention violations, they start internalizing the patterns. They run the checker locally before pushing. They learn faster. They become advocates for conventions themselves.
This is psychological change. At first, developers might resist automated checking—it feels like a micromanager. But when they see that the checker is helping them write better code, faster, and that code review becomes less about style and more about substance, they come around. The checker becomes a learning tool.
The key is making the feedback constructive. Don’t just say “naming violation.” Explain: “This function mixes camelCase and snake_case in parameters, which breaks our convention that all functions use camelCase for consistency. This helps new developers understand our codebase faster.” Explain the why, and people buy in.
Evolving Conventions Based on Real Data
Conventions should evolve based on what you actually learn from code reviews. If you notice every PR violates a particular convention, maybe the convention isn’t clear, or maybe it’s wrong. If you notice teams consistently work around a convention, it’s a signal.
Track metrics: Which conventions are violated most often? Which violations do reviewers spend the most time discussing? Which violations actually cause bugs or maintenance issues? Use this data to evolve.
You might notice that your “functions under 50 lines” convention is violated constantly in data processing modules where complex business logic justifies longer functions. Maybe you need a conditional rule: 50 lines for typical functions, 100 for data processing. Or maybe you need to teach better abstraction techniques. The data guides the decision.
The Psychology of Convention Adoption
Interestingly, automated convention checking creates a positive feedback loop in team culture. When engineers see that the system is fair and consistent—that the same rules apply to everyone—they start respecting the rules more. There’s no ambiguity. The checker didn’t reject your PR because it’s you; it rejected it because the code genuinely violates conventions.
This is different from human review where developers sometimes worry about bias or favoritism. An automated system is impartial. That impartiality builds trust. It also removes the social friction from enforcement. You’re not having a human conversation about whether you did it right. The system has spoken clearly.
Over time, conventions become invisible infrastructure. New developers run the checker, understand the feedback, adjust their code, and move on. They’re not frustrated because the checker explains why each rule matters. They’re not offended because there’s no human judgment. The system is just there, helping them write code that fits the team’s standards.
Building Institutional Knowledge Through Conventions
When you document and enforce conventions, you’re building institutional knowledge that survives team changes. A senior engineer who carries tribal knowledge in their head is valuable, but fragile. If they move to another project, that knowledge goes with them.
But documented conventions are different. They’re checked automatically. New developers inherit them immediately. They’re not negotiable—everyone learns the same patterns. This creates a culture where experience is cumulative rather than distributed.
This is especially valuable in growing organizations. As you hire more engineers, you could either hope they absorb conventions through osmosis, or you could enforce them through tooling. Enforcement scales infinitely. Osmosis doesn’t.
Uncovering Your Hidden Conventions
Most teams don’t explicitly document what they’re already enforcing implicitly. Here’s how to surface your actual conventions through pattern analysis and team feedback:
The most effective way to discover your team’s real conventions is to look at what code reviewers spend time discussing. Every time a reviewer asks someone to change something stylistic, that’s a convention signal. If multiple reviewers independently ask for the same changes across different PRs, that’s definitely a convention worth documenting. Rather than inventing conventions from scratch, you’re making explicit what your team already believes and practices.
Look for patterns in your existing codebase. Do all files have a header comment? Do functions consistently put parameters in a particular order? Do error messages follow a pattern? Do test files mirror the structure of source files? These aren’t accidents—they’re patterns your team has converged on. Documenting these existing patterns is much easier than trying to enforce new conventions.
Conduct a quick team survey: “What would a perfect PR look like to you?” Ask each engineer individually, then compare answers. The overlap is your real convention set. You’ll likely find surprising alignment on things you never formally discussed but everyone just “knew” somehow. That osmotic knowledge is exactly what you want to formalize and make explicit.
Advanced: Contextual Conventions
Not all code is the same. Database migrations have different style requirements than business logic. Generated code shouldn’t follow the same conventions as hand-written code. Test code can be more verbose than production code. Smart convention checking is contextual.
You can build this into your convention system:
# Team Code Conventions
## Default Conventions
[all your normal rules]
## Exceptions and Context-Specific Rules
### Database Migrations
- Functions can exceed 100 lines (schema changes are inherently complex)
- Comments should document _why_ the migration was needed (business context)
- No external function calls (migrations must be deterministic)
### Generated Code
- Skip naming convention checks
- Skip documentation requirements (generated code is implementation detail)
- Do check for any manual modifications post-generation
### Tests
- Allowed to be more verbose than production code
- Mocking can create long setup blocks—that's acceptable
- Comments explaining _why_ a test exists are encouraged
Claude Code can understand this context. When checking a migration file, it applies different rules. When it sees a comment at the top of a file saying “GENERATED – DO NOT EDIT,” it skips style checks. This flexibility prevents conventions from becoming cargo cult rules that developers resent.
Measuring Convention Enforcement Success
Track metrics: How many convention violations appear in PRs over time? Does the number decrease as teams internalize patterns? How much time do reviewers save by not having to discuss style? How fast do new developers become productive?
The best metric is velocity. Teams with strong, enforced conventions move faster because they spend less time in review cycles. Code is more readable, so bugs surface faster. Onboarding is quicker. The entire system feels smoother.
But also track developer satisfaction. Do engineers feel like conventions are helping them or hindering them? Convention enforcement should feel like guidance, not punishment. If it feels punitive, adjust the approach. Make feedback more constructive. Maybe reduce strictness in certain areas. The goal is convention adoption, not compliance. Conduct brief team surveys quarterly: “Are our conventions helping or hurting?” Let data guide evolution.
The Long Game: When Conventions Become Invisible
The ultimate success is when developers stop thinking about conventions. They write code that naturally follows the patterns because the patterns are intuitive, because they’ve internalized them, because it feels wrong to deviate. At that point, conventions stop being rules and become culture. They’re just “how we work here.”
This takes time. Most teams reach this state after 6-12 months of consistent enforcement and positive feedback. But once you reach it, the benefits are enormous. Code review cycles shorten. Bugs decrease. Onboarding accelerates. Team cohesion improves because shared patterns create shared understanding.
Scaling Conventions Across Multiple Teams
Once you’ve mastered conventions within a single team, the next challenge is scaling them across multiple teams with different specializations. Different teams have different needs. The backend team cares about API contracts and database patterns. The frontend team cares about component structure and performance. The DevOps team cares about infrastructure consistency. A one-size-fits-all convention system creates friction because it doesn’t account for these legitimate differences.
The solution is a hierarchical convention system: shared base conventions that apply to everyone, plus team-specific conventions that extend and specialize the base. This maintains organizational alignment—everyone follows core security, naming, and documentation principles—while respecting team autonomy.
For example, you might have base conventions that require all exported functions to have JSDoc comments. But the frontend team extends that with specific requirements about documenting component props and return types. The backend team extends it with specific requirements about documenting API contracts and error codes. Both teams follow the base convention while specializing it for their context.
Implementing this with Claude Code requires a slightly more sophisticated convention checker that understands contexts and extends rules. When Claude checks a PR, it loads both the base conventions and the team-specific conventions. It applies base rules universally and team rules contextually. This flexibility prevents conventions from feeling like arbitrary restrictions.
Teaching Through Conventions: The Educational Dimension
One often-overlooked benefit of convention enforcement is its educational value. Every convention violation is a teaching moment. Claude Code explains why the convention exists and what to do instead. Developers learn the team’s patterns through concrete feedback on their code, which is much more effective than reading documentation.
New developers particularly benefit. Their first PRs might have many convention violations. Instead of a senior engineer spending hours explaining the conventions in a review meeting, Claude Code provides immediate, specific feedback. The new developer adjusts their code, submits again, and learns faster. This accelerates onboarding significantly.
Create a convention documentation that doesn’t just state rules but explains the reasoning behind each rule. “We use camelCase for variables because it’s consistent with JavaScript conventions and helps new developers recognize variables at a glance.” “We limit functions to 50 lines because it makes code easier to understand, test, and refactor.” “We require JSDoc on exports because it helps consumers of your code understand its contract without reading the implementation.”
This “why behind the rule” makes conventions feel less arbitrary and more like collective wisdom. Developers buy in more readily when they understand the reasoning. Claude Code can reference these explanations in its feedback: “This function is 95 lines, and we limit to 50 lines because longer functions are harder to understand and test. Can you break this into smaller pieces?”
Real-World Success: From Chaos to Consistency
Consider inheriting a codebase with no documented conventions. Code is written seventeen different ways. Functions range from five lines to 500 lines. Variable names are inconsistent. Comments explain obvious logic. Tests are sparse and poorly organized. Reviews take forever.
You decide to implement convention enforcement. Here’s how:
Week 1-2: Discover implicit conventions by analyzing review comments from recent PRs and interviewing senior engineers. Create a first draft of CONVENTIONS.md documenting existing patterns.
Week 3: Set up the Claude Code checker in advisory mode. It reports violations but doesn’t block PRs. Do a team presentation explaining conventions and why they matter.
Week 4-6: Violations steadily decrease as developers adjust to feedback. You get feedback on conventions that feel wrong and adjust them. Maybe your function length limit is too strict for certain domains, so you create context-specific rules.
Week 7+: Violations continue decreasing. By week 10, most PRs pass convention checks. Developers have internalized patterns. Code review cycles shorten noticeably.
Month 6: Measure impact. PR review time dropped 30%. Onboarding new developers takes 25% less time. Bug escape rate improved because code is more readable. Developer satisfaction improved.
This transformation doesn’t happen because of enforcement—it happens because consistency creates value that everyone appreciates once they experience it. The enforcement is just the mechanism to bootstrap that consistency.
Common Pitfalls and How to Avoid Them
Pitfall 1: Too many conventions too quickly
Teams get excited and document everything. Developers become frustrated—it feels like a micromanager.
Fix: Start with 5-10 core conventions. Expand based on actual violations and pain points, not theory.
Pitfall 2: Unenforced conventions
Conventions are documented but never checked. They become “nice to haves” everyone ignores.
Fix: Implement checking immediately after documenting conventions. The sooner you start enforcing, the easier conformance becomes.
Pitfall 3: Conventions that don’t match reality
You create conventions based on what you think good code looks like, but your team consistently works differently.
Fix: Ground conventions in existing practice. Use data to discover what your team actually does, then document that.
Integration with Existing Review Processes
Claude Code’s convention checker doesn’t replace human code review—it augments it. Use it to handle mechanical checks so human reviewers can focus on architecture, logic, and business value. This creates better division of labor.
Structure your review process like this: Claude Code checks conventions automatically. If violations are found, the PR author fixes them and resubmits. Once conventions pass, human review focuses on substance. This keeps review cycles fast while maintaining code quality.
Some teams even make convention compliance a prerequisite for human review. “Please address Claude’s convention feedback before requesting review from humans.” This saves human reviewers from seeing obvious issues and lets them focus on genuine architectural concerns.
Conclusion: Building Convention Culture
Convention enforcement is about building a culture where consistency is valued, where new developers learn patterns quickly, where code review focuses on substance rather than style, where development velocity increases because cognitive load decreases.
Start with documenting your actual conventions. Implement automated checking. Make the feedback constructive and educational. Evolve based on what you learn. Over time, conventions become invisible—just how you do things here.
The economics are compelling: teams with strong, enforced conventions move faster. The investment in documentation and automation pays for itself within weeks through reduced review time and accelerated onboarding.
-iNet