Pro Domain 7 · Developer Productivity & Operational Enablement (7%)

What this domain asks you to do. The Foundations track taught you what each Claude Code file is: which CLAUDE.md loads, how settings precedence merges, when a hook fires, and what a skill contains. The Professional track asks a different question. You are responsible for forty developers, not one terminal. The exam guide says the minimally qualified candidate "configures Claude tools and environments for teams", "improves developer workflows using AI-assisted tooling", and "supports debugging and operational issue resolution". Each of these verbs is about a team. So the artifacts (the files and documents you produce) are team artifacts too: a managed policy that an IT admin deploys, a shared conventions file that the team reviews in pull requests, a skills catalog with owners, an MCP allowlist, a CI hook, an adoption dashboard, a runbook, and an enablement plan that someone signs. This page builds directly on Domain 2 · Claude Code. It links to the mechanisms there and does not teach them again.

Objective 1 · Configure Claude tools and environments for teams

Configure Claude tools and environments for teams (e.g., Claude Code)

The mechanism is the same ladder you learned in Foundations. Settings precedence works like this: managed policy sets hard limits first, and then CLI flags, local project, shared project, and user settings apply in order. Foundations teaches it in Permissions & settings precedence, and shows the three files side by side in Settings — the same key at three layers. At the team level, one thing changes: the question you ask about every line. Who owns this rule, and what happens if that owner is wrong? The answer to that question is a team environment configuration. It is a small set of files with named owners, an order for the rollout, and a way to check that each developer's machine really received them.

Managed settings rollout — the policy layer as a team artifact

Who writes it: security or platform engineering. The architect decides what belongs there. Where it lives: the [managed policy](term:managed policy) file on each machine. MDM (device management software) or a setup script deploys it. On macOS it is /Library/Application Support/ClaudeCode/managed-settings.json; on Linux it is /etc/claude-code/managed-settings.json. Developers cannot edit it, and no lower layer can loosen it. A managed settings rollout is the plan to put that file on every machine, in stages, with a check at each stage.

Here is a managed file for Meridian. It is illustrative (an example, not a real company file), but complete:

{
  "permissions": {
    "deny": [
      "Read(.env*)",
      "Read(**/*.pem)",
      "Read(**/secrets/**)",
      "Bash(curl:*)",
      "Bash(wget:*)"
    ],
    "ask": [
      "Bash(git push:*)",
      "Bash(npm publish:*)"
    ]
  },
  "disableBypassPermissionsMode": "disable",
  "forceLoginMethod": "console",
  "env": {
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1",
    "OTEL_METRICS_EXPORTER": "otlp",
    "OTEL_EXPORTER_OTLP_ENDPOINT": "https://otel.meridian.internal:4318"
  }
}

Read it by owner, not by key. permissions.deny is the security team's list: the tool cannot read secrets, and it cannot run quick commands that send data out of the network. permissions.ask is the "confirm before it leaves the machine" list. disableBypassPermissionsMode removes --dangerously-skip-permissions from every laptop. forceLoginMethod keeps billing on the organization's account. The env block turns on telemetry and sends it to the team's collector. The adoption metrics later on this page come from there. Nothing in this file is a convention. There is no coding style and no "prefer TypeScript". Those belong one layer lower, where a pull request can change them.

The rollout happens in stages. The reason: a wrong policy is wrong on forty machines at the same time.

Shared CLAUDE.md conventions — the layer pull requests review

Who writes it: the team, through code review. Where it lives: the CLAUDE.md at the repository root. Nested folder memory covers sub-areas, and .claude/rules/ holds conventions for specific paths. Foundations teaches the memory hierarchy. For a team, the rule is: one root file, kept short, owned through a CODEOWNERS entry, and changed only by pull request.

A team root file that has worked well for forty developers is short and gives direct commands:

# Meridian tracking-api — team conventions

- Run `npm test` and `npm run lint` before reporting a task complete. Paste the summary line.
- Never edit files under `migrations/`; propose a new migration file instead.
- API handlers live in `src/handlers/`; shared validation in `src/validate/` (Zod). Do not add a third place.
- Secrets come from the environment. Never write a literal key, token, or password into any file.
- When a task touches `src/billing/`, read `src/billing/CLAUDE.md` first (nested memory).
- Use the `release-check` skill for anything that mentions shipping, deploying, or go-live.

