- Part II explores pairing ADRs with architecture fitness tests to ensure architectural integrity through CI/CD.
- Part III focuses on AI‑assisted discoverability and validation to surface relevant ADRs and detect drift early.
Together, these parts outline a path from static documentation toward architecture that reacts, informs, and evolves with the system.
→ Jump to the Practical Application
Introduction
Every long‑lived software system faces a growing gap between code reality and architectural reality. Code evolves daily through commits, refactors, and merges, while architecture often lingers in forgotten documents or outdated diagrams. Over time, this divergence creates friction — developers start re‑deciding what was already decided, reconstructing architectural intent from memory or chat logs.
This disconnect is not new. Since the 1990s, teams have tried to bridge it through architecture documentation with goals like:
- knowledge preservation and continuity
- communication and alignment
- onboarding and consistency
- maintenance and evolution
These goals remain valid, but early documentation standards were often too heavy and detached from day‑to‑day development. That’s why Architecture Decision Records (ADRs) gained traction: they promised a lightweight, version‑controlled way to capture architectural decisions alongside code.
A typical definition summarises their purpose:
“An Architecture Decision Record (ADR) is a lightweight document that records a significant architectural decision, including the context, the problem it solves, the options considered, the chosen solution, and its consequences. By maintaining a collection of ADRs, teams create a decision log that provides a shared understanding of the project’s history for new and existing members, helps in consistency and future troubleshooting, and facilitates asynchronous collaboration through version control systems like Git.”
Despite this simplicity, ADRs can still decay into forgotten text files — unless they are actively used. The rest of this series explores how to change that.
→ Jump to the Philosophy and Practice
The promise of ADRs — and their common failure
ADRs are praised for being simple and easy to maintain, but in most teams, they eventually lose their connection to real work. The documents exist — often well-written — yet they stop influencing daily decisions. They become historical artifacts instead of living guides.
This disconnect happens for predictable reasons:
- ADRs live far from the developer’s workflow.
- They require deliberate effort to find and read.
- Searching for “which ADR explains this pattern?” often feels slower than just re‑deciding.
When this happens, architectural documentation fails its purpose. ADRs should participate in the development loop — shaping choices, providing reasoning anchors, and keeping architectural intent visible when change occurs.
The question becomes clear:
How do we turn ADRs from passive documentation into active, living context?
The next section outlines the mindset and practical direction that guided our team toward an answer.
The philosophy behind answering the main question
Instead of creating yet another documentation process, our focus shifted to embedding architecture awareness directly into the developer workflow. The idea was to make architectural reasoning available at the same moment code decisions are made.
Architecture documentation doesn’t have to sit in a separate place or demand special attention. It can quietly surface when it’s most relevant — during a commit, a code review, or a CI pipeline run.
By moving from enforcement to integration, we aim to:
- Reduce cognitive load by surfacing ADRs automatically rather than requiring manual search.
- Encourage re‑use of reasoning instead of re‑inventing past solutions.
- Maintain architectural integrity by connecting reasoning to code changes.
- Keep decisions alive as evolving artifacts linked to real system evolution.
The principle guiding this is simple:
Architectural documentation should not require searching — it should find you when you need it.
This mindset became the foundation for our experiment: using a lightweight pre‑commit hook to bring ADRs closer to everyday work.
Translating philosophy into practice
Turning this principle into something tangible required starting small — solving the simplest piece of the problem first: visibility. We didn’t aim to automate architectural enforcement or validation right away; instead, we wanted to ensure that architectural reasoning could always be found where work happens.
This led to the creation of the ADR Scanner pre‑commit hook, a lightweight script that connects architectural documentation to the developer’s daily workflow.
The idea was straightforward:
- Keep the architectural decision records always visible and up‑to‑date inside the repository.
- Eliminate manual maintenance by automatically generating an index of ADRs.
- Help developers rediscover context when they make changes — without leaving their editor or terminal.
By introducing a minimal automation layer, we could close the gap between architectural intent and implementation. The next section walks through how the hook works in practice and what it enables for development teams.
Introducing the ADR Scanner pre‑commit hook
To bridge the gap between architectural intent and code, a simple automation was built: the ADR Scanner pre‑commit hook. It runs locally in developers’ environments and keeps architecture decision records visible without requiring additional effort.
The repository of the hook : https://github.com/entrofi/pre-commit-hooks
How it works
- Scans the ADR directory recursively for Markdown files.
- Extracts each file’s title and optional Decision section.
- Generates a Markdown index containing links to all ADRs, updating sections between defined markers in target files.
- Can update multiple target files in one run (for example, both
README.mdand a dedicated ADR index). - When run in summary mode, prints short decision summaries directly to the terminal, providing quick architectural context at commit time.
Why it matters
This simple automation ensures that architectural documentation remains discoverable and synchronized with code changes. Developers see decisions evolve alongside implementation, helping them reconnect with reasoning instead of rediscovering it.
Example configuration
repos:
- repo: https://github.com/entrofi/pre-commit-hooks
rev: v0.0.1
hooks:
- id: adr-scanner
args:
- "--src-dir=docs/architecture/architecture_decision_records"
- "--target-file=docs/architecture/architecture_decision_records/index.md"
- "--target-file=docs/index.md"
- "--marker-start=<!--adrlist-->"
- "--marker-end=<!--adrliststop-->"
- "--group-by=subdir"
- "--group-depth=1"
- "--group-heading-level=2"
- "--group-title-case=title"
- "--exclude=index.md"
- "--exclude=adr_template.md"
- "--include-decision-summary"
- id: adr-scanner
name: adr-scanner (summaries only)
stages: [ manual ]
args:
- "--src-dir=docs/architecture/architecture_decision_records"
- "--summarise"
- "--decision-summary-lines=all"
Example output
$ pre-commit run adr-scanner --all-files --hook-stage manual
adr-scanner (summaries only).............................................Failed
- hook id: adr-scanner
- exit code: 3
Decision summaries (all decisions):
- ✅ Platform Buyer Management – Exposure of the Service/Domain Level Data Objects from Network Level Components (REST) – ADR #01
_Disallow exposure of **any** service-layer objects._
REST APIs must always define **dedicated network-level DTOs** or representations.
- ✅ Platform Buyer Management – Module Package Structure – ADR #02
Adopt **Option 1** — a **strict per-module root package structure** under a shared global namespace.
The hook doesn’t enforce architecture — it makes it easier to stay aware of it.
Benefits in daily workflow
Adopting the ADR Scanner hook has subtle but meaningful effects on how teams work with architecture:
- Reduced context loss – decisions stay visible and relevant even as team members change or projects evolve.
- Smoother onboarding – new developers can see why the system looks the way it does without deep dives into historical documentation.
- Fewer repeated discussions – when reasoning is accessible, teams revisit decisions less often and focus on improving them.
- Lightweight maintenance – automation replaces the manual upkeep of architectural indexes.
By embedding awareness rather than enforcing compliance, the hook gently shifts team habits toward continuously maintaining architectural context.
Limitations and next steps
Like any focused tool, the ADR Scanner hook solves a specific part of the problem — visibility. It doesn’t yet provide cross-repo awareness, decision validation, or AI-assisted discovery.
Future iterations will explore:
- Pairing ADRs with architecture fitness tests to validate conformance in CI/CD.
- Introducing assistive commit-time suggestions to connect code changes with relevant ADRs.
- Leveraging semantic search and embeddings for smarter ADR discovery.
Each of these extensions aims to strengthen the same goal: making architectural reasoning findable, verifiable, and always in context.
Closing reflection — architecture as a living dialogue
Architecture documentation should not be a record of the past but a dialogue with the present. The ADR Scanner pre-commit hook is a small concrete step toward that — transforming ADRs from static files into part of the everyday rhythm of software development.
Ultimately, architecture isn’t only about diagrams or documents. It’s about the shared mental model that keeps a system coherent as it grows.