Architecture & Research Prompts

Agents are anchoring machines. Ask one "how should I build X?" and it emits a single confident design in seconds — usually the most common pattern in its training data, not the best fit for your constraints. It will then defend that design when questioned, and every follow-up you write inherits its assumptions. The prompts on this page exist to break that anchor: force multiple options, force evidence before opinions, force a plan before code.

What stays yours regardless of prompting: the decision. These patterns make the agent generate and analyze options; picking one is not delegable.

Architecture option prompts

Two hard rules: demand N options with a tradeoff table, and forbid code. The first defeats anchoring; the second stops the agent from making the decision for you by shipping option 1 as a "sketch" you'll feel committed to.

Weak:

What's the best way to add background job processing to our
Node.js app?

You'll get BullMQ, a Redis dependency, confident prose, and probably a code sample — one option, presented as the answer, with your actual constraints (team size, ops budget, existing infra) never consulted.

Strong:

We need background job processing for our Node.js invoicing service.
Read first: src/app.ts, docker-compose.yml, package.json, and
docs/ARCHITECTURE.md — then confirm what infra we already run.

Constraints:
- Jobs: PDF generation (~2k/day, CPU-bound, 5–30s) and email
  sends (~10k/day, IO-bound). Both must survive process restarts.
- We already run Postgres. We do NOT currently run Redis.
- Two-person team; minimizing operational surface outranks
  throughput. Volumes above are 12-month projections.

Produce exactly 3 options (at least one using only infra we
already run). For each: how it works in our stack (prose, no code),
operational burden, failure modes and job-loss scenarios, migration
path out of it if we outgrow it.

Then a tradeoff table: option × ops burden, delivery guarantees,
throughput ceiling, dep footprint, exit cost.

End with a recommendation AND the strongest argument against your
own recommendation.

Do not write any implementation code. Do not scaffold anything.

The closing demand — argue against your own recommendation — is cheap and disproportionately revealing: a genuinely weak recommendation usually can't survive the agent's own counterargument, and you get to watch it fail before writing any code.

Why the first proposal must never win by default. The first design is drawn from pattern frequency, not from your constraints — for job queues that means Redis + BullMQ even when a Postgres-backed queue (pg-boss, or a jobs table) eliminates an entire piece of infrastructure for a two-person team. Agents also exhibit plausibility symmetry: they argue for the mediocre option exactly as fluently as for the good one, so confidence carries zero information. You extract signal by forcing comparison, not by asking "are you sure?" — the answer to which is always a polite re-anchor. The full decision workflow is in Exploring Options; record what you pick in a decision record.

Research-before-build prompts

For any task touching unfamiliar territory — a subsystem you didn't write, a library choice, an external API — make research a separate deliverable before any implementation session. Splitting matters for two reasons: an agent allowed to build while researching will start building at the first plausible finding, and a findings doc survives the context window — you can review it, correct it, and hand it to a fresh session (docs as memory).

Codebase survey — before touching a subsystem:

Research task — produce docs/research/notifications-survey.md.
Write NO code and change NO files outside docs/research/.

Survey how notifications currently work in this codebase:
- Every file that sends or formats notifications (list paths).
- The data flow from trigger to delivery — as a mermaid
  sequence diagram.
- Config and env vars involved.
- Inconsistencies between notification types (there are at
  least two competing patterns; find them).
- The 5 files a "add SMS notifications" change would touch,
  with one line each on why.

Cite file paths and line numbers for every claim. If something
is ambiguous, list it under "Open questions" instead of guessing.

Library evaluation — same shape, different subject: name the candidates (or ask for candidates plus a search), fix the criteria (maintenance activity, bundle/binary size, license, API fit against a specific file in your repo), and demand the same cite-or-open-question discipline. The verification step is non-negotiable: agents hallucinate library APIs at exactly the moment their confidence peaks, so require version numbers and have any load-bearing claim checked against the library's actual docs — see Hallucination & False Confidence.

Weak vs. strong in one line each:

Which date library should we use?

Evaluate date-fns vs dayjs vs Temporal-polyfill for replacing
moment in src/lib/formatting.ts. Criteria: bundle size impact on
our Vite build, TZ handling for the scheduling code in
src/scheduling/, maintenance activity in the last 12 months,
migration effort (count our moment call sites first). Output a
table + recommendation to docs/research/date-lib.md. Verify API
claims against current docs — state the version you checked. No code.

Evaluate the findings doc, not the vibe: spot-check three cited file paths and one library claim. If any citation is wrong, the doc is untrustworthy and you say so — the redo prompt is "re-verify every claim; I found these errors: …".

Planning prompts

Between research and implementation sits the plan: a reviewable list of steps, files, and risks that you approve before the first line of code. Plans are where you catch the wrong approach at a cost of minutes instead of hours.

In Claude Code, use plan mode (Shift+Tab): the agent can read anything but write nothing until you approve the plan. It's the structurally-enforced version of this pattern — prefer it over politeness-based "please don't code yet", which degrades as context fills. In other tools, the prompt clause below approximates it.

Weak:

Plan how to add multi-currency support, then implement it.

"Then implement it" nullifies the plan — the agent writes a token plan and rolls straight into code with no approval gate. Never combine plan and build in one prompt.

Strong:

Plan mode only — produce a plan, do not implement.

Task: add multi-currency support to the invoicing service
(spec: docs/specs/multi-currency.md).

The plan must contain:
1. Ordered steps, each independently shippable and ≤ ~200 lines
   of diff.
2. Per step: files touched, and the risk if that step is wrong.
3. Schema changes stated exactly (columns, types, backfill plan).
4. What you will NOT do, per the spec's out-of-scope section.
5. Assumptions as A1, A2, … — anything the spec doesn't pin down.
6. The single step most likely to go wrong, and how we'd detect
   it went wrong early.

Stop after the plan. I will approve, amend, or reject before any
implementation begins.

Review the plan against three questions: are steps genuinely incremental (each leaves the system working), does any step hide a decision you should be making (item 3 exists because schema changes love to hide inside "update the model"), and do the stated assumptions match reality — a wrong A-item caught here is the cheapest bug you'll ever fix. Then implement step by step with checkpoints (Large Tasks).

Related

• Exploring Options — the full decision workflow around option prompts.
• What Not to Delegate — why the decision itself stays human.
• Decision Records — capturing the choice so future sessions don't relitigate it.
• Prompt Library: Design — copyable architecture and research prompts.
• Prompt Library: Project & Planning — copyable planning prompts.
• Hallucination & False Confidence — why research output needs spot-checks.