Write Specs Before PRs to Avoid Redesign Debates in Code Review
Write Specs Before PRs to Avoid Redesign Debates in Code Review
You open a pull request. Two hundred lines of clean code. Tests pass. You feel good about it. Then a senior engineer comments: "Have we considered doing this differently?" And suddenly your PR turns into a three-day architecture discussion.
This happens because code review is the wrong place for design decisions. By the time code exists, changing direction costs hours of rewriting. Everyone knows this, but the discussion happens anyway because no one had a chance to weigh in earlier.
The Fix: A Short Spec Before Any Non-Trivial PR
Start writing a short spec before any non-trivial PR. Not a formal design doc - just a quick outline covering:
- The approach - what you are planning to build and why
- Data flow - how information moves through the system
- What you are NOT doing - scope boundaries that prevent scope creep
- Trade-offs - what you considered and rejected
This takes about 10 minutes. The redesign debates still happen, but they happen on a document where changing course costs 10 minutes instead of 10 hours.
Why This Works
When someone reads your spec and says "what about approach X instead?" - you can update three paragraphs and move on. Compare that to rewriting 200 lines of code, updating tests, rebasing, and re-requesting review.
The spec also forces you to think through your approach before writing code. Half the time, writing the spec reveals problems you would have discovered mid-implementation anyway.
What a Good Spec Looks Like
Keep it under a page. A few paragraphs in a markdown file or a comment on the ticket works fine. The goal is not documentation - it is getting alignment before investing time in implementation.
Teams that adopt this pattern report fewer multi-day PR review cycles and less frustration on both sides of the review. The debates do not go away, they just happen when they are cheap.
- AI Verification Paradox in Code Review
- Managing Code from Non-Engineers with AI
- Claude Code Architecture Handoff Pattern
Fazm is an open source macOS AI agent. Open source on GitHub.