Architecture Documentation & Implementation Guidance

The architect hands off a design that others must build and operate. Documentation is what makes that handoff succeed.

What the Architecture Document Covers

• Components: the pieces of the system and how they fit together
• Data flow: input -> processing -> output -> feedback
• Chosen patterns: the design patterns selected (and, implicitly, the alternatives not selected)
• **The *why* behind each decision**: the tradeoffs each choice served

Implementation Guidance Is a Separate, Actionable Layer

Documentation describes the design; implementation guidance is what lets a team build it without re-deriving it. That guidance includes:

• Pinned model versions
• Prompt/Skill structure
• Integration protocols
• Retrieval configuration
• Guardrails
• Eval/monitoring setup

Why Document Rationale, Not Just Decisions

Recording the rationale behind a decision -- not merely the decision -- lets future maintainers understand which constraints that choice served, so they can adapt safely as requirements evolve. A decision log without rationale looks arbitrary six months later and invites maintainers to unwind a choice without realizing what it was protecting against. Documenting decisions without their rationale is not sufficient: rationale is what preserves the tradeoffs for safe future iteration, and it is not something that becomes unnecessary just because the code currently works.

Documentation as the Handoff Enabler

Clear documentation, paired with concrete implementation guidance, is what makes the next lifecycle phase -- handoff -- succeed. An implementation team should be able to build from the documentation without needing to reconstruct the design decisions from scratch.