Home › Study guides › CCAR-P › Domain 6 › Lesson 6.4

CCAR-P · Domain 6 · 14% of the exam · Lesson 6.4 · 23 min read

Documenting the architecture and guiding the team that builds it

What to document for a Claude solution, how to guide the builders with contracts and a CLAUDE.md, and how to keep the pack versioned with the code.

Written against objective 6.4 of the official CCAR-P exam guide (Version 1.0, effective July 2026). An independent resource, not affiliated with Anthropic; the practice questions are written from scratch.

6.4.1 Why a finished design fails in someone else's hands

Vantridge Pharmacy, a US chain of 1,100 stores, takes about 40,000 refill requests a day by phone, app and text message. Emrys, its lead architect, spent eight weeks with the pharmacy practice team designing a prescription-refill assistant. A patient writes "I need my blood pressure tablets again", and the assistant finds the matching prescription, confirms the store and the pickup, and queues the refill for a pharmacist to check. The build goes to an outsourced delivery partner in Bengaluru, roughly ten hours ahead. Meenakshi, its delivery lead, has eight engineers on it, and her working day overlaps with Emrys's by about an hour.

The easy handover is the design-review deck and a walkthrough call. It fails in a predictable way. Every day the team makes dozens of small decisions the deck never mentions. What does the tool return when the pharmacy system times out? Is an expired prescription a refusal or a referral to a pharmacist? Which prompt file is the approved one? May a real patient record go into a test? Each question waits a day for the overlap hour, or gets a plausible guess. The guesses compile, pass their unit tests and look fine in a demo.

It is the same problem as prompting. Anthropic's prompting guide offers a test for any prompt: show it to a colleague with minimal context and ask them to follow it; if they would be confused, Claude will be too. A delivery team ten hours away is that colleague. Whatever they receive has to answer their questions without you.

That is the job of the architecture documentation set, which we will call the pack, and of the implementation guidance that travels with it. Together they are the artefacts that let another team build, test and run the system as designed. How much they must hold depends on the distance to their readers. A team down the corridor can ask; an outsourced team ten hours away, building on health data, needs every answer written down.

6.4.2 Start from the data: flows, classes and obligations

Here is the question builders ask first, usually too late: which data goes where, and what may happen to it on the way? A box diagram of components shows the parts but not what travels between them. A context and data-flow diagram does. It draws every system the solution touches, every flow between them, and the data classification of each flow: which class of data it carries, and therefore which controls apply.

Three classes cover everything at Vantridge. Prescriptions and patients' messages are protected health information (PHI), health data about an identifiable person that HIPAA, the US health-privacy law, protects. Prompts, tool contracts and internal policies are confidential. Store hours are public. Once every flow carries a label, the obligations follow from it. The pack's security and compliance notes write them down as design obligations, not legal advice, each checked against Anthropic's current pages.

• Covered processing. Anthropic's data-retention page says PHI may go through the Claude API under a signed business associate agreement (BAA), in an organisation with HIPAA readiness enabled, using eligible features. The notes list every API feature the design uses and check each one against the page's eligibility table.
• Clean schemas. Structured outputs and strict tool use make Claude's reply or tool input match a JSON schema you supply. The same page warns that these schemas are cached apart from message content, without the same PHI protections. No patient-specific value may appear in a property name, enum, const or pattern.
• Synthetic data for the builders. Meenakshi's team builds with Claude Code, Anthropic's coding agent that reads and edits a repository from the developer's terminal, and the same page says Claude Code is not covered under HIPAA readiness. Real patient records never enter a session; tests and demos use synthetic data.

6.4.3 Document the parts only a Claude system has

Conventional documentation covers APIs, data stores and deployment. A Claude solution adds parts that change behaviour like code but are never compiled: prompts, tool descriptions, model settings, retrieval indexes. Their output is probabilistic, so "it works" means something only against an eval with agreed thresholds. Leave them out of the pack, and a delivery team will treat the system prompt as a string it may tidy and a model upgrade as a routine dependency bump.

Two rows need a word. The model configuration names a pinned model ID, not a family such as "Sonnet". Anthropic's versioning page says an ID stays on one fixed snapshot for its lifetime, and each ID has its own deprecation and retirement schedule. So the document also names who watches that schedule. It records every setting explicitly rather than trusting defaults, because defaults differ between models. Effort, the parameter that trades thoroughness against speed and token cost, defaults to high on Claude Sonnet 5.5 but medium on Claude Opus 5.5.

The thresholds turn "test it properly" into a release rule. Anthropic's guide to success criteria asks for criteria that are specific and measurable, usually on several dimensions at once. Emrys writes Vantridge's thresholds as a short artefact that the pharmacy practice lead signs. Look at how each line names its test set and what a miss does.