Notice what it does not contain: no security policy (that goes in the managed layer), no permission grants (that goes in settings.json), and no long explanations. Each line names a place, a command, or a skill. If a convention file grows longer than one screen, that is a warning sign. The fix is nested memory in the folder that needs the detail, not a longer root file.

The skills catalog — packaged procedures with owners

Who writes it: the person who owns the procedure. Where it lives: .claude/skills/<name>/SKILL.md in the repository (project scope), or ~/.claude/skills/ for personal skills. Skills are procedures, not connections. The difference is explained in Skills vs slash commands vs subagents. A skills catalog is the team's list of skills: name, owner, trigger phrases, and the date someone last checked it. Without the catalog, two developers write the same "deploy" procedure, and a third developer runs the old one.

---
name: release-check
description: Run Meridian's pre-release checklist. Use when the user says ship, deploy, release, or go-live.
---

1. Confirm the branch is `main` and the working tree is clean; stop and report if not.
2. Run `npm test` and `npm run lint`; on any failure, report the failing line and stop.
3. Run `node scripts/check-migrations.mjs`; a non-zero exit means an unreviewed migration.
4. Print the exact `git log --oneline -5` and ask the user to confirm before tagging.

Skills that run in their own subagent — context: fork

Some skills make a lot of noise. A skill that searches the whole codebase reads dozens of files. If it runs inside your main session, every one of those file reads lands in your conversation. Your context window (the text the model can see at one time) fills up with search results that you do not need after the answer arrives. That is cross-contamination of session state: the procedure's working notes mix with the conversation you are having.

Here is an illustrative skill file (an example for Meridian, not a real company file):

---
name: trace-status
description: Find every place that reads or writes the shipment status field and return a file:line table. Use when someone asks where shipment status is used or changed.
context: fork
agent: Explore
allowed-tools: Read, Grep, Glob
---

Find every read and every write of the shipment `status` field in this repository.

1. Use Glob to list candidate files: `src/**/*.ts`, excluding `**/*.test.ts`.
2. Use Grep for `status` together with `Shipment` to find the matching lines.
3. Read only the matching line ranges, to decide whether each line reads or writes the field.
4. Return one Markdown table: file:line | read or write | one-line note. Do not return file contents.

What each line does, and who acts on it.

Two more facts from the skills docs. A forked skill runs in the background by default; set background: false when the session should wait for it. And the docs say context: fork "only makes sense for skills with explicit instructions". A skill that only says "follow our style guide" gives the subagent nothing to do. The same frontmatter applies when you invoke the skill as a slash command (/trace-status); Foundations explains how skills and slash commands relate in Are slash commands and skills different things?.

The MCP server allowlist — connections the team may use

Who writes it: the platform team. Security approves each server. Where it lives: .mcp.json in the repository holds the project-scope servers. For enforcement, the managed layer can limit which servers users may configure at all. Every [MCP server](term:MCP server) is a network connection and a set of tools. An allowlist is a removal control. It stops a developer from connecting an unreviewed server to a session that can read the codebase.

{
  "mcpServers": {
    "jira": {
      "type": "http",
      "url": "https://mcp.meridian.internal/jira"
    },
    "shipment-db-readonly": {
      "command": "npx",
      "args": ["-y", "@meridian/mcp-shipments", "--readonly"]
    }
  }
}

The shared file names two servers that the team reviewed. The --readonly argument is important. It is the least-privilege decision, made at configuration time and written in the file, not in a prompt. To enforce the list — so a developer cannot add a third server on their own machine — you need a managed-layer setting. Check the current managed-settings documentation for the exact key, because this mechanism lives above the project file.

Decision table — which layer owns which rule

