Architecture Documentation & Implementation Handoff.

Documenting a Claude-based architecture needs everything a traditional system diagram needs - components, data flow, integration points - plus a set of GENERAL artifacts that don't exist in non-AI systems and apply to ANY Claude-based architecture, regardless of what tooling built it: the eval suite that defines "working," the prompt/config versions that produced a given behavior, an ADR-style decision record, and a runbook for known failure modes. A handoff missing these lets the receiving team operate the system but not safely modify it.

A SEPARATE, narrower layer sits on top of that general package, and it is CONDITIONAL - it only applies when the build, or the running system itself, actually touches Claude Code or the Claude Agent SDK: the .claude directory (CLAUDE.md, .claude/rules/, settings.json, hooks, skills, commands, subagents) and Claude's own accumulated auto memory. This is Claude-Code-specific configuration - it governs how the coding tool behaves, and, when the production agent is itself built on the Agent SDK (which can load the same .claude/ sources at runtime), it can also shape the running system's behavior. Either way it's one component of a handoff, never the whole handoff package - a team that assembled its Claude-based system directly against the Messages API, with no Claude Code and no Agent SDK .claude/ loading, may have no .claude directory at all, and the general artifacts (eval suite, version history, ADR, runbook) are still required regardless.

Because model behavior can shift across releases and prompts drift under maintenance, handoff documentation for an agentic system is not a one-time snapshot the way a traditional architecture diagram often is. It has to specify how the build team keeps the documented behavior in sync with a system that keeps changing underneath it - who updates what, and when a model version bump or a prompt edit requires re-validation.

The eval suite is executable documentation of intended behavior, and it's a general artifact every Claude-based handoff needs. A build team without it can operate the system but cannot verify whether a later change - a prompt edit, a model version bump - regressed output quality, since traditional unit tests don't catch output-quality regressions the way an eval does.

Systematic prompt management is Anthropic's own named mechanism for prompt/config version history, not just a nice-to-have - and it's general, not Claude-Code-specific. Anthropic's own enterprise LLMOps guidance names it as a best practice on par with monitoring and security: version control, a central repository teams collaborate through, documentation of why each prompt was designed the way it was, and a testing framework to validate changes across scenarios. That is the concrete deliverable behind "hand over the prompt history," not a vague instruction, and it applies whether the system is built on Claude Code, the Agent SDK, or directly against the Messages API.

Architecture Decision Records capture what was rejected, not just what was chosen - general practice an AI-system handoff should still adopt. ADRs are a general software-architecture practice (not an Anthropic-published format) increasingly adapted for AI-system handoffs so a build team inherits the rationale for why a workflow pattern was chosen over an autonomous agent, and what alternatives were rejected, so a rejected approach doesn't get re-proposed from scratch after staff turnover. Treat the exact ADR template as something to verify against your own org's standard.

A runbook for known failure modes turns "the eval score dropped" into an actionable response, not just a detection signal - the fourth general artifact. The eval suite tells the receiving team WHETHER something regressed; a runbook tells them WHAT TO DO about it: who to page, whether to roll back a prompt/agent version (see Systems Life-Cycle Management for the rollback mechanics), and what an acceptable interim mitigation looks like while a fix is prepared. Without it, a detected regression still stalls on "now what."

Where Claude Code or the Agent SDK is genuinely part of the build, the `.claude` directory is the full configuration surface, not just the top-level file - but it's a CONDITIONAL, tool-specific layer, not part of the general package above. CLAUDE.md and auto memory are two different artifacts with two different owners: Anthropic's own Claude Code docs draw the line precisely - CLAUDE.md files are "instructions you write to give Claude persistent context" (reviewable, committed, team-owned), while auto memory is "notes Claude writes itself based on your corrections and preferences" (accumulated automatically, needs periodic audit). Beyond CLAUDE.md, .claude/rules/ (path-scoped conventions), settings.json, hooks, skills, commands, and subagents all independently shape running behavior when they're in play. A handoff that documents only CLAUDE.md and never mentions hooks or settings hands the receiving team an incomplete picture of what actually governs the system - but a handoff for a system with no .claude directory at all is not incomplete on that basis; it simply doesn't have this conditional layer to hand over.