Most teams do not have an architecture documentation problem.
They have an architecture drift problem.
The code changes. The docs lag. The ADRs stop halfway through a migration. And then somebody suggests solving it by letting an AI system install the repo, run whatever it wants, and summarize the result.
That is the wrong trust model.
The more useful question is this:
How do you generate architecture docs from a live repository without turning your documentation pipeline into a build agent?
Accord Book's current documentation subsystem answers that question with a stricter set of boundaries.
The design principle
AI can help propose architecture truth. It should not become an unbounded execution surface, and it should not silently publish what becomes authoritative.
That principle shows up in three places across the repo:
- read-only repository analysis,
- bounded evidence and staged synthesis,
- Git PR review with merge as publish.
Start with a safer analysis boundary
Accord Book's documentation architecture is explicit about what it does not do during generation.
It does not:
- execute customer code,
- install dependencies,
- run tests,
- run builds,
- or infer architecture from runtime side effects.
Instead, the pipeline uses a local bare mirror + ephemeral detached worktree at the repository's default-branch tip and reads the repo as data.
That matters for two reasons:
1. Security
A documentation pipeline should not become a privileged code-execution path into customer repositories.
2. Reproducibility
A useful architecture draft should map to a specific analyzed snapshot, not to a fuzzy local machine state that may never ship.
Bounded evidence beats repo-wide dumping
A common failure mode in AI documentation tooling is pretending that "more repo context" automatically means "better output."
Usually it means more noise.
Accord Book's generation flow is narrower:
- walk the repository,
- classify files,
- build bounded evidence packs,
- synthesize section-level drafts,
- reconcile and canonicalize,
- then open a reviewable PR.
That is not just a cost optimization. It is a quality architecture.
The system shapes evidence before the model writes prose.
The document shape matters too
Accord Book's Git-backed documentation flow is not aiming for one giant AI-generated summary blob.
It targets established shapes:
- arc42 for architecture sections under
.q_context/arc42/ - ADR markdown under
.q_context/adrs/
This is an underrated design choice.
Known document shapes make review easier, reduce output drift, and help both humans and agents consume the result more predictably.
The publication boundary is where trust is won
This is the part that matters most.
Accord Book's .q_context workflow is Git-backed, and the repo docs are explicit about the publication rule:
- AI proposes changes on a branch,
- Accord Book opens a pull request,
- humans review,
- merge = publish,
- and agents consume only the merged default branch.
That is a much better trust contract than silently mutating a private draft store and hoping everyone remembers what is authoritative.
What the workflow looks like
| Stage | What happens |
|---|---|
| Read-only snapshot | Analyze a fixed default-branch commit, not a mutable working tree |
| Index + classify | Build a bounded view of architecture-relevant files |
| Evidence pack | Assemble section-specific excerpts instead of dumping the whole repo |
| Draft synthesis | Generate structured section drafts |
| Merge + canonicalize | Reconcile outputs and repair source-path references |
| PR review | Open a GitHub PR for human review |
| Publish | Merge to the default branch; merged .q_context becomes authoritative |
Why this is better than a build-agent model
| Question | Build-agent approach | Accord Book-style docs generation |
|---|---|---|
| What does it trust? | Repo can execute cleanly | Repo can be inspected safely |
| What is the failure mode? | Setup/runtime breaks the pipeline | Analysis can still produce bounded partial output |
| What becomes truth? | Easy to blur draft and publish | Merge on default branch is explicit |
| What do agents read? | Risk of draft/runtime confusion | Merged .q_context only |
Why this matters beyond documentation
The interesting thing about this design is that it mirrors the broader Accord Book product stance.
Across conflict detection, digests, and docs generation, the pattern is similar:
- gather evidence,
- keep provenance,
- propose carefully,
- and leave important publication decisions to humans.
That is not anti-automation.
It is automation designed for systems where trust matters.
Closing thought
If your documentation pipeline needs to behave like a CI runner before it can explain your system, you may have given it the wrong job.
A better documentation system reads the repository safely, builds bounded evidence, proposes structured updates, and lets humans decide what becomes published truth.
That is the shape Accord Book is converging on with .q_context, arc42, ADRs, and PR-based publication.
If you want the shorter governance version, pair this with AI Proposes, Humans Publish.