The real reason PRDs and ADRs don't survive contact with your team

joaosmoura — Mon, 15 Jun 2026 13:09:56 +0000

It's not a culture problem. It's a timing problem.

I've led engineering teams at four of Brazil's largest financial institutions — environments where decision traceability isn't optional. Audits require architectural rationale. Incidents demand post-mortems that explain not just what broke, but why the system was designed the way it was. Onboarding a new engineer means they need to understand decisions made months before they joined.

High-stakes environments. High documentation standards.

And even there, the same pattern kept appearing: the documentation existed, but the decisions didn't survive.

The timing trap

Here's what actually happens in most teams.

A developer picks up a ticket. They open their editor — or increasingly, they open Claude Code, Cursor, or Copilot — and they start building. The context is fresh, the problem is clear, and forward momentum feels like progress.

Three weeks later, a tech lead asks: "Why did we introduce this new dependency?" The developer who built it has moved on to the next sprint. The Slack thread where the decision was made has scrolled past. The ADR that should have been written is still a blank template in a folder nobody opens.

This isn't a discipline problem. It's a friction-at-the-wrong-moment problem.

Most documentation systems ask for the artifact after the decision. By then, the cognitive context has evaporated. What gets written is a rationalization, not a record.

Why AI coding tools made this worse before making it better

The arrival of Claude Code, Cursor, and similar tools accelerated this pattern significantly. A developer can now go from "here's the ticket" to "here's a working prototype" in an hour. The speed is genuinely impressive. The documentation gap it creates is genuinely dangerous.

In a team of one, that's manageable. In a team of eight, working across five services, with two new engineers onboarding — it's how you accumulate architectural debt that takes quarters to unwind.

In high-compliance environments, the cost of this gap is particularly visible — but the pattern exists everywhere. The irony is that AI coding tools are also the best possible enforcement point. They sit exactly where the work begins.

The upstream hypothesis

The insight behind upstream is simple: documentation should be enforced upstream of the code, not downstream of it.

Not in the PR review. Not in the sprint retrospective. Not in the quarterly architecture review. At the moment a developer opens a feature branch and types their first prompt.

That's the moment the context is fullest. That's when the cost of writing a PRD is lowest. That's when the ADR actually captures a decision, not a post-hoc justification.

How it works technically

upstream installs a UserPromptSubmit hook into Claude Code — one of the lifecycle hooks the tool exposes for exactly this kind of integration.

When a developer opens a feature branch and submits their first prompt in a Claude Code session, the hook fires and injects a context message:

UPSTREAM: feature detected without PRD. Invoke upstream-guard before continuing.

Claude then runs the upstream-guard skill, which does four things:

Classifies the work — feature, bug, fix, chore, or incident. Bug fixes and chores bypass the check automatically; only feature work triggers enforcement.
Checks for a PRD — by filename or content match in the configured docs directory.
Checks for an ADR — but only if the PRD describes architectural decisions (new external dependency, database migration, API contract change, infrastructure change, auth change). Not every feature needs an ADR.
Releases to development once the required docs exist.

A few design decisions worth noting:

The hook fires at most once per session. This is intentional. It's tracked via a PPID-based cache file in /tmp. Subsequent prompts in the same session are silent. The goal is to interrupt once, not to create a tollgate on every interaction.

Bypass branches are first-class citizens. fix/, hotfix/, chore/, docs/ prefixes skip the check entirely. The system is designed to get out of the way when it shouldn't be in the way.

PRDs and ADRs can be created four ways: imported from an existing document, generated through a short interview (the most common path), auto-drafted from git context, or linked to an external tool (Confluence, Google Docs via OAuth/PKCE). The barrier to compliance is intentionally low.

Skips are logged, not blocked. If a developer genuinely doesn't need a PRD for a particular piece of work, they can skip with a justification. The skip is logged to SKIPS.md and a PR snippet is generated. Transparency, not bureaucracy.

What gets committed to the repo

.claude/
  hooks/
    upstream-check.sh           # UserPromptSubmit hook
  plugins/upstream/
    skills/
      upstream-guard.md         # orchestration skill
      upstream-prd.md           # PRD creation skill
      upstream-adr.md           # ADR creation skill
    templates/
      PRD.md
      ADR.md
upstream.config.yaml

The entire plugin lives in .claude/, which Claude Code picks up automatically. A platform engineer runs upstream init once in the repo. The team gets it on their next git pull. No global install required on individual machines.

The organizational argument

There's a framing from Will Larson's An Elegant Puzzle that I keep returning to: systems that rely on individual discipline fail at scale, while systems that encode discipline into process survive it.

PRD and ADR culture almost always relies on individual discipline — a tech lead who remembers to ask, a developer who takes the time to write. upstream encodes that discipline into the toolchain itself. The enforcement happens whether or not the tech lead is in the room.

For teams adopting AI coding tools, this matters more than it might seem. The productivity gains from Claude Code are real. But productivity without process creates a specific kind of technical debt: fast, well-written code that nobody can explain, modify, or audit six months later.

upstream is an attempt to make the documentation as fast as the code.

Getting started

npm install -g upstream-docs
cd your-repo
upstream init

The init wizard configures upstream.config.yaml, scaffolds .claude/, and optionally sets up a CODEOWNERS guardian for the config file.

The repo is at github.com/joaos-moura/upstream-docs. Feedback, issues, and contributions welcome.

João Moura is a Head of Engineering with experience leading technical teams at XP Inc., Itaú, BTG Pactual, B3, and Syngenta Digital. He builds at the intersection of engineering leadership and system design.

DEV Community: joaosmoura