Where architecture decisions actually live: 190 popular repos, 10 with ADR files

Popular open-source projects write down why their code looks the way it does, but almost none of them use architecture decision records for it. Across 190 popular repos, we found decisions in pull request descriptions in 154 of them, in commit messages in 163, and in comments in central files in 135. At least 10 had ADR files: our detector found 9 and missed Airflow's.

An ADR (architecture decision record) is a short document, usually in a docs/adr/ folder, that records one decision: the context, what was decided and the consequences. The rest of this post looks at where popular projects write their decisions down when they don't use ADRs.

The numbers

We index decisions for every repo, meaning statements of the form "we chose X over Y because Z", pulled from wherever the repo keeps them. For the 190 public repos in our index with 500+ GitHub stars and a health score (leaving out our own two repos and a duplicate copy of FastAPI), we found 10,339 decisions in 187 repos. The table counts where they came from in two ways.

The "repos" column is the one to read. The "decisions" column is lumpy, because a single repo with an unusually chatty history can add hundreds, and the last row comes from an older version of our extractor that ran on a few repos and pulled far more per repo. The repo counts don't have that problem.

Composio has the most ADR decisions, 30 mined from its docs/decisions folder (about 9 unnumbered files), followed by openstatus with 9, and after that the counts drop off fast. Our detector missed Airflow, which keeps numbered ADR folders in six places, including dev/breeze/doc/adr and airflow-core, about 49 Markdown files in all.

Two decisions from requests

The first is a decision from requests, mined from a pull request: switch the character-detection dependency from the LGPL-licensed chardet to the MIT-licensed charset_normalizer. The PR body says why: "By including an LGPL'd module it is no longer clear if the resulting artefact must also be LGPL'd," and "By changing out this dependency for one under MIT we remove all license ambiguity." The context, the decision and the consequence are all there, in a PR instead of a file called 0007-switch-charset-library.md.

The second comes from a comment in requests' auth.py:

# "I want us to put a big-ol' comment on top of it that
# says that this behaviour is dumb but we need to preserve
# it because people are relying on it."
#    - Lukasa

That is a design decision (keep the old behaviour for compatibility) with its reason, written exactly where the next person to touch that code will see it. We think it does the job better than an ADR would, because nobody has to know the ADR exists.

Why ADRs don't get written

The reason looks mechanical. A pull request description is written at the moment the author knows the most about the change, in a box the workflow puts in front of them, and a reviewer reads it within hours. A commit message works the same way: it's required, it's right there, and someone reads it. A code comment sits on the line it explains.

An ADR asks for a separate file, in a separate folder, written at a separate time and read by nobody in particular. Each of those is a small extra cost, and small extra costs are the first thing to slip when a project is moving fast. So the decision still gets written down, in the place that costs nothing extra.

Some big projects also keep design records in a different repository altogether. React's RFCs, Python's PEPs and Rust's RFCs all live outside the main code repo. Our numbers only count what's inside the repo we indexed, so projects like these look emptier here than they are.

Where should you record architecture decisions?

If you want your team's decisions recorded, put the question where people already type:

1. Add a "Why" section to your pull request template. One line is enough: "Why this approach, and what did you rule out?" That is the ADR, written at the right moment.
2. Squash-merge with the PR body as the commit message, so the why also lands in git log, where it survives a move to another code host.
3. Comment the weird parts. If code looks wrong but is right, say why on that line, the way requests does, because those are the decisions people trip over.
4. Keep ADRs for the few cross-cutting decisions. Choosing a database, a framework or an API style affects the whole codebase and deserves its own page. Most teams make only a handful of those a year.

Decisions written in PRs and comments end up scattered, so finding "why do we do retries this way?" means searching three places. repowise init does that gathering: it reads ADR files, WHY: and DECISION: markers, commit messages, pull request bodies and comments on central files, and stores each decision with a verbatim quote and the files it governs.

repowise init                       # capture runs as part of indexing
repowise decision candidates        # mined decisions awaiting review
repowise decision confirm a1b2c3d4  # accept one; this is what makes it govern
repowise decision health            # stale and ungoverned hotspots

Mined decisions arrive as proposals. Only a person, or a committed ADR marked accepted, makes one govern. Your coding agent reads the list through the get_why tool, one of ten MCP tools: get_why(query="src/payments/processor.ts") returns what governs that file. Every public repo has a decisions page, and the decisions feature page shows the review flow.

A repowise decision page for a mined comment decision: context, decision, rationale quote, verified-quote badge and a governance scope linking it to modules and files

What these numbers can't tell you

• These are mined decisions, and they vary in weight. The extractor reads text and proposes decisions: some are big ("migrate to Pydantic v2 with a compatibility layer") and some are small ("remove an unnecessary import"). None of them has been confirmed by the project's maintainers, which is why our pages mark them "proposed".
• Our ADR detection looks for two formats (Nygard-style and MADR). An ADR in a different format, or in a wiki, may not be counted, and the detector missed Airflow's ADR folders entirely, so the true ADR count is at least 10.
• Capped clones undercount. For repos where we only indexed the last 500 to 2,000 commits, the commit-message and PR counts cover only that window.
• Squash-merge habits matter. Projects that merge with the PR body as the commit message get counted under both PRs and commits, and projects that use merge commits with empty messages show fewer.
• This is popular open source. A company codebase with a design review process may look completely different.

How we measured

The sample is every public repo in our index with 500+ GitHub stars and a health score on its latest index, minus our own two repos (repowise-dev/repowise and repowise-dev/claude-code-prompts) and tiangolo/fastapi, an older duplicate of fastapi/fastapi: 190 repos. For each one we called the public decisions endpoint (api.repowise.dev/snapshots/<id>/decisions) on 6 October 2026 and used its per-source counts. A repo counts under a source if at least one of its decisions came from there. Each decision is extracted from the source text and kept with a link to the commit, PR or file it came from. To reproduce the counts, call the same endpoint for any snapshot and group by source.