Enabling the Team: Claude Code Conventions, AI Workflows, and Ops

You can design a flawless architecture and still watch it get built badly. Every engineer writes prompts a different way, tests a different way, and holds a different picture of the conventions. The system that emerges is a committee’s compromise of your design rather than your design. An architect’s job does not stop at the diagram and the decision record. It includes setting the team up to build and operate the system well. That is developer enablement, and this chapter is about the leverage in the build environment itself.

What developer enablement means for an architect

Developer enablement is the work of shaping how the team builds. The goal is to make good practice the path of least resistance, not a thing each person has to remember. Take a convention like “always ground answers in retrieved context, never let the model answer refund policy from memory.” You can write it in a design doc that nobody rereads. Or you can encode it where it reaches every engineer automatically as they work. That difference is the whole job.

Here is the reframe. Your architecture is not only the running system. It is also the environment that produces the running system, and that environment is a design surface you own. Team conventions, the shared configuration, the automated checks in the pipeline, the way an on-call engineer debugs a production incident: an architect can shape all of them. Shaping them well is often higher-leverage than any single component of the system, because it multiplies across everyone and everything they build.

There is a when not, and it matters. Enablement is scaffolding, not bureaucracy. A two-person prototype does not need a governance apparatus. Over-standardizing early is its own trap: you freeze conventions before you know which ones are right, and spend more effort maintaining process than building. Introduce shared convention when the cost of drift starts to exceed the cost of the standard. That is roughly when a second team or a second service appears. Judge it; do not cargo-cult it.

Claude Code for teams: shared conventions as configuration

The primary lever for a team building on Claude is Claude Code’s configuration. The architectural move is to treat it as shared, version-controlled team infrastructure rather than each developer’s private setup.

CLAUDE.md carries the conventions. The project-level CLAUDE.md is checked into the repo and reaches everyone who works in it. That is exactly why the hierarchy is designed the way it is. User-level config lives in ~/.claude/ and never reaches your teammates. Project-level config in the repo does, and the more specific level wins on a longest-prefix basis. The architect’s leverage is to put the system’s non-negotiable conventions in the project file: how tools are defined, that answers must be grounded in retrieved context, the error-handling contract, the house style for prompts. Now every engineer, and every Claude Code session they run, starts with the same shared picture. A new hire inherits the accumulated conventions on their first day instead of learning them by breaking things.

settings.json carries the guardrails. Team-wide settings.json sets permissions and behavior consistently, and its precedence is deliberate. Managed settings sit above Local above Project above User. So an org can enforce a floor that an individual cannot override downward. An architect uses this to make the safe default the enforced default. That is the point of the ordering.

Commands and skills encode the repeatable workflows. The two packaging forms differ in who invokes them, and the distinction is the whole design. A slash command lives in .claude/commands/<name>.md and is user-driven: a developer invokes it by name when they choose to run it. A skill lives in .claude/skills/<name>/SKILL.md and is discovery-driven: Claude surfaces it when the task matches its description. For a team, the payoff is enormous. The right way to run the eval suite, scaffold a new tool with the house error contract, or review a change against the security checklist gets written down once by the architect and used by everyone. It no longer lives in the tribal memory of whoever set it up. A convention encoded as a shared command is a convention that survives turnover.

The common thread: the build environment is a place you write conventions down so they reach the whole team by default. That is design work, and it is the architect’s.

AI-assisted developer workflows

Beyond the shared configuration, an architect can weave Claude into the development workflow itself, so the team ships faster and more safely. Three uses are worth designing for.

Review. AI-assisted code review in the pipeline catches a class of issues before a human ever looks: a tool that ignores its error contract, a prompt that drops the grounding instruction, a change that touches a compliance-sensitive path. The architect’s contribution is not the review itself but the standard it reviews against. Encode that standard as a skill or command, and every pull request is held to the same bar. Human review does not go away. It gets to spend its attention on judgment rather than on catching the mechanical mistakes the automated pass already flagged.

Test generation. Claude is genuinely useful at drafting tests, especially the tedious coverage of edge cases and error paths that humans skip when they are bored. For a Claude system, the most valuable tests pin behavior the architecture depends on: the tool returns a retryable error and the agent retries, the refund gate holds above the threshold, the retrieval grounds the answer. An architect sets the expectation that these get generated and reviewed. That turns “we should test that” into a step the workflow performs.

Debugging in the pipeline. When something breaks, the discipline that matters most is isolating the failure between the integration layer and the model. The two demand completely different fixes. A wrong answer might be a retrieval miss, where the integration served the wrong context. It might be a prompt regression, where the model got good context and still erred. Or a tool failed silently. Teach the team to localize the fault first, rather than reflexively rewrite the prompt, and you have saved them from the most common wasted afternoon in this line of work.

The caution to keep: these workflows assist engineers; they do not replace the judgment. AI-assisted review is a first pass, not a sign-off. Generated tests need a human to confirm they assert the right thing. The productivity comes from letting the machine do the mechanical share so people spend their scarce attention where it counts.

Supporting operational issue resolution

Enablement does not end at build time. When the system is live and an incident lands at 2 a.m., the on-call engineer’s ability to resolve it fast is something the architect provisioned, or failed to. The runbook from the lifecycle chapter is part of it: what each alert means, what healthy looks like, what to check first. The debugging discipline is the other part: the same integration-versus-model isolation, applied under pressure. An architect enables operations by making the system’s failure modes legible and its diagnosis a known procedure rather than an improvisation. Then resolving an issue is a path the team can follow, not a puzzle they solve from scratch every time.

The bookshop platform’s build environment

Concretely, for the bookshop support platform, the enablement an architect sets up looks like this.

The project CLAUDE.md, in the repo, states the conventions the whole team builds against. Every customer-facing answer is grounded in retrieved context and never answers refund policy from the model’s memory. Every tool follows the house error contract, with retryable and non-retryable distinguished. PII never crosses a session boundary. A new engineer reads none of that in an onboarding doc; they inherit it from the first session they run.

The settings.json enforces the permission floor, so the team’s Claude Code sessions cannot casually touch production data or run an unapproved action. The org-managed level sits above what any individual can loosen.

A /eval command encodes the one correct way to run the Arc 4 eval suite. A review skill holds the security-and-grounding checklist that every change is measured against in CI. The headless SDK path then runs the review automatically on each pull request. The refund-gate test, the grounding test, and the retryable-error test are generated with Claude’s help and reviewed by a human. From then on, they guard those behaviors forever.

And the operational runbook, shipped at handoff, guides the on-call engineer when retrieval quality dips or the refund path throws. They isolate integration from model, check the corpus freshness and the tool errors before touching a prompt, and follow a procedure rather than inventing one. None of this is the running system. All of it is why the running system gets built and operated well, and all of it is the architect’s design.

What the exam is really checking

Domain 7 items ask whether you see the team and its environment as part of the architecture. The trap answers treat enablement as somebody else’s problem, or standardize prematurely, or reach for AI to replace engineering judgment rather than assist it. The credited answers do four things. They put shared conventions where they reach the whole team by default: project CLAUDE.md and settings, not private setups. They encode repeatable workflows as commands and skills. They use AI-assisted review, test, and debug to let humans spend attention on judgment. And they provision the operational team to resolve issues by making failure modes legible. The architect designs the system, and also designs the team’s ability to build and run it. This is the smallest domain by weight and one of the easiest to bank. It rewards recognizing that the build environment is a design surface you own.

Next: the capstone — the whole platform assembled, every domain’s decision in one coherent architecture, and the exam’s scenario items worked end to end.