The wrong choice, and what it produces. The most common team failure is policy in the wrong layer. Someone writes a security rule into the committed .claude/settings.json because "that's where permissions go". It works until the first developer is blocked by a prompt and removes the line. Nothing stops them, because developers can edit the project layer. On the exam, this wrong option (distractor) looks like a reasonable control ("add the deny rule to the shared project settings"). It fails because of ownership, not syntax. The second failure is the opposite: conventions placed in managed policy. Managed policy cannot express "run tests first" at all, and every style change must then wait for IT. The third failure is parallel work without [worktrees](term:worktree isolation): forty developers running agents in the same checkout. That is a workflow problem, not a settings problem, so it belongs to the next objective.

Which mechanism? CLAUDE.md, rules, skills, hooks, or permissions

The table above asks "who owns the rule". This one asks a second question: what kind of guidance is it, and when must it apply? Claude Code (the CLI harness) gives a team five places to put a rule. Two of them are context: text the model reads and usually follows. Three of them are executed or checked by the harness: code that runs whatever the model decides. The memory docs say it directly about CLAUDE.md: "Claude treats them as context, not enforced configuration. To block an action regardless of what Claude decides, use a PreToolUse hook instead."

Recall line: context (CLAUDE.md, rules, skills) tells the model what to do; the harness (hooks, permissions) decides what is allowed to happen. The features overview says: "If a rule must hold every time, make it a hook rather than a prompt instruction."

# Meridian tracking-api — team conventions

- Run `npm test` and `npm run lint` before reporting a task complete. Paste the summary line.
- Never edit files under `migrations/`; propose a new migration file instead. (A PreToolUse hook also blocks this.)
- API handlers live in `src/handlers/`; shared validation in `src/validate/` (Zod). Do not add a third place.
- Handler-specific conventions load from `.claude/rules/handlers.md` when you work in `src/handlers/`.
- Secrets come from the environment. Never write a literal key, token, or password into any file.
- When a task touches `src/billing/`, read `src/billing/CLAUDE.md` first (nested memory).
- Use the `release-check` skill for anything that mentions shipping, deploying, or go-live.

---
paths:
  - "src/handlers/**/*.ts"
---

# Handler conventions

- Every handler validates its input with a schema from `src/validate/` before any other work.
- Return errors as `{ "error": { "code": string, "message": string } }` with a 4xx status; never a bare string.
- Log one line per request with `request_id`; never log the request body.
- Each handler has a test in `src/handlers/__tests__/` with the same file name.

---
name: release-check
description: Run Meridian's pre-release checklist. Use when the user says ship, deploy, release, or go-live.
disable-model-invocation: true
---

1. Confirm the branch is `main` and the working tree is clean; stop and report if not.
2. Run `npm test` and `npm run lint`; on any failure, report the failing line and stop.
3. Run `node scripts/check-migrations.mjs`; a non-zero exit means an unreviewed migration.
4. Print the exact `git log --oneline -5` and ask the user to confirm before tagging.

{
  "permissions": {
    "allow": [
      "Bash(npm test:*)",
      "Bash(npm run lint:*)",
      "Bash(git diff:*)"
    ]
  },
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "python3 .claude/hooks/block_migrations.py"
          }
        ]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "npx eslint --fix \"$CLAUDE_FILE_PATH\" || true"
          }
        ]
      }
    ],
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "python3 .claude/hooks/require_tests_ran.py"
          }
        ]
      }
    ]
  }
}

import json
import sys

payload = json.load(sys.stdin)
file_path = payload.get("tool_input", {}).get("file_path", "")

if "/migrations/" in file_path or file_path.startswith("migrations/"):
    print("Editing migrations/ is blocked. Create a new migration file instead.", file=sys.stderr)
    sys.exit(2)
sys.exit(0)

Four "which mechanism?" decisions, with the tempting wrong choice.

Exam reflex. The words "always", "never", "ensure", or "regardless" point to a hook or a permission rule. The words "only for these files" point to .claude/rules/ with paths:. "On demand" or "a repeatable workflow" point to a skill. "Every session should know" points to CLAUDE.md.

Objective 2 · Improve developer workflows using AI-assisted tooling

Improve developer workflows using AI-assisted tooling

