Three Laptops, One Repo: Stopping Repeated Decision Re-Explanations

This article explains how a small team of three developers, each working on a separate laptop against a single shared repository, stopped repeatedly re-explaining their technical decisions. The answer is to codify decisions as executable, reviewable artifacts in the repository itself—using architecture decision records (ADRs), automated checks, and a living style guide—so the context is always attached to the code and never lost in chat history.

The Problem: Context Lost in Transit

When three people work on one repo, each laptop holds a slightly different mental model. One developer knows why the build script uses a specific flag; another knows why the API returns a 204 instead of a 200; the third knows why the database index is composite. Every time a new task touches one of these areas, someone has to re-explain the reasoning. That re-explanation is not just a time sink—it is a source of inconsistency. A decision explained verbally on a Tuesday may be forgotten by Friday, and a new pull request may silently reverse it.

The core issue is that explanations live in ephemeral channels (chat, video calls, hallway conversations) while the code lives in a permanent, shared artifact. The fix is to move the explanations into the repo itself, in a form that is both human-readable and machine-enforceable.

Architecture Decision Records (ADRs)

The first and most direct tool is the Architecture Decision Record. An ADR is a short markdown file that captures a single decision: the context, the decision, and the consequences. The format is deliberately lightweight so that writing one feels like writing a commit message, not a design doc.

For the three-laptop scenario, the team agreed that any change that affects a public interface, a build step, a dependency, or a data schema must include an ADR. The ADR lives in a docs/adr/ directory in the same repo, with a filename like 0007-use-204-for-delete.md. The file contains:

• Status: Proposed, Accepted, Deprecated, or Superseded.
• Context: What problem was being solved, and what constraints were present.
• Decision: What was chosen, and what alternatives were considered.
• Consequences: What becomes easier and harder because of the decision.

Because the ADR is in the repo, it is versioned. When someone asks “why does this endpoint return 204?”, the answer is a grep away. The team no longer needs to reconstruct the reasoning from memory; they read the document that was written when the decision was fresh.

Automated Checks: Enforcing the Decision

An ADR only helps if people actually read it. To make that happen, the team added automated checks that fail the build when a decision is violated. For example, they wrote a small script that scans the codebase for the forbidden pattern of returning a 200 on a DELETE request, and it runs in CI. The script is part of the repo, so it runs on every laptop and on the shared server.

This is the key step: the decision is not just documented, it is enforced by code. When a developer on laptop B tries to introduce a change that contradicts an accepted ADR, the build fails with a message that points to the relevant ADR file. The developer does not need to ask anyone; the repo itself explains the rule and the reasoning.

Concrete examples of such checks include:

• A linter rule that flags the use of a deprecated library.
• A unit test that asserts the API response code for a specific endpoint.
• A script that verifies the database migration file matches the schema in the ADR.
• A CI step that runs npm audit and fails if a known vulnerable dependency is introduced.

These checks turn “please remember not to do X” into “the build will not pass if you do X.” The reasoning is still in the ADR, but the friction of a failed build is what makes the team pay attention.

Living Style Guide and Code Comments

Not every decision is architectural. Many are about style: naming conventions, file structure, error-handling patterns. For those, the team maintains a living style guide in the repo—a markdown file that is updated whenever a new pattern is agreed upon. Unlike a static wiki, this guide is reviewed in pull requests, so changes are discussed in the same place as code changes.

Code comments also play a role, but they are used sparingly. The rule is: a comment should explain why, not what. For example, instead of // set timeout to 30 seconds, they write // 30s timeout to match the upstream SLA (see ADR-0012). This connects the code to the decision record, so a reader can follow the trail.

How to Choose What to Document

Not every decision needs an ADR. The team uses a simple test: if a decision is likely to be questioned by someone who has not been in the conversation, it gets documented. They also document decisions that are hard to reverse or that affect multiple parts of the codebase. Routine choices—like which variable name to use—are left to the style guide.

A practical heuristic is to write an ADR when you find yourself about to explain a decision in a pull request comment. Instead of typing a long explanation, you write a short ADR and link to it. This keeps the review focused on the code, not on re-litigating past choices.

Common Problems and Pitfalls

The most common failure is that ADRs become stale. A decision made six months ago may no longer be valid, but the ADR is still marked as “Accepted.” To avoid this, the team reviews ADRs during sprint planning or when a related area of code changes. They also use a status field: when a decision is superseded, the old ADR is marked “Superseded” and a new one is created. The old file stays for history, but the status makes it clear it is no longer active.

Another pitfall is writing ADRs that are too vague. “We decided to use a microservice architecture” is useless without context. A good ADR includes the specific trade-offs that were considered, such as “we chose a monolith for the first version because the team is small and the domain is simple, but we kept the module boundaries so a split is possible later.”

Finally, automated checks can be overdone. If every minor style preference is enforced with a custom script, the build becomes slow and brittle. The team limits automated checks to decisions that are costly to reverse or that have caused bugs in the past.

Comparing Alternatives: Wiki, Chat, and Onboarding Docs

A wiki is a common alternative, but it lives outside the repo and often drifts from the code. A chat channel is useful for discussion but is not searchable in a way that connects to the code. Onboarding documents help new team members but are rarely updated after the first month.

The advantage of putting decisions in the repo is that they are versioned, reviewed, and co-located with the code. When a developer checks out a commit from three months ago, they also get the ADRs that were valid at that time. This is impossible with a wiki or chat.

Frequently Asked Questions

Q: What if a decision is too complex to explain in a short ADR?
A: Write the short ADR anyway, and link to a longer design document if needed. The ADR should capture the essence; the link provides depth. If the decision is so complex that it cannot be summarized, that is a sign that the decision may need to be broken into smaller parts.

Q: How do we get the team to actually write ADRs?
A: Make it part of the definition of done. A pull request that changes a public interface or a dependency is not merged until an ADR is attached. The reviewer checks for the ADR, just like they check for tests.

Q: What about decisions that are made in a meeting and not by a single person?
A: The ADR should reflect the outcome of the meeting, not the individual opinions. The “Context” section can note that the decision was made in a team discussion. The important thing is that the outcome is recorded, not who argued for it.

Q: Can we use ADRs for non-technical decisions, like project management choices?
A: Yes, but it is usually better to keep ADRs focused on technical decisions that affect the codebase. Project management decisions are better in a separate document, because they have a different audience and a different lifecycle.

Q: What if we have a large existing codebase with many undocumented decisions?
A: Start with the most recent decisions and the ones that are most likely to be questioned. You do not need to document everything retroactively. As you touch an area of code, write an ADR for any decision that you find yourself explaining.

Q: How does this help with onboarding a new developer?
A: A new developer can read the ADR directory to get a history of the project’s evolution. They can also run the automated checks to see what rules are enforced. This is much faster than trying to extract the same information from chat logs.

Related

• Best Multiplayer Switch Games: Top Picks
• Nomad vs Kubernetes: Which One to Use
• Contractor Credential Check: What It Must Return