CCAR-P Domain 7: Developer Productivity & Operational Enablement

Claude Code resolves configuration in layers. User settings (~/.claude/settings.json) apply to one engineer everywhere; project settings (.claude/settings.json, checked into the repo) apply to everyone on that repo; local settings (.claude/settings.local.json, gitignored) let an individual override without polluting the shared config. Enterprise-managed policy settings sit above all of them and cannot be overridden. As an architect you push team defaults into the checked-in project layer and reserve the local layer for personal preference.

The harder design decision is which mechanism to use for a given rule. Some mechanisms advise the model; others are enforced by the harness before the model's output ever runs. Getting this mapping right is the core competency the domain tests.

Two complementary primitives turn tribal knowledge into reusable tooling. Custom slash commands are Markdown files in .claude/commands/ (project) or ~/.claude/commands/ (personal); the filename becomes the command, and the body is a prompt template that can take arguments. Skills are richer, model-invoked capabilities under .claude/skills/<name>/SKILL.md — the model reads a Skill's description and decides on its own when to pull it in, so Skills carry a whole procedure plus optional scripts and references.

• Reach for a slash command when a human wants an explicit, on-demand entry point — /deploy-check, /open-pr, /triage.
• Reach for a Skill when you want Claude to recognize a situation and apply a standard procedure without being told each time.
• Both live in the repo, so distribution is just git — clone the repo and the whole team has them.
• Version them like code: review changes in PRs, because a bad shared command misfires for everyone.

Non-interactive mode (-p / --print) is how Claude Code runs inside pipelines. In print mode you get a single answer and exit; combine it with structured output and hard limits so a CI step is deterministic, parseable, and cost-bounded. The flags below are the ones an architect wires into a pipeline.

# CI step: classify a PR diff into a bounded, schema-checked JSON result
claude -p "Classify the risk of this diff" \
  --output-format json \
  --json-schema '{"type":"object","properties":{"risk":{"type":"string"}},"required":["risk"]}' \
  --max-budget-usd 0.50 \
  --permission-mode plan \
  --allowedTools "Read Grep"

MCP servers extend Claude Code with tools — a database client, an internal ticketing API, a docs search. To distribute one across a team, define it at project scope in a checked-in .mcp.json at the repo root. Everyone who clones the repo inherits the same server definitions, so tool availability is reproducible rather than something each engineer configures by hand. User-scoped MCP config stays personal; local scope is for one-off experiments.

Secrets are the sharp edge. The .mcp.json you commit must never contain credentials. Reference environment variables with ${VAR} expansion and let each developer or CI runner supply the actual secret out of band — a secrets manager, CI variables, or a gitignored .env. The committed file describes how to connect; it never carries the key.

{
  "mcpServers": {
    "internal-tickets": {
      "command": "npx",
      "args": ["-y", "@acme/tickets-mcp"],
      "env": { "TICKETS_API_TOKEN": "${TICKETS_API_TOKEN}" }
    }
  }
}

The payoff of committing CLAUDE.md, .claude/commands/, .claude/skills/, .claude/settings.json, and .mcp.json to the repo is that a new hire's first git clone brings the entire operational context with it — conventions, team commands, standard procedures, permission guardrails, and tool wiring. That is the golden path: the sanctioned, low-friction route that is easier to take than to reinvent.

• Ship starter templates (repo scaffolds) that already contain the .claude/ config so new services inherit the standard from day one.
• Keep secrets out of every committed file; document the required env vars in CLAUDE.md so onboarding is self-serve.
• Treat the shared config as reviewed code — changes go through PRs, not ad hoc edits to one person's machine.
• Use enterprise-managed policy settings for controls that must not be locally overridable across the org.

Enablement without measurement is faith. An architect instruments adoption and outcomes, then feeds the data back into the shared config. Structured JSON output from headless runs, session cost data, and standard delivery signals (cycle time, review turnaround, change-failure rate) let you see whether the golden path is actually being taken and whether it helps.

• Adoption: are the shared commands, Skills, and MCP servers actually invoked, or do engineers route around them?
• Cost: --max-budget-usd and JSON output make per-run spend observable so automation stays within budget.
• Flow: measure delivery outcomes (lead time, defect escape rate), not vanity metrics like lines generated.
• Feedback loop: when a control is repeatedly overridden, that is a signal the guidance is wrong — fix the config, not the people.

Authoring a Skill is the easy half. The professional problem is distribution: getting the same versioned, trustworthy Skill in front of every engineer, keeping it current as it changes, and knowing who owns it when it breaks. A Skill is just a directory — a SKILL.md with YAML frontmatter (name, description) plus any bundled scripts or reference files — so the distribution question reduces to where that directory lives and how it reaches a developer's session. There are three realistic homes, and choosing among them is the strategy decision, not an afterthought.