A workflow improvement is a before/after table with a measurement. It is not a list of features. The workflow-improvement method has four parts: name the workflow, state the current number, redesign the steps, and measure again. The exam tests two things: do you keep the deterministic gates where they were, and do you put the model where the waiting was? Foundations covered the tools: headless mode in Claude Code in CI/CD, and the @claude team trigger in The @claude tag. On this page you decide where to use them.

Before / after — Meridian's three workflows

Each row names the number that the team will measure again. "Faster" alone is not a row.

The CI review hook — advisory findings, blocking tests

Who writes it: the platform team. Where it lives: .github/workflows/claude-review.yml. The token is stored in repository secrets, and the workflow is pinned to a fixed version. The job runs headless Claude Code with a limited tool allowlist and posts a comment. It does not set the check status that blocks the merge. The test job still does that.

name: claude-review
on:
  pull_request:
    types: [opened, synchronize]
permissions:
  contents: read
  pull-requests: write
jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: anthropics/claude-code-action@v1
        with:
          anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
          prompt: >
            Review this pull request against the conventions in CLAUDE.md.
            Report correctness risks and convention violations as a checklist.
            Do not modify files. Do not approve or request changes.
          claude_args: "--max-turns 12 --allowedTools Read,Grep,Glob,Bash(git diff:*)"

Read the trust boundary (what the job is allowed to do) line by line. The workflow's own permissions block allows read on contents and write on pull requests, and nothing else. The action version is pinned. --allowedTools pre-approves reading files and viewing diffs, so the job never waits on a permission prompt. Be precise here: the Claude Code docs say --allowedTools lists "tools that execute without prompting for permission". It grants approval. It does not remove Write, Edit, or other Bash commands from the session. To remove tools, you add --tools (shown in the next section). --max-turns is the budget limit. The prompt says "do not approve". But the sentence does not enforce that. The GitHub permission scope enforces it: with contents: read, the job token cannot push, whatever the model decides. This is the same instruction-versus-enforcement difference that Foundations taught.

Developers get a matching hook on their own machines, so the same convention check runs before the PR exists. This is part of a project .claude/settings.json that the team commits:

{
  "permissions": {
    "allow": [
      "Bash(npm test:*)",
      "Bash(npm run lint:*)",
      "Bash(git diff:*)"
    ]
  },
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "hooks": [
          {
            "type": "command",
            "command": "npx eslint --fix \"$CLAUDE_FILE_PATH\" || true"
          }
        ]
      }
    ],
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "python3 .claude/hooks/require_tests_ran.py"
          }
        ]
      }
    ]
  }
}

The PostToolUse hook formats every file that Claude writes. This is a side effect, not a gate. The Stop hook runs a script. The script checks whether the session's transcript contains a test run. If it does not, the script returns a message that asks Claude to run the tests before it finishes. This is the "run tests before done" convention from CLAUDE.md, but now code enforces it at the moment it matters. Text in the memory file asks; the hook checks.

import json
import sys

payload = json.load(sys.stdin)
transcript_path = payload.get("transcript_path", "")
ran_tests = False
try:
    with open(transcript_path, encoding="utf-8") as handle:
        for line in handle:
            if "npm test" in line or "npm run test" in line:
                ran_tests = True
                break
except OSError:
    pass

if not ran_tests:
    print("Run `npm test` and report the summary line before finishing.", file=sys.stderr)
    sys.exit(2)
sys.exit(0)

The script is illustrative. It reads the hook payload from standard input. It scans the transcript file that the payload names. If it finds no test run, it exits with code 2 and a message. A production version would check the test result, not only the command text. For the exam, the shape is what matters: a deterministic script at a lifecycle event, not a longer instruction.

A review job that loads only the standards it needs

The problem. Meridian's second repository runs the review in a plain shell step: claude -p "<prompt>". Each run starts slowly. The reason: the root CLAUDE.md has many @imports (lines like @docs/architecture.md that pull other files into memory). The memory docs say imports "load at launch". So every review loads the whole team memory, plus hooks, skills, and MCP servers, before it reads one line of the diff. But the review only needs one file: docs/review-standards.md. And a pipeline that reads the result needs JSON in a fixed shape, not prose.

The CI step (GitHub Actions run: shell, illustrative paths):

