Communication Is the API

I'm pairing with an AI agent on a platform API change. We modify a schema, update the tests, regenerate the Software Development Kit (SDK). The pull request (PR) description documents everything. The change ships.

Two hours later, a developer on the client team pings me. Their build is broken. Type errors everywhere. They dig through commit messages, trace the SDK diff, and eventually piece together what changed. The information was there—in a PR description, in a commit message, in the generated types. But it wasn't communicated.

That distinction—between documentation and communication—is what this post is about. Documentation is passive. It sits there. Communication is active. It reaches the right person, at the right time, in the right format. And when your teams scale beyond a single room, communication becomes infrastructure. It needs the same rigor we apply to our APIs, our tests, and our deployments.

Daniel Coyle opens The Culture Code with a story that makes this visceral. Designer Peter Skillman ran a challenge: build the tallest structure you can from spaghetti, tape, string, and a marshmallow. Teams of MBA students averaged under ten inches. Teams of kindergarteners averaged twenty-six. The MBAs spent their time strategizing, negotiating roles, managing status—figuring out who was in charge before doing any actual building. The kindergarteners stood close together, barely talked, and just started trying things. Rapid iteration. No status management. When something fell, they adjusted and kept going.

Coyle's conclusion: group performance depends less on individual skill than on how people interact. The MBAs had more knowledge and more strategy. The kindergarteners had better communication—not in words, but in the signals that said we are in this together, keep going, try again. That's the difference between documentation and communication in a nutshell. The MBAs documented a plan. The kindergarteners communicated through action.

The Sand Hill Unicorns Problem

In Measure What Matters, John Doerr uses a football team to explain how Objectives and Key Results (OKRs) work—and how they fail. He imagines himself as the general manager of the Sand Hill Unicorns. His objective: make money for the owner. His key results: win the Super Bowl and fill the stands to at least 90 percent capacity.

He cascades those key results down. The head coach's objective becomes "win the Super Bowl," with measurable key results: a passing attack of at least 300 yards per game, a defense allowing fewer than 17 points, and top-3 punt return coverage. Clear. Specific. The coach cascades again—the offensive coordinator targets a 65 percent completion rate and less than one interception per game.

Meanwhile, the Senior Vice President (SVP) of marketing's key results are "upgrade branding," "improve media coverage," and "revitalize promotions." Unmeasurable. Vague. But even if she fixed those, Doerr argues the whole approach is flawed. Rigid cascading creates four problems—and every one of them is a communication failure.

Doerr's fix isn't better cascading. It's transparency. Google publishes every employee's OKRs for the entire organization to see. Teams self-align because they can see where the organization is headed. Communication happens through visibility, not chain of command. As Doerr puts it: "Precisely because OKRs are transparent, they can be shared without cascading them in lockstep."

My favorite example from the book: a physical therapist attends a sports medicine conference and learns about a new injury prevention regimen. On her own, she creates an OKR to implement it. Her objective doesn't align with her direct manager's OKRs, but it aligns with the GM's overarching objective—if the top players stay healthy, the team's chances of winning the Super Bowl soar. That only works when the general manager's objectives are visible. Transparency enables self-alignment.

Conway's Law tells us that organizations design systems that mirror their communication structures. If your communication is one-dimensional—top down, cascade only—your systems will be one-dimensional too. This connects directly to how we think about cross-functional team structure: the communication structure IS the organizational structure.

Two Seconds, Twenty People, Zero Margin

A Formula 1 (F1) pit stop: the car arrives, roughly 20 crew members execute in under two seconds, the car leaves. Every role is defined. Every signal is pre-agreed. There is no room for "I assumed you meant..."

Research on F1 teams reveals something that maps directly to how engineering teams operate under different conditions. Under low time pressure, informal advice networks are sufficient for cross-unit coordination. People share information, ask questions, coordinate through normal channels. But under high time pressure—race conditions, production incidents, release deadlines—those informal networks break down. The research shows that under pressure, informal communication only works when it's embedded in formal workflow structures. Without structured protocols, cross-unit communication fails exactly when it matters most.

Post-race debriefs in NASCAR and F1 reveal another tension that engineering teams know well: balancing safety and reliability against performance. "We could have been faster, but was it safe?" is the same question as "We could ship this sooner, but is it backward compatible?" Structured communication is how teams navigate that tension without it becoming a war between speed and stability.

The takeaway: Slack and sprint demos work fine for normal work. But breaking changes, incidents, and cross-team API modifications need structured communication protocols. "We mentioned it in Slack" is the engineering equivalent of shouting over the engine noise.

Version Your Promises

Semantic versioning (SemVer) is the most successful communication protocol in software, and most teams think of it as an engineering convention. It's not. It's a communication system disguised as a numbering scheme.

Every version number answers one question for every consumer: Will this break me? That's communication. And it creates accountability—a major version bump forces the provider to evaluate the cost-benefit ratio of introducing a breaking change. As the SemVer spec puts it: incompatible API changes require incrementing the major version. That's not just a rule. It's a promise.

We apply this philosophy beyond version numbers. In our platform API, when we deprecate an endpoint, we don't remove it. We override it with an HTTP 410 Gone response. We monitor traffic for 2–4 weeks. We remove only when traffic reaches zero. The 410 response IS the communication—any client hitting the deprecated endpoint gets an explicit signal instead of a confusing 404. Grace periods are a form of respect for your consumers.

Lead with the "So What"

