Documentation, handoff and the solution lifecycle

What you’ll be able to do

• Document a Claude architecture so another team can operate, debug and change it: prompts, models, tools, data flows, evals and limits
• Provide implementation guidance that makes the safe path the easy path for builders
• Plan a handoff with exit criteria, runbooks and a named operating owner
• Run each lifecycle phase (discovery, design, handoff, monitoring, iteration) with entry and exit criteria

What you need to know

What a Claude system’s documentation must contain

Conventional architecture docs (context diagram, components, deployments) are necessary but not enough. Much of a Claude system's behavior lives in artifacts that conventional docs ignore, and those are exactly what the next team needs when something goes wrong:

• Data flows and trust boundaries. What data enters, which components and providers see it, what's logged, retention, residency, and who can access each store.
• Prompts and templates, in source control with versions and owners, plus the reason behind non-obvious rules.
• Model choices per step, the pinned versions, and the eval evidence for each choice.
• Tools and permissions: every tool or MCP server the system can use, what it can do, the credentials and scopes it runs with, and why each is needed.
• Guardrails: which rules are enforced in code and where, and which are prompt-level only.
• Evaluation suite: the datasets, metrics, thresholds and how to run it. This is the definition of "working".
• Known limitations and failure modes, stated plainly: input types not tested, languages with weaker results, cases that always escalate.
• Cost model: where tokens go, expected volume, and the levers (caching, tiering, batching) already in use.
• Decision records with their revisit triggers (lesson 6.2).

Keep documentation next to the code and change it in the same review as the change it describes. Documentation that lives in a separate wiki drifts from the system within a few releases.

Implementation guidance for builders

When other teams build on your architecture, written guidance should make the safe path the easy one. Provide a reference implementation or template repository with the guardrails already wired in, shared libraries for the risky parts (auth, logging with redaction, output validation), clear statements of what is non-negotiable and why, and worked examples. For teams using Claude Code, a project CLAUDE.md carrying conventions and constraints, and shared Skills for recurring procedures, put the guidance where the builders' tools will read it. Guidance that says "remember to validate outputs" gets forgotten; a library that validates by default doesn't.

Handoff is a phase with exit criteria

Handoff fails when it's a meeting rather than a process. Define the criteria up front: the receiving team has run the eval suite themselves, deployed a change through the pipeline, worked through the runbooks in a drill, and has the access and on-call coverage it needs. Runbooks should cover the incidents a Claude system actually has, with the diagnostic order spelled out. For a quality drop, for example: check whether inputs or retrieved sources changed (re-index, document refresh, upstream data), then prompt and template versions, then model version, then the integration code. For cost spikes: token usage by step, cache read rates, retry loops. For dependency outages: the degraded mode and communications. A named operating owner signs off; until then, the build team still holds the pager.

The lifecycle doesn’t end at go-live

• Discovery exits with testable, owned requirements and a tested riskiest assumption (6.1).
• Design exits with decisions recorded, reviewed by security and compliance, and an eval suite that defines acceptance.
• Build and handoff exit when acceptance criteria pass on real data and the operating team meets the handoff criteria.
• Monitoring is continuous: quality on sampled traffic, latency, cost per task, escalation and override rates, safety signals. Watch for drift: content changes in the knowledge base, shifts in what users ask, upstream data changes.
• Iteration runs through change control: every prompt, retrieval, tool or model change passes the regression eval before release, with a rollback path. Feedback (6.3) feeds both the backlog and the eval set.

Plan for model lifecycle explicitly. Models are released and later deprecated on the provider's schedule, so keep the eval suite ready to qualify a replacement, track deprecation announcements, and budget migration effort before it's urgent. A system whose prompts were tuned heavily to one model's quirks is a bigger migration; that's worth noting in the docs too.

Key concept

Document the AI-specific artifacts (prompts, model versions, tools and permissions, guardrails, eval suite, known limits), hand off only against explicit exit criteria with runbooks and a named owner, and keep monitoring and gated iteration running for the life of the system.

Lifecycle questions often describe a system that worked at launch and degraded later, or a team that inherited one it can't safely change. The strong answer adds the missing lifecycle mechanism (eval-gated change control, runbooks, monitoring, documented limits) rather than a one-off fix.

Practice scenario

Build exercise — Assemble a handoff pack and run a drill

Advanced · 60 min

What you’ll learn

• Inventorying the AI-specific artifacts a new owner needs
• Writing runbooks with a diagnostic order for common incidents
• Defining and testing handoff exit criteria

1. For a real or sample Claude system, inventory every artifact in the documentation list above and mark where each lives today and whether it’s in version control.

   • Why: Prompts, evals and permissions are the parts most often missing from handoffs, and they define the system’s behavior.
   • You should see: At least one artifact that exists only in a notebook, a chat thread or someone’s head.

2. Write runbooks for three incidents (quality drop, cost spike, dependency outage), each with symptoms, a diagnostic order, the commands or dashboards to check, and the escalation path.

   • Why: Under pressure, teams go for the most familiar fix; a written order sends them to the most likely cause first.
   • You should see: A quality-drop runbook that checks inputs and retrieval before prompts and models.

3. Define handoff exit criteria and test them with a drill: someone from the receiving team ships a small prompt change through the pipeline with the regression eval, then works one runbook end to end.

   • Why: A handoff is complete when the new owner can change and fix the system unaided, not when the slides are presented.
   • You should see: Gaps found in the drill (missing access, unclear steps) fixed before the build team leaves.

Exam traps

Handing off a system with architecture diagrams but no runbooks or eval suite

Diagrams don’t tell the new owner how to tell whether it’s working or what to do when it isn’t. Include evals and runbooks.

Documenting prompts and model choices outside version control

Prompts and model versions define behavior. They need versions, owners, review and a history, like code.

Treating go-live as the end of the project

Content, users and models change after launch. Monitoring and gated iteration are lifecycle phases with owners.

Shipping prompt or model changes after launch without a regression evaluation

Every behavior change can fix one case and break others. Run the eval suite before release and keep a rollback path.

Leaving known limitations out of the documentation to avoid alarming the new owners

Undocumented limits become production incidents. State them plainly so owners can route around them.

Waiting for a model deprecation notice before planning the migration

Keep the eval suite ready to qualify replacements and budget migration effort ahead of the deadline.

Sources

• Claude Developer Platform Docs: models, deprecations and Claude Code
• Anthropic
• Anthropic, Claude Certified Architect – Professional Exam Guide v1.0 (July 2026)