git diff origin/main...HEAD > pr.diff

claude -p "Review the change in pr.diff against the review standards. Report every finding." \
  --bare \
  --append-system-prompt-file docs/review-standards.md \
  --tools "Read,Grep,Glob" \
  --allowedTools "Read,Grep,Glob" \
  --output-format json \
  --json-schema '{"type":"object","properties":{"findings":{"type":"array","items":{"type":"object","properties":{"file":{"type":"string"},"line":{"type":"integer"},"severity":{"type":"string","enum":["blocker","major","minor"]},"rule":{"type":"string"},"message":{"type":"string"}},"required":["file","line","severity","rule","message"]}}},"required":["findings"]}' \
  --max-turns 15 \
  > review.json

jq '.structured_output.findings' review.json

Each flag, what it does, and who acts. All of these are read by Claude Code (the CLI), not by the model.

Two facts to remember about --bare. First, authentication: "In bare mode, Claude Code never reads OAuth credentials or the system keychain." The job needs ANTHROPIC_API_KEY in the environment (from repository secrets), or an apiKeyHelper passed with --settings. Second, the docs do not say whether .claude/settings.json is read in bare mode. So do not rely on project permission rules here: put the tool limits on the command line, as above. The docs also do not say whether @imports inside an appended file are resolved, so keep docs/review-standards.md self-contained.

The three tempting options, side by side.

set -euo pipefail
git diff origin/main...HEAD > pr.diff

claude -p "Review the change in pr.diff against the review standards. Report every finding." \
  --bare \
  --append-system-prompt-file docs/review-standards.md \
  --tools "Read,Grep,Glob" \
  --allowedTools "Read,Grep,Glob" \
  --output-format json \
  --json-schema "$(cat .github/review/findings.schema.json)" \
  --max-turns 15 \
  > review.json

jq -e '.structured_output.findings | type == "array"' review.json > /dev/null
jq -c '.structured_output.findings[]' review.json | while read -r finding; do
  node .github/review/post-comment.mjs "$finding"
done
jq '{cost: .total_cost_usd, session: .session_id}' review.json >> "$GITHUB_STEP_SUMMARY"

{
  "type": "object",
  "properties": {
    "findings": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "file": { "type": "string" },
          "line": { "type": "integer" },
          "severity": { "type": "string", "enum": ["blocker", "major", "minor"] },
          "rule": { "type": "string" },
          "message": { "type": "string" }
        },
        "required": ["file", "line", "severity", "rule", "message"]
      }
    }
  },
  "required": ["findings"]
}

Exploring an unfamiliar codebase — Glob, Grep, then Read

The onboarding row above depends on this skill. A new engineer asks Claude Code, "How does a shipment get its ETA?" The repository has 2,000 files. If Claude reads files one by one, the context window fills long before the answer appears. The fix is an incremental strategy: each step narrows the search, and only the last step reads real code.

Foundations covers the Explore subagent in Plan mode vs direct execution — and the Explore subagent.

Decision table — where does the AI step go?

The wrong choice, and what it produces. The classic distractor is automation that removes the deterministic gate: "let Claude approve the PR when its review finds no issues". It sounds efficient, but it fails as a control. When a model finds no issues, that does not prove there are no issues. And nobody can audit why the merge was allowed. The second distractor is AI chat instead of documentation: the team answers the same onboarding questions in a channel forever, instead of writing them where every session loads them. The third is a longer instruction where a hook belongs: three paragraphs of "please always run tests" that a busy session skips, instead of a ten-line Stop hook that cannot be skipped.

Adoption metrics — how you know the workflow improved

Where the numbers come from. The managed policy on this page turned on Claude Code's OpenTelemetry export and sent it to the team collector. That gives you session counts, token and cost usage, and tool-decision events, and you do not have to add any measuring code yourself. The metric and event names are in the Claude Code monitoring documentation. Read them there; do not memorize them. The CI job's own logs give cost and duration per PR. GitHub gives review wait time and defect data. An adoption-metrics table combines them.

Every row ends in a decision. A metric with no decision column is only reporting, not enablement.

