Prerequisites

This guide assumes:

  • Familiarity with Conway’s Law. Read What Is Conway’s Law? first if “communication structure shapes system structure” sounds new.
  • A local clone of the repository you want to analyze. The diagnosis below is a git query.
  • A POSIX shell with awk, sort, uniq, and cut. Standard on macOS and Linux.
  • Visibility into the org chart. You need to map author emails to teams.

Rank the congestion candidates

Start by looking at the slowest, most contentious modules. Files with commits from many different authors over the last quarter signal congestion.

Run this from the repo root to rank files by distinct-author count over the last three months:

git log --since='3 months ago' --pretty=format:'%ae' --name-only \
  | awk '/@/{a=$0;next} NF{print a"\t"$0}' \
  | sort -u | cut -f2 | sort | uniq -c | sort -rn | head -20

Expected output: a numbered list of file paths, highest distinct-author count at the top. The leading number on each line is the distinct-author count. The first ten paths are your congestion candidates. Example:

  14 src/api/router.ts
  12 src/auth/middleware.ts
  11 db/schema.sql
   9 config/feature-flags.yaml
   7 src/billing/invoice.ts

Adjust the time window with --since if three months is wrong for your codebase. Use --since='6 months ago' for a slow-moving codebase where quarterly churn is light. Use --since='6 weeks ago' for a fast-moving startup where the org changed within the last quarter and you want a recent signal.

Cross-reference with the org chart

Cross-reference those files with the org chart. If a single module is edited by authors from four different teams, expect merge conflicts, review delays, and slow shipping. That is Conway’s Law at work: the code reflects the expensive communication path between teams.

Ask whether the module needs four teams editing it, or whether they edit it because they cannot wait for one team to ship. If it is the latter, the real problem is organizational, not technical. The module is congested because no one owns it clearly.

Build the commit-to-organization map

Document which teams touch which files. This commit-to-organization map is the diagnosis tool. The gaps between team responsibilities and code boundaries are where friction lives.

A simple two-column list works: file path on the left, comma-separated list of teams that edited it on the right. Highlight any row with three or more teams. Example:

src/api/router.ts          payments, identity, growth, platform   ← congested
src/auth/middleware.ts     identity, platform                      ok
db/schema.sql              payments, identity, data, platform     ← congested
config/feature-flags.yaml  growth, platform                        ok

The highlighted rows are where Conway’s Law is operating against you.

Verify

You’re done diagnosing when every congested module on the map has either a named single owner or a planned ownership change. The diagnosis itself does not fix anything; it tells you which organizational changes will pay off.

Troubleshooting

The command returns no output

The repository has fewer than three months of history, or no commits have author emails. Verify with git log --since='3 months ago' | head. Adjust the time window if needed.

Distinct-author counts look low across the board

You are looking at a small team (fewer than ten engineers) where everyone edits everything. Conway’s Law applies less cleanly here. Look at PR review wait times by reviewer instead; the bottleneck is people, not files.

You see misalignment but cannot point to specific costs

Measure three things over a single sprint:

  • Median PR review wait time, grouped by reviewing team.
  • Merge-conflict frequency on the top ten most-edited files.
  • Calendar minutes per engineer tagged “sync,” “alignment,” or “coordination.”

When you can attach hours per quarter to misalignment, the case for the reorganization writes itself.

Where to go next

References