Personal Skills (~/.claude/skills/) belong to one machine and don't travel — fine for experiments, wrong for team assets. Project Skills (.claude/skills/ committed to the repo) ride along with a git clone or git pull, are reviewed through the same PR process as code, and are versioned by the repo's own history — this is the default answer for anything specific to one codebase. Plugin Skills are packaged into a plugin and served from a marketplace the org controls; a developer installs once and receives updates on their own cadence, which is what you want for cross-repo, org-wide capabilities (a house code-review style, a release runbook) that shouldn't be copy-pasted into thirty repos.

Versioning and ownership are what separate a distributed Skill from a shared liability. Give each shared Skill a named owning team, a version recorded in the frontmatter or the plugin manifest, and a changelog — because a Skill silently rewrites how work gets done, an unannounced change to its instructions is a production change with no diff anyone reviewed. Roll updates out the way you roll out config: stage to a small group, watch, then widen. Treat a Skill's bundled scripts as code (they execute), and treat its prose as policy (it steers judgment); both deserve review.

The other half of team setup happens before anyone logs in: shared configuration and spend controls. Layer a checked-in .claude/settings.json (shared, in the repo) under an admin-managed managed policy that individuals cannot override, and keep personal settings.local.json for individual taste only. Into that shared layer belong the guardrails that cost real money: a default model tier so routine work doesn't reach for the most expensive model by reflex, budget and usage limits at the org/workspace level, and a rate posture that fails safe under load. Decide these once, centrally, so cost is a property of the platform rather than a per-developer accident.

AI raises the volume of code an engineer can produce; it does not raise the trust that code deserves. The professional failure mode is subtle: AI output is fluent, plausible, and syntactically clean, so it triggers the reviewer's "looks right" reflex and slides through with less scrutiny than a junior's hand-written patch would get. The discipline that keeps throughput high without lowering the bar is to make verification explicit and non-negotiable — a checklist the author runs before the diff reaches a human, so human review is spent on judgment rather than on catching what a checklist would have caught.

The core trap is that schema-valid is not correct. Output can parse, satisfy its types, and pass a happy-path smoke test while being wrong in ways that only a human who understands the intent can see: the query returns rows but joins on the wrong key; the migration is reversible but drops an index under load; the auth check is present but checks the wrong claim. These are not syntax errors, so no linter or type-checker flags them. Confidence in the output must come from evidence you gathered, not from the polish of the prose around it.

Throughput and quality are not actually in tension once you route the work correctly. Let automation own the mechanical layers — type-checking, linting, test execution — so they run on every change for free and never tire. Reserve scarce human attention for the two things a model cannot self-certify: whether the change matches the intended behavior, and whether it is safe to ship. Using AI to help review (draft a test, explain a diff, flag a suspicious pattern) is fine and multiplies a reviewer; letting AI be the final judge of its own output is the line you do not cross.

Live AI systems fail differently from ordinary services. The symptom a user reports — "it called the wrong tool," "it answered confidently but wrong," "it got slower and vaguer over a long session" — is rarely where the fault lives. Operational competence at the professional level is the habit of reading a behavioral symptom back to its architectural cause, because the fix for these problems is almost never a code patch at the point of the error; it is a change to a tool description, a context-management policy, a routing rule, or a prompt contract upstream.

Two causes recur often enough to name. Wrong tool routing is almost always a description problem, not a model problem: the model selects tools by matching intent against the words in each tool's description, so two tools with vague or overlapping descriptions will be confused no matter how capable the model is — the fix is editing prose, not retraining. Confident-wrong answers are usually a context problem: the true facts were dropped, summarized away, or never retrieved, so the model reasons fluently over an incomplete picture. Chasing these at the symptom ("add a warning to the output") treats the smoke; naming the architectural cause treats the fire.

Turn that diagnostic habit into artifacts the team can run without you. A runbook per known failure class captures the symptom, the first three things to check, the likely cause, and the remediation — so the on-call engineer follows a path instead of rediscovering it at 2am. An escalation ladder says explicitly who handles what and when it leaves the on-call's hands: self-serve runbook, then owning team, then architect, then vendor. The goal of writing these down is not documentation for its own sake; it is to move knowledge out of your head and into the team's hands.

• Runbook per failure class: symptom → first checks → likely architectural cause → remediation → how to verify it's fixed
• Escalation ladder: on-call (runbook) → owning team → architect → platform/vendor, with the trigger for each hop stated
• Observability the team owns: traces of tool calls, token/context usage, cost per workflow — visible without asking the architect
• A recurring review where the team, not the architect, triages new symptoms and writes the next runbook
• An explicit off-ramp: the architect's involvement is scheduled to shrink, and that is the measure of a successful handoff

The deliverable that outlasts the architect is not the system; it is the team's ability to run and evolve it unaided. Build toward self-sufficiency deliberately: pair on the first few incidents, then let the team lead the next ones while you observe, then step back to advisor. A design that only its author can operate is an operational liability dressed up as expertise. Success is measured the day a novel symptom appears, the team traces it to its architectural cause, fixes it, and updates the runbook — and no one needed to call you.