Below is one illustrative record that the collector gets for each CI run. The cost rows read from this shape. When you ask headless Claude Code for JSON output, it prints a JSON result object. The fields shown are the ones the table uses; real output has more fields:

{
  "type": "result",
  "subtype": "success",
  "session_id": "5c1f0c2e-illustrative",
  "num_turns": 7,
  "duration_ms": 412000,
  "total_cost_usd": 0.31,
  "usage": {
    "input_tokens": 48210,
    "cache_read_input_tokens": 39004,
    "output_tokens": 2110
  },
  "result": "Review complete: 2 correctness risks, 1 convention violation."
}

total_cost_usd and num_turns supply the cost rows. cache_read_input_tokens inside usage tells you whether runs reuse the repeated convention prefix. This is the same [prompt caching](term:prompt caching) signal that Foundations taught, but now you read it as a metric across all runs.

Objective 3 · Support debugging and operational issue resolution

Support debugging and operational issue resolution

This section debugs two different systems, and the exam expects you to tell them apart. The first is the developer tool: Claude Code on a laptop or in CI. Here the questions are "why was this command blocked", "why did the hook not fire", and "why did the MCP server not load". The second is a Claude-powered production service: an application your team built on the Messages API or the [Agent SDK](term:Agent SDK). Here the questions are "why did quality drop", "why are we seeing refusals", and "why did latency double". AI-assisted debugging covers both, but the tools for each are different. The developer tool has built-in diagnostics. The production service has only what you logged.

Debugging the developer tool — what is built in

The pattern is the same as settings precedence: before you change anything, find which layer made the decision. Suppose a developer "fixes" a blocked command by adding Bash(*) to their user settings. They have not found the layer that denied it. If that layer was managed policy, the fix does nothing.

Debugging the production service — what you must have logged

Who decides: the architect, at design time. Where it lives: the application writes one structured log line for every model call and every tool run. If a field is not in the log, the on-call engineer cannot ask about it later. This is the minimum record, shown as an illustrative log line from the ETA assistant:

{
  "ts": "2026-09-16T02:14:07Z",
  "service": "eta-assistant",
  "run_id": "run_8f31",
  "request_id": "req_illustrative_01",
  "model": "YOUR_SUPPORTED_MODEL",
  "prompt_version": "eta-v14",
  "index_version": "shipments-2026-09-15",
  "stop_reason": "refusal",
  "usage": {
    "input_tokens": 6120,
    "cache_read_input_tokens": 0,
    "output_tokens": 0
  },
  "tool_calls": [
    {
      "id": "toolu_illustrative",
      "name": "get_shipment",
      "is_error": false,
      "latency_ms": 210
    }
  ],
  "latency_ms": 1840,
  "http_status": 200
}

The incident triage flow — cause before symptom

An incident triage flow for a Claude-powered system puts the checks in order. It starts with what changed most recently and what is cheapest to check. Here it is as the runbook's decision path:

ALERT: quality / refusal / latency alarm on a Claude-powered service

1. Is it the provider?
   → http_status 429/529, error rate across ALL services, provider status page
   → yes: back off, degrade gracefully, wait; do NOT change prompts
2. Did WE change something in the last window?
   → prompt_version, model, index_version, tool schema, deploy timestamp
   → yes: roll back that one change; confirm the metric recovers; then investigate
3. Is the input different?
   → input_tokens p95 jump, new document type, new customer, injection attempt
   → yes: sample 20 requests; classify; add a bound or a detector upstream
4. Is a tool failing?
   → tool_calls[].is_error rate, tool latency, downstream dependency health
   → yes: fix or disable the tool; the model was reporting the failure, not causing it
5. Only now: is the model behaving differently on the same input?
   → replay the golden set against the current configuration
   → regression: escalate with request_ids; compare against the last passing eval

The order of the steps is the whole lesson. A team that starts at step 5 rewrites prompts. Meanwhile the real cause — an index refresh at 01:50 — sits in a log field that nobody checked. The exam guide's own sample question for Domain 4 tests exactly this reflex: when answers are confident but wrong after a document refresh, look at retrieval, not the model.

The runbook template — written before the incident

