If you’ve ever said “Sure, I’ll let the assistant help”… and then watched it confidently rewrite half your repo, you’ve met the core problem of AI-assisted dev work:
- The model is eager to act.
- Your codebase is fragile.
- Your attention is limited.
The fix isn’t “use the AI less.” It’s to change the mode you’re using it in.
I call this Shadow Mode Prompting: you ask the model to do the work as if it could ship it, but you explicitly constrain the output so it can only produce reviewable proposals — never direct actions.
Shadow mode is how you get the speed of an assistant with the safety of a cautious teammate.
What “shadow mode” means
In shadow mode, the assistant is not your co-pilot at the controls. It’s your co-pilot sitting behind you, narrating what it would do:
- It can propose a plan.
- It can point to files and functions.
- It can draft diffs.
- It can enumerate commands.
…but it cannot execute anything, and it must treat uncertainty as a first-class output.
The win: you reduce blast radius while keeping momentum.
When shadow mode is the right default
Shadow mode shines when:
- The change touches multiple files (refactors, upgrades, migrations).
- You’re not sure about requirements (API edge cases, product intent).
- You’re operating under risk (prod hotfixes, security, payments).
- You want learning, not just output (you’ll maintain this later).
If the task is trivial (rename variable, write a small helper), you can leave shadow mode. But for anything “repo-shaped”, start in shadow mode.
The 4-part shadow mode contract
A good shadow mode prompt has four ingredients:
- Goal — what success looks like.
- Boundaries — what it must not do (no actions, no guessing).
- Artifacts — the format you want (plan, diffs, checklist).
- Decision points — where you want it to stop and ask.
Here’s a reusable template.
You are in SHADOW MODE.
Goal:
- <what I’m trying to accomplish>
Context:
- Repo: <stack, constraints, relevant modules>
- Current behavior: <what happens now>
- Desired behavior: <what should happen>
Boundaries:
- Do not assume you can run commands.
- Do not claim tests pass.
- If you are unsure, say "UNCERTAIN" and list what you need.
Deliverables (in order):
1) A step-by-step plan (max 10 steps)
2) A "diff-first" proposal: list files, and for each, the exact changes
3) A verification checklist I can run locally (commands + what to look for)
4) Stop and ask me for approval before proposing any additional changes
Two things matter here:
- “Do not claim tests pass.” This single line kills a lot of subtle overconfidence.
- “Diff-first proposal.” You want changes that are easy to review, not a wall of rewritten code.
Concrete example: upgrading a dependency safely
Let’s say you want to upgrade a major framework version. The dangerous path is: “Upgrade X to vNext and fix errors.” That invites sweeping, unreviewable edits.
Shadow mode version:
You are in SHADOW MODE.
Goal:
- Upgrade Next.js 14 → 15 with minimal changes.
Context:
- App Router is used.
- We have custom middleware.
- We deploy via Docker.
Boundaries:
- Propose changes as diffs only.
- Don’t invent files or config.
- Flag any breaking changes as "RISK".
Deliverables:
1) Upgrade plan
2) Proposed diffs (package.json, lockfile notes, config)
3) Verification checklist
What you’re looking for in the output:
- A small set of files (package.json, next.config.js, middleware).
- A clear set of breaking changes (RISK tags).
- A checklist (build, unit tests, a couple of key routes).
If it proposes touching 30 files, that’s a smell. Ask it to narrow scope:
“Reduce scope: only changes required to build and start. Defer refactors.”
Shadow mode for debugging: the “triage + hypotheses” pattern
Debugging is where shadow mode becomes a superpower, because the assistant can generate hypotheses without pretending it has evidence.
Prompt:
You are in SHADOW MODE.
Bug:
- Users sometimes get logged out after 30–60 minutes.
Evidence:
- Session cookie is set.
- We use Redis for session storage.
- Logs show occasional 401s from /api/me.
Deliverables:
1) Triage questions (max 7)
2) Top 5 hypotheses with confidence scores
3) For each hypothesis: 1–2 verification steps
The assistant should say things like:
- “If Redis TTL is shorter than cookie maxAge, you’ll see intermittent logouts.”
- “If /api/me calls happen from a different subdomain, SameSite may block cookies.”
…and crucially, it should label uncertainty. You’re using it to widen your search, not to declare the answer.
The “proposal queue”: turning shadow mode into a workflow
Shadow mode really clicks when you treat proposals like a queue:
- Ask for a plan + diffs.
- Pick one small change.
- Apply it manually (or via a small patch).
- Run the verification checklist.
- Repeat.
This mirrors how you’d work with a careful junior dev: small PRs, frequent checks, and clear stop points.
If you want an even tighter loop, add an explicit constraint:
“Only propose changes that fit in a single PR (≤ 200 LOC changed).”
Common failure modes (and how to prompt around them)
1) The assistant gets vague
If you get generic advice, force file-level specificity:
“List the exact files and the exact edits. If you can’t, say UNCERTAIN and explain why.”
2) The assistant rewrites too much
Cap the change budget:
“Max 3 files. Max 150 changed lines. If more is needed, split into phases.”
3) The assistant invents APIs
Add a strict grounding rule:
“Only reference symbols that exist in the code I provided. Otherwise ask.”
4) The assistant forgets your constraints later
Restate the contract at the bottom:
“Reminder: you are in SHADOW MODE. Deliver diffs + checklist only.”
A tiny checklist to keep shadow mode honest
Before you act on any proposal, check:
- Did it name files and specific changes?
- Did it label RISK and UNCERTAIN items?
- Does the checklist include one fast test (lint/unit) and one realistic test (run app / hit endpoint)?
- Is the scope small enough that you can review it in under 10 minutes?
If not, push back. The whole point is to keep the work shippable.
The takeaway
Shadow mode isn’t about distrusting the assistant — it’s about building a workflow where trust is earned per step.
Use shadow mode as your default for anything that could break the repo. Ask for plans, diffs, and verification checklists. Keep scope small. Make uncertainty explicit.
You’ll ship faster — and you’ll sleep better.
Top comments (0)