When I pair with my AI agents, the pattern that consistently works is: lead with the executive summary—what changed, why it matters, what action is needed—and allow the reader to dig into details on demand. Different audiences need different depths.

This applies everywhere: PR descriptions, incident communications, architecture decision records, Slack messages about breaking changes. The 500-line PR description with no summary is the engineering equivalent of a 90-minute meeting that could have been an email—everyone approves it, nobody read it, and the breaking change ships to staging unnoticed.

In our codebase, we enforce this through what we call the exhaustive compliance review. Before declaring any task complete, the author runs review passes against every relevant coding standard. We added a communication pass: "Does this change affect any other team? Did I communicate with structure?" That pass forces the author to think about downstream impact before saying "done."

Communication Modes Match the Moment

Matthew Skelton and Manuel Pais define three interaction modes in Team Topologies. I find them useful as a communication framework, not just an organizational one. Each mode implies a different communication style, and using the wrong mode for the situation causes friction.

The mistake I see teams make: defaulting to Collaboration mode for everything. Collaboration is expensive—it requires both teams' attention simultaneously. It's the right mode for discovery, for designing a new API contract together. But an API that's permanently in Collaboration mode is an API that hasn't matured into a product. The Team API concept captures this: every team should document what they provide, how to consume it, what's changing, and how to reach them. A README for your team, not just your code.

Cockpit Communication for Engineering Teams

In 1977, two Boeing 747s collided on the runway in Tenerife, killing 583 people. The investigation revealed a communication failure: the co-pilot recognized the captain was making a dangerous decision but didn't challenge it directly. Hierarchy killed communication, and communication killed people.

The aviation industry's response was Crew Resource Management (CRM)—structured communication training that flattens hierarchy in critical moments. Research on cockpit crews shows that high-performing captains demonstrate "metacognitively explicit communication"—they state their mental model out loud so others can correct it. The same three principles translate directly to engineering teams.

The "I see, I think, I recommend" pattern is worth practicing until it becomes habitual. Unstructured concerns ("this feels risky") get lost. Structured assertions ("I see X, I think Y, I recommend Z") get acted on. The format itself communicates confidence and competence, regardless of the speaker's seniority.

But structured formats alone aren't enough. Coyle's research in The Culture Code shows that structured communication only works when people feel safe enough to use it. He identifies what he calls belonging cues—small, consistent behaviors that signal three things: energy (investing in the exchange), individualization (treating people as uniquely valued), and future orientation (signaling the relationship will continue). Teams saturated with these cues spend less energy on status management and more on the actual work. The message they transmit: you are safe here, we share a future.

Coyle illustrates this with what he calls the "bad apple" experiment. A researcher planted a negative actor in groups—someone who was aggressive, lazy, or pessimistic. Group performance dropped 30 to 40 percent almost every time. Except in groups with a person Coyle calls "Jonathan," who counteracted the negativity not by confronting it, but by signaling safety: leaning in, making eye contact, asking questions, drawing quieter members into the conversation. One person's communication behavior protected the entire group. In engineering terms, the senior engineer who responds to a junior's concern with "good catch, tell me more" is doing Jonathan's work.

This connects to what Coyle calls the vulnerability loop: one person shares a weakness or uncertainty, the other person reciprocates, and trust deepens. The loop only starts when someone goes first—and that someone is usually the leader. A tech lead who says "I'm not sure this migration path is right—what am I missing?" creates permission for the whole team to flag risks. A tech lead who projects certainty on every decision gets silent compliance and surprise failures. Coyle saw this pattern everywhere he studied, from Navy SEAL teams carrying a 250-pound log (six people, constant communication, zero room for ego) to Pixar's Braintrust meetings where directors present unfinished work specifically to invite critique.

CRM gave aviation the format for safe communication. Coyle's research explains the environment that makes the format work. You need both. A team with structured assertion but no psychological safety will produce people who know the format but never use it. A team with psychological safety but no structure will produce people who care deeply but communicate vaguely.

Rules as Communication Infrastructure

We use Cursor rules to encode team standards into our development environment. These rules function as codified communication—they encode decisions once so they don't need to be re-communicated every time someone touches the code.

When we identified the communication gap described at the start of this post—changes being documented but not communicated—we didn't write a wiki page about it. We wrote a rule. The cross-team communication rule lives in both our platform and client codebases, tailored to each side's responsibilities. On the platform side, it enforces the breaking changes protocol and executive summary pattern. On the client side, it enforces reading the upstream PR before fixing type errors and communicating impact across apps.

This is standing on the shoulders of giants applied to communication: codify what works, make it discoverable, and iterate on it when it doesn't.

Seven Principles for Communication-First Teams

Here's what I've landed on after building teams across multiple codebases and working with both human and AI collaborators. Each of these is something we practice and enforce through our rules—they're not aspirational. They're operational.

Take a Baseline

Communication infrastructure, like all infrastructure, is never finished. You can't improve what you don't measure. Before applying any of this, take a baseline on how your teams communicate today. Where do things get lost between teams? How many breaking changes shipped without warning in the last quarter? How many meetings could have been an executive summary?

Pick one principle and try it for two sprints. Maybe it's adding the executive summary layer to your PR descriptions. Maybe it's adopting the "I see, I think, I recommend" format for cross-team concerns. Measure whether it reduces miscommunication. If it does, codify it. If it doesn't, iterate. That's kaizen—permanent learning, permanent improvement.