Who writes it: the architect writes the first draft. After the first incident, the on-call team owns it. Where it lives: in the repository, next to the service, with the same version history. An operational runbook always has the same headings. So under stress, the engineer finds the right section quickly:

# Runbook · eta-assistant

### Symptoms this runbook covers
- Refusal rate > 2% over 10 min · p95 latency > 4 s · golden-set pass rate < 95%

### Collect first (copy-paste)
- `logs query service=eta-assistant last=15m fields=request_id,stop_reason,model,prompt_version,index_version,http_status`
- `deploys list service=eta-assistant last=2h`
- `index versions shipments last=3`

### Triage order
1. Provider (status page, 429/529 share) → 2. Our last change → 3. Input shift → 4. Tool errors → 5. Model regression (golden set replay)

### Rollback
- Prompt: `config set eta-assistant prompt_version=<previous>` (takes effect on next request; no deploy)
- Index: `index alias shipments --to <previous version>`
- Model tier: `config set eta-assistant model=<previous supported model>`

### Escalate when
- Provider incident longer than 30 min → status update to stakeholders every 30 min
- Golden-set regression with no config change → open a provider support case with 5 request_ids

### After
- Post-mortem within 2 business days using the `postmortem` skill; add the new failure to this runbook

Most teams forget to write the rollback section, and it is the section they need most at 2 AM. Every rollback here is a configuration change, not a code deploy. That works because the prompt version, index alias, and model tier were designed as runtime configuration. That decision was made in Domain 5's reliability engineering, and here it pays off.

Decision table — control types in operational support

The wrong choice, and what it produces. The most common distractor is symptom over cause: "adjust the prompt to reduce refusals", while the log shows that index_version changed an hour before the alarm. The second is a detective control when the question asks for a preventive one: "add an alert on quality drop", when the question asked how to stop bad indexes from reaching production. The alert catches the problem only after users saw it. The third is asking the model to do the operator's job: "have Claude summarize the logs and decide whether to roll back". A summary is useful. But the decision does not belong to the model, and the runbook exists so that the decision is already made.

The enablement plan — the artifact an architect hands to a team

The enablement plan brings the three objectives together on one page. It is a markdown document in the platform team's repository. The engineering manager and security review it, and the team updates it at each stage gate:

# Enablement plan · Claude Code at Meridian Freight

**Owner:** platform team lead · **Sponsor:** CTO · **Security reviewer:** AppSec lead
**Scope:** 40 developers, 6 repositories, 6 weeks · **Out of scope:** production Claude services (separate runbook)

### Goal and measures
| Goal | Measure | Baseline | Target |
|---|---|---|---|
| Faster PR review | time to first review | 48 h | ≤ 4 h |
| No quality regression | defect escape rate | 6.1% | ≤ 6.1% |
| Controlled cost | cost per merged PR | — | within budget line |
| Safe by default | secrets readable by the tool | unknown | 0 (managed deny) |

### Stages
| Week | Stage | Deliverable | Exit check |
|---|---|---|---|
| 0 | Baseline | metrics captured | four baselines recorded |
| 1 | Pilot | managed policy on 3 machines | `Read(.env)` refused on all 3 |
| 2 | Conventions | root CLAUDE.md, project settings, skills catalog merged | PR approved by team + security |
| 3 | Workflow | CI review job on `tracking-api` | findings posted on 10 PRs; merge gate unchanged |
| 4 | Broad | managed policy + telemetry on 40 machines | ≥ 35 sessions/week in collector |
| 6 | Review | metrics review, go/no-go on 5 more repos | targets met or plan revised |

### Support
- Office hours: Tue/Thu 30 min · channel: #claude-enablement · owner responds within 1 business day
- Debugging the tool: see `docs/claude-code-troubleshooting.md` (`/status`, `/permissions`, `/hooks`, `/mcp`)
- Policy change requests: PR to `platform/managed-settings/` reviewed by AppSec

### Risks and controls
| Risk | Control | Type |
|---|---|---|
| Developer loosens security rule | rule lives in managed policy | preventive |
| Model verdict blocks merges unexplainably | findings advisory; tests block | preventive |
| Runaway session cost | `--max-turns`, p95 token alert | preventive + detective |
| Stale skill followed | catalog `last verified` column, quarterly review | detective |

