Rubric
Contents — domains, guide and mocks

Architecture docs and implementation guidance

CCAR-P 6.410 min read · checked 21 September 2026

Task statementDocument architectures and provide implementation guidance

What a handover documentation set contains

Architecturethe single source of truth
  • C4 diagramscontext → containers → components
  • Decision recordsADRs: why, and what it costs
  • Interface specsAPIs, tools, data contracts
  • Prompt & eval packversioned prompts + test set
  • Runbookoperate, monitor, recover
  • Security & dataflows, access, retention
One architecture, several documents, each with a clear reader. Keep them small and linked rather than one monolith.

Diagrams at the right zoom level

The C4 model gives a simple way to draw architecture for different readers. It has four levels. A system context diagram shows your system as one box, with the people and external systems around it — ideal for business stakeholders. A container diagram opens that box to show the separately deployable pieces: web app, API service, database, the Claude API, a vector store. (In C4, a “container” means any deployable unit, not specifically a Docker container.) A component diagram zooms into one container for developers, and a code level shows classes or functions. The C4 site stresses that you do not need all four levels, and that the model works with any notation or tool.

The C4 levels and who reads them

  1. System contextbusiness sponsors, risk, new joiners
  2. Containersarchitects, IT, security, operations
  3. Componentsdevelopers changing that part
  4. Codeoften skipped; the code itself serves
Most client handovers need the top two levels for everyone and the third only for the containers the client’s engineers will change.
A container view of a hospital discharge-letter system (as text)text
[Clinician] --uses--> [Review web app]
[Review web app] --calls--> [Drafting service]
[Drafting service] --reads--> [EHR export (read-only)]
[Drafting service] --retrieves--> [Guideline index]
[Drafting service] --calls--> [Claude API]
[Drafting service] --writes--> [Audit log]
[Review web app] --signed letter--> [Records system]

Notes: patient data never leaves the approved region;
every letter is signed by a clinician before filing.

For Claude systems, a container view should always make three things visible: where data crosses a boundary (especially into the model API), where a human reviews or approves, and where the system’s state and logs live. These are the questions security, compliance and operations will ask first.

Record decisions, not just outcomes

A diagram shows what was built; it never shows why. Architecture decision records fill that gap. In Michael Nygard’s format each ADR is one to two pages with a title, context, decision, status and consequences. ADRs are numbered in sequence and never reused; when a decision changes, the old record stays and is marked superseded by the new one. That history is precisely what a client’s team needs a year later when someone proposes undoing a choice. How to frame the trade-off inside an ADR for stakeholders is covered in 6.2.

DocumentMain readerAnswersUpdate when
System context diagramSponsor, risk, new joinersWhat is this and what does it touch?A new user group or external system
Container diagramIT, security, operationsWhat runs where, and how data flowsA service or data store changes
ADRsEngineers, future architectsWhy was it built this way?Every significant decision
Prompt & eval packEngineers, QAWhat the model is told, and how we know it worksAny prompt, model or tool change
RunbookOperations, on-callHow do I run, monitor and recover it?After every incident or release

Implementation guidance people can act on

Implementation guidance is where many architects stop too early. “Use retrieval and a good prompt” is advice; an implementer needs specifics they can build and verify. For a Claude system that means the interfaces (tool definitions and API contracts), the prompts themselves stored under version control, the model and settings chosen with the ADR that justifies them, the error-handling and fallback behaviour, and — most importantly — the acceptance tests. Anthropic’s evaluation guidance favours task-specific tests that mirror real traffic, include edge cases and can be graded automatically where possible. Handing over the test set and pass mark is the most precise implementation guidance you can give: it defines “done”.

Vague guidance vs actionable guidance

Slide notetext

Drafting service:
- Use Claude with RAG over
  the guidelines.
- Write a good prompt.
- Make sure it is accurate.
- Handle errors properly.

Implementation guidetext

Drafting service (see ADR-004)
Input: EHR export JSON v2.
Retrieve: top 5 guideline
  chunks, cite chunk ids.
Prompt: prompts/discharge.md
  (git tag v1.3), owner QA.
Done when: >=92% on eval set
  evals/discharge-150 (rubric
  in evals/rubric.md).
On API error: retry per
  retry-after, then queue and
  show "draft pending".
The right-hand version can be implemented and checked by someone who never met the architect.

Anthropic’s Building effective agents article makes a related point about tools: the tools an agent uses deserve thorough documentation and testing, because the model can only use a tool as well as its description explains it. Tool and interface documentation is therefore part of the architecture pack, not an afterthought.

