"Why does this batch job perform a full table wipe-and-reload every night?" When taking over maintenance of a client system, this type of question often leaves developers at a loss for words. Reading the code reveals what it does. But the "why"—why full reload instead of incremental updates, why this database was chosen, why this specific process is asynchronous—is documented nowhere. The individuals who made those calls have already moved on, leaving no one to explain the rationale. Fear of breaking something prevents anyone from modifying it, preserving an opaque design simply because no one understands why it was built that way. Taking over systems built by other vendors in custom development almost inevitably brings you up against this wall.
The root issue is that architectural decisions are not recorded. Code captures results, but it does not record why that result was chosen or which alternatives were discarded. ADRs (Architecture Decision Records) provide a lightweight solution to fill this void. As summarized in InfoQ's June 2026 article How Lightweight ADRs and Architectural Advice Forums Can Support Architectural Decisions (InfoQ), pairing lightweight ADRs with advice forums preserves decisions without bogging down workflows with heavy architecture documents. In this article, we explain how to apply this practice to custom development to create maintainable, inheritable architectures.
Why code alone cannot convey architecture
Code describes the current state, but design choices involve multiple layers of context that never surface in code.
First is discarded alternatives. When comparing options A, B, and C to choose B, only B remains in the code. Later developers asking "why not A?" cannot tell whether A was evaluated and rejected or never considered at all. A well-meaning engineer might refactor the system toward A, only to run into the exact constraints that led to its initial rejection—such as incompatibilities with the client's legacy systems.
Second is the shelf life of assumptions. An assumption like "full data reloads are fine because data volume is small" becomes invalid as data scales. If that assumption is never documented, teams cannot distinguish between obsolete choices ready for modernization and active constraints that must still be honored.
Third is accountability. In custom development, clients will inevitably ask why an architecture was configured in a certain way. Without records of why decisions were made and who signed off on them, fulfilling professional accountability becomes impossible.
ADRs fill these gaps using short, one-page records for each decision. Instead of writing exhaustive specifications up front, teams create a concise record whenever a decision occurs. This is what makes them lightweight.
Lightweight ADR basics — one record per decision
An ADR captures a single architectural decision inside a short document with standard headings. The exact format is secondary; as long as it captures context, decision, and consequences, it serves its purpose. The standard practice is storing them alongside code in the repository under a numbered sequence like docs/adr/0001-xxx.md, keeping them under version control.
# ADR-0007: 在庫同期を差分更新ではなく夜間の全件洗い替えにする
- ステータス: 承認済み（2026-06-20）
- 決定者: 開発リード / 顧客側システム担当
## 文脈（なぜ今これを決めるか）
顧客の基幹システムは差分APIを提供しておらず、深夜に当日分の
全在庫CSVが1ファイル出力される。リアルタイム連携の要件はない。
データ量は現状5万件、当面10万件以下の見込み。
## 決定
夜間バッチで全件を洗い替えする。差分更新は実装しない。
## 結果（この決定の代償と前提）
- 利点: 実装が単純で、CSV側の欠落・重複に強い（毎回作り直すため）
- 欠点: 日中の在庫はリアルタイムに反映されない（要件上は許容）
- 前提: データ量が数十万件を超えたら全件洗い替えは見直す
- 却下案: 差分更新（A）= 差分APIが無く、CSV比較が複雑になるため見送りThe critical rule is to always document rejected alternatives and underlying assumptions. Having this single record allows you to answer the earlier question—"why a full wipe-and-reload?"—instantaneously. It captures both the initial constraint that no incremental API existed and the expiration condition to revisit the design once data volume grows. When inventory expands six months later, the team has an explicit baseline: "This core assumption is no longer valid, so we re-evaluate."
Limit documentation to decisions that are significant, difficult to reverse, and non-obvious. Documenting every routine implementation detail leads to bureaucratic decay. Restricting ADRs to decisions whose rationale will inevitably be questioned later—such as datastore selection, integration patterns, auth strategies, and async boundaries—is key to sustaining the practice.
Using advice forums to prevent delays without unilateral decisions
While an ADR records decisions, an architectural advice forum defines how decisions are reached. The essence of this mechanism, as described in the InfoQ article, is to keep decision-making decentralized while mandating stakeholder consultation prior to deciding. This operational model strikes a balance: avoiding the bottleneck of requiring a central architect's approval for everything while preventing isolated decisions that clash later.
In practice, the person making a decision solicits input beforehand from affected parties—fellow developers, operations teams, and client representatives—and documents the feedback received along with reasons for accepting or rejecting it in the ADR. While there is no obligation to follow every piece of advice, deciding without asking is prohibited. In custom development, including the client's internal technical leads among those consulted is particularly effective.
| Approach | Speed | Quality | Issues in custom development |
|---|---|---|---|
| Central architect approves all decisions | Slow (bottleneck) | High | Stalls if the lead departs |
| Individuals decide autonomously | Fast | Inconsistent | Later conflicts, misalignment with client |
| Advice forum + ADR | Fast | Stable | Requires building a consultation habit |
This philosophy of avoiding centralized authority while maintaining governance connects directly to other areas of systems operations. Much like replacing standing production access with auditable job execution discussed in our article on eliminating standing SSH access, or modeling AI agent permissions via delegation in our article on AI agent authentication and authorization, it represents a governance model designed to keep decentralized actions traceable and explainable.
Pitfalls when adopting it in client web development
An inventory management system for a logistics company whose maintenance we inherited (client name withheld) was a prime example of an architecture nobody understood. When the client requested real-time updates for the nightly inventory wipe-and-reload batch mentioned earlier, no one remembered the original constraint—that the ERP had no incremental API—and the team nearly promised real-time capabilities prematurely.
We began by auditing over a dozen high-impact, unexplained decisions in the existing system, retroactively drafting ADRs through codebase analysis and interviews with past stakeholders. Once the constraint regarding the lack of an incremental API was documented, we could clarify with the client that real-time updates required ERP-side modifications, successfully steering expectations toward a realistic compromise of near-real-time batch runs during business hours. From that point on, whenever a new architectural decision arose, we transitioned to collecting input with the client's technical staff and capturing decisions in ADRs. Rather than mounting an overwhelming documentation overhaul, we simply recorded forward-looking decisions one by one and filled in critical past decisions as needed.
The single most effective takeaway from this project was that ADRs should start with future decisions. Attempting to document past architecture retroactively leads to burnout from sheer volume. Start by recording upcoming decisions one at a time, only drafting retroactive records for historical decisions when modifying related components. This keeps overhead minimal while building a repository of rationales starting from the areas changing most frequently.
Another pitfall is treating ADRs as write-and-forget artifacts. When conditions change, past assumptions collapse. When that happens, update the record not by deleting it, but by marking it "superseded" and referencing the old ADR from the new one. Preserving this chain of decisions allows future teams to understand both when and why strategies shifted.
Where to begin
If there is even one architectural decision you cannot explain, adopting ADRs is worthwhile. You do not need a flawless template. A short Markdown file covering context, decision, rejected alternatives, and assumptions stored alongside code in docs/adr/ is all it takes to get started.
Begin by selecting a single decision your team is wrestling with right now and capturing it in an ADR. Before finalizing it, gather advice from affected stakeholders—including client leads—and document the reasons behind accepted or discarded options. Establishing this habit ensures that when questioned six months later or when assumptions shift, the rationale can be retrieved immediately.
If you are unable to safely modify an inherited system because its design intent is unknown, or if you want to eliminate reliance on institutional memory in maintenance, please contact GleamHub. We can help you document critical architectural decisions retroactively via ADRs and establish workflows to keep future decisions clear and inheritable.