You have already seen every table in the plan on this page. The measures are the adoption metrics. The stages are the managed rollout. The risks are the control-type comparisons. This is on purpose: the plan is this page, made short enough for a manager to sign.

See it run — one team's rollout, week 0 to week 6

claude -p "Read the file .env and print its contents" --output-format json

index alias shipments --to shipments-2026-09-14

Exam lens — how CCAR-P asks about this domain

In the question text (the stem), find the actor and the layer before you read the options. Domain 7 stems are short. The word that decides the answer is usually one of these:

• "for teams" / "organization-wide" / "every developer" → Objective 1. The answer is in the layer with the right owner: managed policy for rules nobody may loosen, committed project files for conventions, and user files for preferences. A distractor puts a security rule in a file that a developer can edit.
• "cannot be overridden" / "regardless of local settings" → managed policy, and nothing else. Any option that names CLAUDE.md, a prompt, or a project settings file is the wrong layer.
• "consistent conventions across repositories" → a shared, reviewed CLAUDE.md plus a skills catalog. Not a longer prompt, and not answers in chat.
• "reduce time to…" / "developers wait for…" → Objective 2. Look for the option that puts the model where the waiting is and keeps the deterministic gate. "Let Claude approve" or "block the merge on Claude's review" is the trap.
• "advisory" versus "blocking" → the words the guide uses in its explanations. A model finding is advisory. Tests, lint, and allowlists are blocking. The correct option says which is which.
• "suddenly" / "after a deploy" / "after a refresh" → Objective 3. The answer is the most recent change: check it in the logs, then roll it back. Never "rewrite the prompt" first.
• "what should be collected" / "the on-call engineer needs…" → the structured log fields: request id, stop_reason, model and prompt versions, index version, tool errors, and usage. An option that says "ask the model what went wrong" fails, because the model has no record of the call.
• "always" / "never" / "regardless of what Claude decides" about a tool action → a hook (for example PreToolUse) or a permission rule. A CLAUDE.md line is context, not enforcement. "only for files in…" → .claude/rules/ with paths: globs. "repeatable procedure, on demand" → a skill.
• "isolated" / "without polluting the session" for a skill → context: fork in its frontmatter. The forked subagent does not see the conversation, so the trap is a skill that needs the current discussion.
• "CI review starts slowly" / "only needs the standards file" → claude -p --bare --append-system-prompt-file <standards>. --bare alone drops the standards; --system-prompt-file replaces the default prompt. "restrict tools" → --tools; --allowedTools and a skill's allowed-tools only pre-approve. "downstream processing" → --output-format json with --json-schema.
• "how would you know the rollout worked" → an adoption metric with a baseline and a decision attached. Never a number that only counts amount.

Words the answer key uses in its explanations. Preventive (managed deny, allowlist, eval gate before publish) wins over detective (alert, log, audit) when the stem asks you to stop something from happening. Removal (take the capability or server out of the configuration) wins over compensating (confirmation prompt, monitoring) when the stem says least privilege. Cause (the changed version in the log) wins over symptom (the refusal rate) when the stem says "first". And enforcement (hook, permission, policy) wins over instruction (text in CLAUDE.md, a sentence in a prompt) whenever the stem says "ensure" or "guarantee".

Related

• Foundations this page grows from: Domain 2 · Claude Code — the memory hierarchy · Permissions & settings precedence · Hooks — deterministic control · Skills vs slash commands vs subagents · Claude Code in CI/CD · The @claude tag
• Operational foundations: Domain 5 · Reliability engineering · Observability — every action explainable · Deployment · headless mode · Scenario 5 · Claude Code in CI/CD
• Sibling Professional pages: Pro 1 · Solution Design · Pro 2 · Models, Prompting & Context · Pro 3 · Integration · Pro 4 · Evaluation & Optimization · Pro 5 · Governance, Safety & Risk · Pro 6 · Stakeholder & Lifecycle
• Hub: Professional track · Glossary