Architecture Documentation Pack

We built the Architecture Documentation Pack because we were tired of asking "Why did we choose Postgres over DynamoDB?" and getting a shrug. We were tired of joining codebases where the "why" lived in a Slack thread from three years ago, or worse, in the head of an engineer who had already left.

Code tells you what the system does. Architecture Decision Records (ADRs) tell you why it does it. When you lose the rationale, you lose the ability to refactor safely. You end up with a house of cards where touching one service requires a prayer and a full regression suite.

This pack gives your team a version-controlled workflow for capturing those decisions as code. No more wiki rot. No more tribal knowledge. Just MADR-compliant templates, C4 diagrams as DSL, and CI/CD enforcement that blocks architectural drift before it hits main.

The Graveyard of Slack Decisions

You know the pattern. You see a migration script that hardcodes a region, or a query that uses SELECT * on a massive table. You ask a senior engineer, and they say, "I don't know, it was like this when I got here."

That's not just a missing comment. That's a missing decision record. When architecture decisions live in buried Jira tickets, random Slack channels, or PDFs nobody reads, you don't just lose knowledge. You lose the context. You start making the same mistakes twice. You rebuild the same wheel because the original blueprint vanished.

We've seen teams spend weeks untangling a dependency graph only to find the original constraint was documented in a Confluence page that got archived last quarter. The codebase becomes a graveyard of good intentions, where every line of code is a mystery waiting to be solved.

Pair this with a technical writing workflow to ensure your prose matches your code, but remember: writing is only half the battle. You need a system that enforces documentation standards automatically.

The Real Cost of Tribal Knowledge

This isn't just annoying; it's expensive. Every time a new hire has to reverse-engineer a design choice, that's billable hours burned on discovery instead of delivery. Every time a decision is repeated without context, you risk introducing subtle incompatibilities.

The cost compounds. You get technical debt, but worse, you get architectural drift. Your system evolves organically, without a central nervous system. Eventually, the codebase becomes a monolith in all but name, where no single person understands the whole picture.

We've seen incidents caused by teams ignoring documented constraints because the records weren't version-controlled. When the decision record isn't in the repo, it's not part of the code review process. It's easy to bypass. It's easy to forget.

The bus factor drops to one. If the architect gets sick, the team stops. If the architect leaves, the team guesses. And guessing is how you ship security vulnerabilities, compliance failures, and performance regressions.

How Top Teams Lock Down Rationale

Leading engineering organizations don't leave architecture to chance. A 2025 AWS Architecture blog post ^[3] highlights that Architecture Decision Records (ADRs) are critical for documenting and communicating important process and architecture decisions. The post emphasizes that ADRs help teams maintain a clear history of why choices were made, ensuring that future engineers can understand the context without needing to ask the original author.

Microsoft's Azure Well-Architected Framework reinforces this, advising teams to start the ADR at the onset of a workload and maintain it throughout the lifespan ^[1]. An ADR should be started for brownfield workloads, and if the data ... Read more about maintaining ADRs in the Azure documentation ^[1].

Imagine a fintech platform scaling from 50 to 500 endpoints. Without a disciplined record-keeping workflow, every API contract change, every database migration, and every auth strategy shift becomes a potential point of failure. When the team adopts a structured approach, they stop guessing. They link decisions to code. They enforce standards.

The C4 model helps here. By defining Context, Container, Component, and Code levels, you create a shared vocabulary. Diagrams become code. They live in the repo. They get reviewed. They get updated.

Use this alongside a developer onboarding docs pack so new hires can read the architecture history on day one. Onboarding becomes a guided tour, not a scavenger hunt.

Architecture as Version-Controlled Code

With the Architecture Documentation Pack installed, your repo becomes the source of truth.

ADRs are no longer an afterthought. You get MADR-compliant templates that force you to capture context, alternatives, and consequences. Every decision gets a status: Proposed, Accepted, Deprecated, Superseded. This lifecycle ensures decisions are reviewed and revisited as the system evolves.

C4 diagrams move from static PNGs in a wiki to living DSL files in your repo. Structurizr models update alongside your code. You can embed diagrams directly in markdown, so the documentation stays in sync with the implementation.

CI/CD catches violations. If you merge a change that breaks a documented architectural constraint, the pipeline blocks. You don't need a meeting to enforce standards; the linter does it. Scripts validate ADR headers and DSL syntax. The workflow is automated, repeatable, and auditable.

What's in the Architecture Documentation Pack

• skill.md — Orchestrator skill that defines the Architecture Documentation workflow, instructs the agent on when to use ADRs vs C4 diagrams, and references all templates, scripts, validators, and examples.
• templates/adr.mdr — Production-grade MADR (Markdown Architecture Decision Record) template with required metadata, status lifecycle, and consequence tracking.
• templates/c4-workspace.dsl — Real Structurizr DSL template for C4 modeling, demonstrating workspace, model, and view definitions with auto-layout and dynamic views.
• references/adr-guide.md — Canonical knowledge on ADRs: MADR structure, status meanings (Proposed, Accepted, Deprecated, Superseded), CI/CD integration strategies, and governance rules.
• references/c4-structurizr.md — Canonical knowledge on the C4 model levels (Context, Container, Component, Code), Structurizr DSL syntax, embedding diagrams, and diagram-as-code best practices.
• scripts/scaffold-adr.sh — Executable bash script that scaffolds a new ADR file with the MADR template, auto-increments the sequence number, and fills in metadata.
• scripts/validate-adr.sh — Validator script that checks ADR files for required MADR headers and valid status values. Exits non-zero on failure to enforce documentation standards in CI.
• scripts/validate-c4.sh — Validator script that checks Structurizr DSL files for structural integrity (workspace/model/views blocks, balanced braces). Exits non-zero on syntax errors.
• examples/adr-001-database-choice.md — Worked example of a completed ADR documenting a database technology choice, showing proper context, alternatives, and consequences.
• examples/workspace.dsl — Worked example of a C4 workspace DSL defining a realistic microservice architecture with containers, components, and dynamic views.
• .github/workflows/arch-docs-ci.yml — CI/CD pipeline configuration that runs the ADR and C4 validators on pull requests, blocking merges that violate architecture documentation standards.

Install and Ship

Stop guessing. Start documenting.

Upgrade to Pro to install.