ACCEPTANCE THRESHOLDS, refill assistant. Owner: pharmacy practice lead. Run on every change to a prompt, tool, model setting or retrieval setting.
Prescription match: at least 98% correct on 400 anonymised past requests. Below 98% blocks release.
Referral to a pharmacist: 100% of the 60 controlled, expired and no-refill cases. Any miss blocks release.
Scope: no clinical or dosing advice in any of the 80 adversarial cases. Any miss blocks release.
Latency: 95th-percentile reply time under 6 seconds on the 400-case set. A miss needs the practice lead's written sign-off to release.

6.4.4 Implementation guidance: contracts first, then a reference path

The pack says what the system is. Implementation guidance says how to build it so that eight engineers produce one system, not eight. Four instruments do most of the work, and each wins in a different place.

For a team with one overlap hour a day, contracts come first, because a contract settles an argument without a meeting. Emrys then builds one thin reference path himself: a patient message in, a refill queued or referred out, every failure branch included, written against the contracts. The team copies its structure instead of inventing its own. The coding standards stay short and Claude-specific. Check stop_reason, the response field that says why Claude stopped, before acting on any reply. Log the prompt version and model ID with every call, and keep message content out of shared logs.

The contract for a tool Claude calls starts with its definition. Look at strict: true and additionalProperties: false, which hold Claude's input to exactly this shape, and at rx_id, an opaque identifier rather than anything about the patient.

{
  "name": "submit_refill_request",
  "description": "Queue a refill of one active prescription for pharmacist review. Call only after the patient has confirmed the prescription and the store.",
  "strict": true,
  "input_schema": {
    "type": "object",
    "properties": {
      "rx_id": {"type": "string", "description": "Opaque id from list_active_prescriptions"},
      "store_id": {"type": "string", "description": "Store the patient confirmed"},
      "fulfilment": {"type": "string", "enum": ["pickup", "delivery"]}
    },
    "required": ["rx_id", "store_id", "fulfilment"],
    "additionalProperties": false
  }
}

The rest of the contract is what the schema cannot say. Strict mode guarantees the SHAPE of a call, never that the call is allowed. Anthropic's structured-outputs page lists what the schema subset cannot express, numeric ranges among them, and warns that a reply ending in refusal or max_tokens may not match the schema at all. So the contract states that the refill service re-checks the prescription: it belongs to the signed-in patient, has refills left, has not expired and is not a controlled substance. It fixes three result shapes: queued with a ready time, needs_pharmacist with a reason, and unavailable. And it says what the caller does with each.

6.4.5 A CLAUDE.md for a team that builds with Claude Code

Meenakshi's engineers build with Claude Code, so every session has a second reader of the guidance: Claude itself. A CLAUDE.md file briefs it. Claude Code loads the project's file, ./CLAUDE.md or ./.claude/CLAUDE.md, at the start of every session, and because the file is committed to the repository, the whole team shares one version.

The tempting move is to import the whole pack so that Claude "knows the architecture": a line such as @docs/architecture/pack.md in CLAUDE.md pulls that file into every session. Resist it. Anthropic's docs suggest keeping each CLAUDE.md under 200 lines, because longer files use more context and reduce adherence, and an imported file loads in full at launch too. The file holds what every session needs: commands, where things live, conventions, and the few rules that matter, each with its reason. The pack stays in docs/architecture/, named by path, for Claude to open when a task calls for it.

Here is the start of Vantridge's file. Look at the rules that carry their reasons, and at the pointers that name files without importing them.

# Vantridge refill assistant

## Commands
- `make test` runs unit tests; `make evals` runs the eval suite (uses API credits)

## Where things live
- Architecture pack: `docs/architecture/` (start at its README)
- Prompts: `prompts/`, one file per version. Never edit a released version; add a new one.
- Tool contracts: `contracts/tools/`. Change a contract before the code that uses it.

## Rules
- Synthetic data only (`fixtures/synthetic/`): Claude Code is outside Vantridge's HIPAA arrangement.
- Refill eligibility lives in `refill_service/eligibility.py`, never in a prompt, because a prompt cannot guarantee it.
- A change under `prompts/` or to the model settings updates `docs/architecture/inventory.md` and attaches an eval run.

Know its limit. Claude Code treats CLAUDE.md as context, not enforced configuration. For anything that must be blocked whatever Claude decides, its docs point to a hook, a script Claude Code runs at a fixed moment such as before a tool call. So every rule here is backed by something that does enforce it. Eligibility has its module and tests, the inventory rule a CI check, and the synthetic-data rule the strongest control of all: the delivery team has no access to production records. The shared settings, permissions and hooks of the team's Claude Code set-up are a configuration job of their own.

6.4.6 Docs as code, and the test of a complete handoff

A pack written once and kept on a wiki is accurate for about a sprint. After the first prompt fix, a new tool and a model upgrade, it describes a system that no longer exists, and soon nobody reads it. Docs as code fixes that: the pack lives in the same repository as the system, changes in the same pull request, goes through the same review and ships with the same release tag.

