We Didn’t “Align” — We Argued (and Shipped a Better System)
Source: Dev.to
Background
Software projects rarely fail because someone can’t write code.
In this project we were building a product with a fairly standard stack:
- Frontend: React + TypeScript
- Backend: REST API
- Multiple engineers working in parallel
- Tight deadlines (the fun kind)
Everything looked fine… until it didn’t.
The Problem
The frontend assumed fields that the backend hadn’t implemented yet.
Nothing was broken enough to stop development, but bugs kept appearing late in the cycle.
The Turning Point
Someone asked the dangerous question:
“Why don’t we just define the API first?”
The question triggered a debate:
- A backend engineer worried about losing flexibility
- A frontend engineer worried about slowing down
- Another voice saying “we can just fix it later” (classic)
Instead of pretending we agreed, we argued it out. That was the turning point.
What We Did
Define OpenAPI specs early
- Generated TypeScript types for the frontend from the specs
- Treated breaking API changes as actual breaking changes, not “oops”
Enforce discipline
- Required review of the spec PRs
- Accepted that changes would take slightly longer upfront
Trade‑offs
- Backend flexibility: lost some freedom to “just rename stuff”
- Process overhead: specs required discipline and review, making some PRs longer than a novel
- Speed: changes took a bit longer initially
What We Gained
- Predictable frontend types
- Fewer late‑stage surprises
- Much calmer pull‑request reviews
Human Impact
The biggest win wasn’t technical—it was human.
Instead of asking “Why is this field missing?” we started asking “Should this field even exist?”
Specs forced us to:
- Name things clearly
- Argue about responsibility
- Make decisions visible
Design reviews became real design reviews, not post‑mortems.
Challenges Faced
- Over‑specifying early and having to loosen things later
- One spec PR was longer than some novels
- Accidentally breaking the API and forgetting to regenerate types (yes, that hurt)
Collaboration doesn’t remove mistakes, but it surfaces them early.
Lessons Learned
- Collaboration surfaces disagreement early.
- Silence is more dangerous than conflict.
- Tools don’t fix teams—they expose them.
- Clear contracts reduce ego‑driven decisions.
- Senior engineers don’t avoid friction; they engage with it.
Good collaboration isn’t about being nice. When teams stop optimizing for speed today and start optimizing for trust tomorrow, the codebase follows. And yes—sometimes that starts with an argument.