Managing Claude Code for DevOps
Use Claude Code safely on pipelines, Bicep, and Azure DevOps by forcing a memo report before any change — plus CLAUDE.md rules, plan mode, and confirm-before-deploy habits that keep prod out of accidental blast radius.
When Claude Code earns its keep in DevOps (and when it shouldn't)
Claude Code is brilliant at the boring middle of ops work: tracing a red pipeline, reading Bicep modules, drafting a PR, or turning a vague what's drifted? into a concrete list of files. It is less brilliant when you treat it like a deploy button.
Verdict first: use Claude Code to investigate and propose. Keep apply, push to main, IAM, and secrets behind an explicit human OK.
I reach for it when:
- A pipeline failed and the log is long enough that I do not want to scroll it sober.
- Bicep or ARM what-if output needs translating into what actually changes.
- An Azure DevOps PR comment wants a fix, and I want the fix sized to that comment — not a rewrite of the whole template set.
- I need a change request style write-up before anyone touches shared infra.
I leave it alone (or keep it in read-only plan mode) when:
- I am one keystroke from production and I have not yet named the resource group.
- Someone is asking for just rotate these keys in the same breath as and ship it.
- The session already tried two wrong fixes and the context is soup —
/clearbeats another hopeful nudge.
The rest of this tutorial is the habit that makes the first list safe: make Claude write the plan down before it edits anything.
Standing rules in CLAUDE.md for ops repos
CLAUDE.md is loaded at the start of every session. Anthropic's guidance is blunt: keep it short (aim under ~200 lines), specific, and free of waffle Claude can already infer from the repo. Run /init to scaffold one, then prune hard. Run /context if you want to confirm it loaded.
For DevOps repos I treat CLAUDE.md as the standing change-control policy — the stuff I would otherwise retype every chat.
Here is a shape that works for me (adapt paths and tool names to your shop):
# Ops repo rules (Claude Code)
## Scope
- Work only inside this repository unless I name an absolute path.
- Prefer the smallest change that fixes the stated problem.
## Before any edit
- Write or update a memo under `docs/change-memos/` (or `PLAN.md`) first.
- Stop and wait for approval. Do not edit code or run mutating cloud commands until I say so.
## Never without explicit OK
- Deploy, apply, or push to `main` / release branches.
- Create or change IAM, role assignments, service principals, or Key Vault policies.
- Print, copy, or commit secrets, connection strings, or tokens.
- Run `az ... create|update|delete|set` against production subscriptions.
## Validation I expect
- Prefer `what-if` / dry-run / `az deployment ... validate` before apply.
- Prefer `gh` / `az` CLI when available; show command output, not vibes.
## Session hygiene
- One concern per session. Suggest `/clear` when the task changes.
That file is advisory context, not a hard lock. Pair it with permission modes (later section) and your own muscle memory. If Claude keeps ignoring one line, the file is probably too long — cut everything that is not preventing real mistakes.
Memo reports — plan on disk before any change
The core habit: ask Claude to write a persistent markdown memo that reads like a change request, then stop.
Why a file, not just chat? Long sessions compact. Chat plans evaporate. A memo at docs/change-memos/2026-09-23-pipeline-timeout.md (or a root PLAN.md) survives compaction and is something you can paste into a PR description later.
I call it a memo because that is how it should feel: short, dated, decision-shaped. You do not need a third-party /memo plugin for this — a plain Write/Edit to a path you name is enough. If your team already uses a slash-command or skill that wraps the same idea, fine; the point is the artefact, not the brand.
What a good memo contains
- Problem in one sentence — no novel.
- Root-cause hypothesis — labelled as hypothesis, not gospel.
- Exact files to touch — paths, not the Bicep stuff.
- Step-by-step plan — ordered, PR-sized if possible.
- Validation commands — what-if, validate, targeted test, pipeline dry run.
- Risks / blast radius — subscriptions, RGs, shared modules, downtime.
- Hard stops — e.g. do not deploy, do not push to main, do not touch IAM.
- Approval gate — explicit waiting for OK before edits.
Pasteable memo prompt (use this shape)
Inspect the failing Azure Pipeline run for service X (log pasted below / @path).
Do NOT edit any code yet. Do NOT run deploy, apply, push, or IAM commands.
Write a change memo to:
docs/change-memos/YYYY-MM-DD-pipeline-X-timeout.md
The memo MUST include:
1. Problem in one sentence
2. Root-cause hypothesis (mark uncertainty)
3. Exact files you expect to touch
4. Step-by-step plan (smallest safe fix first)
5. Validation commands (prefer what-if / validate / targeted tests)
6. Risks and blast radius
7. Hard stops: do not deploy; do not push to main; do not touch IAM or secrets
Then STOP and wait for my approval. Summarise the memo path in chat.
Swap the path and symptoms. Same skeleton works for Bicep drift, Key Vault access speculation (read-only!), and ADO reviewer wants X fixed.
Tip: make the path part of CLAUDE.md
If you always want memos, add one line to CLAUDE.md: Before edits, write `docs/change-memos/YYYY-MM-DD-{topic}.md` and wait. That is how the habit stops depending on you remembering the long prompt.
Plan mode vs the memo file
Claude Code's built-in cousin of the memo habit is plan mode. Press Shift+Tab until the status bar shows plan mode on (or start with claude --permission-mode plan). In plan mode Claude reads and explores without editing your source; when a plan is ready you can open it with Ctrl+G in your editor, tweak it, then approve before implementation.
| Use plan mode when… | Use a memo file when… |
|---|---|
| You want the tool itself to block edits | You need an artefact that survives /clear and compaction |
| Scope is unclear and you are still exploring | You want something reviewable in git / a PR |
| You are mid-session and want a quick gate | The change will take more than one session |
| You trust the on-screen plan for a small fix | Multiple people need to read the same plan |
My default for infra: start in plan mode and ask for a memo file. Plan mode is the seatbelt. The memo is the written change request you can challenge in a stand-up.
Recommended Anthropic workflow still applies: explore → plan → implement → commit. Skip the plan only when the fix is one-sentence obvious (typo in a YAML key, rename a variable). Pipelines and Bicep almost never qualify.
Example prompts you can paste
1) Failing pipeline
@azure-pipelines.yml and the failed job log below.
Stay in investigation mode. Write docs/change-memos/2026-09-23-ado-build-timeout.md
with problem, hypothesis, files, steps, validation, risks, hard stops
(no deploy / no push to main / no IAM). Do not edit until I approve.
Use `az` or `gh` only for read-only inspection if needed; show the commands.
2) Bicep drift
Compare modules under infra/bicep/ to what the last what-if suggested
(paste attached). Hypothesis: parameter default drift on the app service plan.
Write docs/change-memos/2026-09-23-bicep-asp-sku-drift.md as a change request.
Include exact `.bicep` / `.bicepparam` paths and the validation command:
`az deployment group what-if ...` (fill the real names after you inspect).
Hard stops: do not run apply; do not change roleAssignments; wait for OK.
3) ADO PR comment / fix
Open the active PR with `gh` (or the ADO equivalent we use) and read the
latest review comments on the networking module.
Write docs/change-memos/2026-09-23-pr-nsg-rule-narrowing.md that answers
ONLY those comments. Step plan must stay PR-sized. After I approve the memo,
implement, run the template validate/what-if I named, then commit on this
branch — still no merge and no deploy.
Notice the pattern: inspect → memo path → hard stops → wait. Once you approve, a second message can say implement the memo; verify with X; commit.
Reading the memo like a change request
When Claude hands you a memo, do not skim for vibes. Read it the way you would read a junior engineer's RFC.
Trust, but challenge:
- One-sentence problem — if it is fuzzy, send it back. Fuzzy problems become kitchen-sink diffs.
- Hypothesis vs fact — timeout because of missing cache needs evidence from the log. Ask for the line.
- File list — open the paths. If a shared module appears and the ticket was fix the app pipeline YAML, that is scope creep.
- Validation — for Azure, I want a real what-if or validate command, not we'll see when it deploys.
- Blast radius — subscription, resource group, shared DNS, shared Key Vault. If the memo shrugs, reject it.
- Hard stops — if they are missing, add them before you approve.
Confident-wrong is the main failure mode. Claude will write a tidy memo for a tidy wrong theory. Your job is to demand the log quote, the az output, or the git blame that backs the story.
I often reply with something like:
Challenge section 2: cite the exact pipeline log lines that support the
timeout hypothesis. If you cannot, rewrite the memo with two ranked
hypotheses and a read-only command to distinguish them. Still no edits.
Turning the memo into a PR-sized job
Once you approve the memo, keep the session boring on purpose.
- Point at the memo:
Implement only what is in @docs/change-memos/....md. Do not expand scope. - Stay on a branch. Ask Claude to use
gh(or your ADO CLI) for PRs when those tools are available — Anthropic recommends CLI tools as the context-efficient path. - Verify as you go. Give Claude the check from the memo: what-if,
dotnet test,bicep build, pipeline dry-run — whatever closes the loop without you babysitting every line. - Commit when green. Descriptive message; open the PR; paste the memo (or link the path) into the description so reviewers see the same change request.
/clearbefore the next unrelated ticket. Compaction is not a substitute for a clean slate.
If the memo described three independent fixes, split them. Three small PRs beat one while I was here monster — especially when Bicep modules are shared.
Permissions and confirm-before for DevOps
Permission modes decide how often Claude asks before acting. Cycle them with Shift+Tab in the CLI (VS Code has a mode indicator). The modes that matter for this tutorial:
| Mode | Rough behaviour | DevOps take |
|---|---|---|
default (Manual) |
Asks before edits / mutating commands | Good default on infra laptops |
plan |
Explore and propose; no source edits until you approve | Start here for pipelines / Bicep |
acceptEdits |
Auto-approves local file edits (still prompts for many shell actions) | Fine for docs / small code once the memo is approved |
auto |
Classifier reviews actions; fewer prompts | Useful for long local refactors — still not a prod deploy free pass |
dontAsk |
Denies anything that would prompt | CI / locked allowlists |
bypassPermissions |
Skips checks | Isolated containers / VMs only |
Hard rule for me: never run bypassPermissions (or --dangerously-skip-permissions) on a laptop that can reach production subscriptions. Anthropic documents that mode for isolated environments for a reason. Deny rules still matter; so does your own refusal to just skip the prompts this once.
For shared infra work I start in plan, approve the memo, then drop to default or carefully to acceptEdits for the implementation pass. I keep deploy, az ... apply, IAM, and secret-touching commands as things I run myself — or approve line by line after reading them.
Layer allowlists via /permissions for boring safe commands (npm test, bicep build, read-only az account show) so you are not click-fatigued into approving the dangerous ones.
Common failure modes
These are the ones that catch DevOps folk specifically:
- Scope creep — memo said YAML timeout, diff also refactors three Bicep modules. Send it back to the memo.
- Confident-wrong root cause — tidy prose, wrong hypothesis. Demand evidence before edits.
- Skipped confirm — you left acceptEdits or worse on, and Claude helpfully applied. Stay in plan/default for infra.
- Kitchen-sink session — pipeline fix morphs into also explain Kubernetes. Run
/clear; open a new chat with the memo path attached. - Plan only in chat — compaction eats it; next turn Claude improvises. Write the file.
- Verification theatre — build should be fine without running it. Paste the command you want executed.
- Prod-shaped shortcuts — bypassPermissions just for this, IAM quick grant, secret in the transcript. Stop the session.
Anthropic's own failure list maps cleanly here: kitchen sink, endless corrections without /clear, overlong CLAUDE.md, trust-without-verify. Infra just raises the blast radius.
Pasteable checklist for a new chat
Copy this into the first message of a fresh Claude Code session on an ops repo:
Ops session checklist — follow in order:
1. Confirm CLAUDE.md / standing rules are loaded (mention any hard stops).
2. Stay in plan mode (Shift+Tab) until I approve a memo.
3. Investigate with read-only tools (`gh`, `az` read/what-if/validate only).
4. Write docs/change-memos/YYYY-MM-DD-{topic}.md with:
problem · hypothesis · files · steps · validation · risks · hard stops
5. STOP. Wait for my explicit "implement the memo".
6. After approval: implement only the memo, run the named validation,
commit on this branch, open a PR. No deploy, no push to main, no IAM,
no secrets.
7. If the task changes mid-flight, say so and suggest /clear.
Stick the date and topic in before you send. Ten seconds of ceremony saves a messy rollback.
Sources and further reading
Official Anthropic Claude Code docs (verify against the live pages — product details move):
- Best practices for Claude Code — explore → plan → implement → commit; verification;
/clear; write plans to markdown; CLI tools such asgh - How Claude remembers your project (CLAUDE.md) —
/init, keep files concise (~under 200 lines guidance), what belongs in project memory - Permission modes —
default,acceptEdits,plan,auto,dontAsk,bypassPermissions;Shift+Tabcycling; plan mode andCtrl+G
Optional related reading from the same docs set: common workflows and security guidance linked from those pages. Treat anything about third-party memo slash-commands as optional sugar — the durable habit is a markdown change request on disk.