At Vantridge, any change to a prompt, a tool contract, a model setting or a retrieval setting must update the inventory and attach a fresh eval run. CI fails when a prompt file's version is missing from the inventory, and a model change gets no exemption. Anthropic's prompting guide says a technique measured on one model should be re-checked against your own evals before you apply it to another, so every eval record in the pack names its model ID. Look at what each inventory line carries: the file, the owner, and the eval run with the model it ran on.

PROMPT refill-system v7 | prompts/refill-system.v7.md | owner: prompt lead, delivery team | sign-off: pharmacy practice lead | evals 2026-09-24 on claude-sonnet-5-5: all thresholds met
TOOL submit_refill_request v3 | contracts/tools/submit_refill_request.v3.json | owner: pharmacy systems tech lead | writes to the refill queue; the service re-checks eligibility
MODEL claude-sonnet-5-5 | effort medium, max_tokens 8000 | owner: platform lead, delivery team | watches the deprecation schedule; evals re-run before any change of ID

The handoff package is everything the receiving team needs to build and run the system without the architect: the pack, the implementation guidance, the reference path and a runnable eval suite. How do you know it is enough? "The team has no questions" proves nothing: nobody asks about what they do not know is missing. Emrys runs a tabletop walkthrough, a rehearsal on paper. Meenakshi's team answers five realistic scenarios from the pack alone while he stays silent.

The pharmacy system fails for twenty minutes. A patient asks whether the refill is safe with ibuprofen. Anthropic announces a retirement date for the pinned model. A release candidate misses a threshold. A new engineer wants to demo with a real prescription. Each answer that ends in "ask Emrys" is a defect in the pack, fixed before he leaves. The package is complete when the team can build, release and run the system without him, with a named person other than the architect as owner of every part.

6.4.7 The exam traps

Every trap here leaves the knowledge where builders cannot reach it when they need it: in a deck, a person, a wiki or a prompt.

• ✗ Handing over the design deck and a walkthrough as the documentation. ✓ Hand over a pack that answers the builders' questions: classified data flows, the inventory, contracts, thresholds, failure modes, runbooks and owners.
• ✗ Keeping the documentation in a wiki and updating it after each release. ✓ Store it with the code and change it in the same pull request as the prompt, tool or model change, with an eval run attached.
• ✗ Describing prompts and model settings in prose ("the assistant uses Sonnet"). ✓ Inventory each one with its exact version or pinned ID, file, owner and last eval run, so any reply can be traced and any change reviewed.
• ✗ Trusting the schema, the prompt or CLAUDE.md to enforce a business rule. ✓ A strict schema guarantees shape, a prompt makes behaviour likely and CLAUDE.md is context. Rules that must hold live in the service, tests or hooks, and the contract says where.
• ✗ Importing the whole architecture pack into CLAUDE.md. ✓ Keep CLAUDE.md short, with commands, conventions and key rules with reasons, and name the pack by path.
• ✗ Treating "no questions", or an architect staying on call, as proof that the pack is complete. ✓ Test the package with realistic scenarios answered from the pack alone. A short support period may follow, but it is not the evidence.

6.4.8 Put it together: write a handoff pack and test it

You now have every piece, from classified data flows to a pack that changes with the code and passes a scenario test. The quickest way to own the method is to write a small pack, then watch a reader who lacks one part of it improvise.

Three neighbouring objectives pick up from here. Decision records (6.2) carry the why behind each choice the pack states. The lifecycle handoff (6.5) is the phase in which ownership actually moves, with the monitoring and iteration that follow. Team tool configuration (7.1) turns the conventions in CLAUDE.md into shared settings, permissions and hooks that enforce them.

Key takeaways

• ✓ Documentation is the part of the design that works without the architect: write it for a team that cannot ask you, as owned, versioned artefacts beside the code.
• ✓ Start from a context and data-flow diagram with each flow's data class, and turn the classes into security and compliance obligations checked against Anthropic's current pages.
• ✓ Document the Claude-specific parts: a prompt and tool inventory with versions and owners, a pinned model configuration, the retrieval design, guardrails and human review points, failure modes, runbooks, and acceptance thresholds that gate every release.
• ✓ Guide the build with interface contracts first, then a reference path and coding standards; a strict schema guarantees shape, so the contract also states the checks the service enforces.
• ✓ Give Claude Code teams a short, committed CLAUDE.md with commands, conventions and rules with reasons, pointing to the pack by path, and back every must-hold rule with code, tests or hooks.
• ✓ Keep docs as code, changed in the same pull request as each prompt, tool or model change, and prove the handoff package by having the receiving team answer realistic scenarios from it alone.

Check your understanding

4 questions written for this lesson, then one from the CCAR-P question bank on the same topic. Every answer option is explained, including the ones you did not pick. Nothing is stored.

Sources

• How Claude remembers your project
• Structured outputs
• Define success criteria and build evaluations
• Prompting best practices
• Model IDs and versioning
• Effort
• API and data retention
• The CCAR-P exam guide, summarised