Back to Blog

Write Specs Before PRs to Avoid Redesign Debates in Code Review

Fazm Team··2 min read
code-reviewspecsengineering-processpull-requestsarchitecture

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.

More on This Topic

Fazm is an open source macOS AI agent. Open source on GitHub.

Related Posts