Reviewing a handover pack

  • Passes: System context and container diagrams
  • Passes: ADRs for model, workflow and human-review choices
  • Check: Prompts versioned in the repositorytwo prompts still only in a wiki page
  • Missing: Acceptance test set with pass mark
  • Passes: Data-flow and retention notes for security
  • Fails: Runbook with alerts and rollback stepsno rollback procedure
A retailer’s handover pack checked the week before go-live.

Traps the wrong answers are built from

Tempting but wrongDo this instead
One exhaustive design document covering every audience.A small, linked set: C4 diagrams by level, ADRs, interface specs, prompt-and-eval pack, runbook.
Diagrams that show boxes but not data boundaries or human checkpoints.Mark where data enters the model API, where people approve, and where logs live.
Documenting only the final design, not the reasons.Write ADRs with context and consequences; supersede rather than delete old ones.
Guidance like “write a good prompt” or “ensure accuracy”.Hand over versioned prompts, interfaces, fallback behaviour and a test set with a pass mark.
Keeping prompts and eval sets outside version control.Store them in the repository with the code so changes are reviewed and tested.

You should now be able to

  • Choose C4 diagram levels to suit business, operations and developer audiences.
  • Show data boundaries, human checkpoints and logging on a container diagram of a Claude system.
  • Write and maintain ADRs, including superseding decisions that change.
  • Produce implementation guidance an implementer can verify: interfaces, versioned prompts, fallbacks and acceptance tests.
  • Assess a handover pack for gaps before go-live.

Practice questions

Original questions written for this lesson, in the exam’s style. Answer first, then open the reasoning — every option is explained, including why the wrong ones are tempting.

  1. Question 1

    A bank’s risk committee wants to understand a new Claude-based complaints-triage system before approving it. None of the committee members are engineers.

    Which diagram is most appropriate to lead with?

    1. AA component diagram of the triage service’s internal modules.
    2. BA system context diagram of users and external systems.
    3. CA class diagram generated automatically from the codebase.
    4. DA sequence diagram of every API call in a single triage request.
    Show answer and reasoning
    1. AIncorrect. Component detail is for developers changing that service; it buries the committee’s questions.
    2. BCorrect. The context level shows what the system is, who uses it and what it touches — the right zoom for non-technical reviewers.
    3. CIncorrect. Code-level diagrams are rarely needed at all and are meaningless to a risk committee.
    4. DIncorrect. Accurate but too detailed; it answers an engineer’s debugging question, not a governance one.

  2. Question 2

    A year after handover, an insurer decides to replace its fixed extraction workflow with an agent. The original ADR for the workflow is still in the repository.

    What should happen to that ADR?

    1. ADelete it, so nobody is confused by an outdated decision.
    2. BEdit it in place to describe the new agent design.
    3. CMark it superseded and link it to a new ADR for the agent.
    4. DLeave it unchanged; ADRs never need updating after acceptance.
    Show answer and reasoning
    1. AIncorrect. Deleting loses the history of why the original choice was made, which is the point of keeping ADRs.
    2. BIncorrect. Rewriting history hides that the decision changed and why; ADRs should be immutable once accepted.
    3. CCorrect. Nygard’s approach keeps old records, marks them superseded and references the replacement, preserving the full reasoning trail.
    4. DIncorrect. The status field must change, otherwise readers think the old decision still applies.

  3. Question 3

    You are preparing implementation guidance for a retailer’s engineers, who will build the returns assistant you designed.

    Which two items give them the most actionable guidance? (Select 2.)

    1. AAn acceptance test set with a scoring method and pass mark.
    2. BA slide deck summarising the vision for the assistant.
    3. CVersioned prompt files and tool definitions in the repository.
    4. DA note to “follow prompt engineering best practice”.
    5. EA recording of the design workshop for reference.
    Show answer and reasoning
    1. ACorrect. Tests define “done” precisely and let the team check their own work without the architect.
    2. BIncorrect. Useful for sponsors, but it gives engineers nothing they can build or verify.
    3. CCorrect. Concrete, reviewable artefacts that the team can implement, test and change safely.
    4. DIncorrect. Generic advice leaves every real decision to the implementer’s guesswork.
    5. EIncorrect. Hours of discussion are hard to act on; the decisions should be extracted into ADRs.

Practise every question in Domain 6 →

Sources

Drafted with AI assistance and checked against the sources above; expert review is in progress. Spotted an error? Tell us and it gets fixed, dated and listed on how this is written.