Four Design Questions

## Full reference: the four design questions

Every coding-agent architecture — Claude Code, LangGraph, Devin, SWE-Agent, Aider, whatever you are building — answers the same four questions. The answers are not interchangeable. This pack is the 2-minute orientation; every other dive-sourced pack in the catalog is a zoom-in on one row.

### 1. Where does reasoning live?

**The question:** How much decision-making goes into the model, and how much into deterministic harness code?

**Claude Code's answer:** Roughly 1.6% of the codebase is AI decision logic; 98.4% is harness — permission gates, context management, tool routing, recovery logic. The agent loop is a simple while-loop. Engineering complexity lives around it.

**Alternatives:** LangGraph pins reasoning into explicit state graphs (developer controls flow, easier to debug, constrains the model). Devin uses multi-step planners and task trackers (more reliable for complex workflows, scaffolding becomes maintenance burden).

**Implications for your agent:**
- More capable models need less scaffolding — if you target Claude 4.6 / GPT-5, over-scaffolding becomes tech debt.
- Regulated domains (finance, healthcare) may justify explicit state graphs for auditability even at the cost of model headroom.
- If you find your harness code is <5% of your codebase, you are probably under-investing in determinism; expect flakiness.

### 2. How many execution engines?

**The question:** Do all interfaces (CLI, SDK, IDE) share one engine, or does each surface get its own?

**Claude Code's answer:** One `queryLoop` for every surface — interactive CLI, headless (`claude -p`), Agent SDK, IDE. `QueryEngine` is a conversation wrapper, not the engine itself.

**Alternatives:** Mode-specific engines per surface (common in products that bolt on an IDE after shipping a CLI; leads to behavior drift where the CLI does one thing and the IDE does another).

**Implications for your agent:**
- A single engine makes every regression reproducible on every surface. Diverging engines produce "works on CLI, broken in IDE" tickets.
- Shared engine forces shared permission, context, and recovery semantics — a feature, not a bug.
- If you already have two engines, treat consolidation as a top-3 backlog item; the drift cost compounds.

### 3. What is the default safety posture?

**The question:** How do you prevent the agent from doing harmful things by default?

**Claude Code's answer:** Deny-first. The order is deny > ask > allow. A broad deny always overrides a narrow allow. Seven independent safety layers stack on top — any one can block. Trust is never restored on resume.

**Alternatives:** Container isolation (SWE-Agent, OpenHands) — strong coarse boundary, everything inside the container is allowed. Git rollback (Aider) — lightweight, only protects file changes, doesn't stop network or shell side effects. Approval-only (basic chatbots) — simple but users approve 93% of prompts without reading.

**Implications for your agent:**
- Copying the posture without the layers that make it work is worse than picking a simpler posture. If you pick deny-first, you also need pre-filtering, classifier, sandboxing, and the six other layers — see `seven-safety-layers`.
- Container isolation looks like a shortcut but commits you to a rebuild every time a permission changes.
- Whichever posture you pick, name the failure mode. Deny-first fails on approval fatigue and shared-token-budget bypasses. Containers fail on egress. Rollback fails on non-file side effects.

### 4. What is the binding resource constraint?

**The question:** Which resource runs out first, and what shapes every architectural decision downstream?

**Claude Code's answer:** The context window. ~200K tokens (older models; up to 1M on 4.6 series). Five compaction strategies run sequentially before every model call — Budget Reduction → Snip → Microcompact → Context Collapse → Auto-Compact. Context is the *binding* constraint; lazy loading, deferred tool schemas, and subagent summary-only returns all exist because context is scarce.

**Alternatives:** Compute budget (when you're running a local model and tokens are cheap but GPU time is the bottleneck). Explicit scratchpad (when the harness externalizes state to disk and context is only the working set).

**Implications for your agent:**
- **Context budget is not compute budget.** Agents with a big compute budget and a small context window need compaction; agents with a big context window and a small compute budget need caching and parallelism. Do not confuse the two.
- Pick one binding constraint and design to it. If you pick context, every feature must answer "what does this cost in tokens per turn" before shipping.
- If your answer is "we don't have one yet," measure — a p95 turn token count and a session-peak token count are the minimum.

### How to use this pack in a design review

At the top of the design doc, write:

> **Our four answers:**
> 1. Reasoning lives in: [model / harness / explicit graph] — because [one line].
> 2. Execution engines: [one / N, and why].
> 3. Safety posture: [deny-first / container / rollback / approval] + known failure mode.
> 4. Binding constraint: [context window size / compute budget / scratchpad] — measured ceiling is [number].

If you cannot fill a row, the review is not ready. Send the author to the deeper pack for that row:
- Row 1 → `agent-design-space-six-decisions` or `pattern-decision-tree`
- Row 2 → `turn-execution-pipeline`
- Row 3 → `seven-safety-layers` and `injection-surface-audit`
- Row 4 → `nine-context-sources` or `claude-code-guide`

### Anti-patterns

- **Copying Claude Code's posture without its layers.** Deny-first without the seven-layer stack degrades into approval fatigue.
- **Two execution engines with no consolidation plan.** Drift compounds; every feature now costs 2×.
- **Treating context budget as compute budget.** You end up with a caching strategy when you needed compaction, or vice versa.
- **Writing the architecture diagram before answering these four.** Diagrams without stated constraints document a guess.

Sourced from VILA-Lab/Dive-into-Claude-Code (CC-BY-NC-SA-4.0, arXiv 2604.14228). Paraphrased with citation; Claude Code percentages and layer counts quoted from the paper's §Four Design Questions and §Key Highlights sections.