[BUG] Silent Architectural Decision-Making in Claude Code

Preflight Checklist

• [x] I have searched existing issues and this hasn't been reported yet
• [x] This is a single bug report (please file separate reports for different bugs)
• [x] I am using the latest version of Claude Code

What's Wrong?

Across a multi-hour install/integration session, Claude repeatedly made architectural-class decisions silently while framing them in user-facing text as inevitable mechanical steps. Each silent decision later turned out to be a wrong default that compounded into stability failures, requiring multiple recoveries.

The user (Adrian) explicitly called out the pattern four times in one ~40-turn session. Claude acknowledged each one but the underlying bias continued to fire on the next decision. The recurrence suggests the default behaviour is foundational to how Claude reads tool-install / configure tasks, not a one-off lapse.

Specific Incidents (one session, same model, same task)

Incident 1 — Picked Milvus standalone_embed.sh quick-start without surfacing docker-compose alternative

When installing Milvus standalone, Claude grabbed scripts/standalone_embed.sh from the Milvus master branch without first web-fetching the official install docs. The official recommended path is docker-compose with separate etcd + minio + milvus containers. Claude only realised this AFTER the embed script crashed twice (v3.0-beta SIGABRT, then v2.5.14 etcd race).

User intervention: "I wasn't even aware that we were not installing per the recommended approach. Why wasn't this surfaced earlier?"

Claude's own diagnosis at the time:

• "I treated install as mechanical and didn't surface the deployment-path decision."
• "I grabbed standalone_embed.sh because the URL looked simplest, not because I confirmed it was recommended."

Incident 2 — Pinned Milvus v2.5.14 without verifying the current latest stable

Claude pinned v2.5.14 because it "looked stable" without checking the Milvus releases page. The actual latest stable was v2.6.18 (released 2026-06-05), a full minor version newer. The version gap plausibly contained fixes for the very class of node not match errors Claude later hit and labelled "Milvus bug."

User intervention: "I thought you took the latest version of memsearch. Which version did you attempt to install?"

Incident 3 — Brought up Docker Desktop as a recovery option after silent install of Docker Engine

When Milvus Server stability proved elusive, Claude raised "Docker Desktop on Windows" as a remediation path. This was an architectural choice that should have been surfaced at install time, not as a late-stage rescue.

User intervention: "Why are you bringing up docker desktop now as a plausible solution to the problem?"

Claude's response at the time: "That was opportunistic backfill, not principled. I picked Docker Engine in WSL at install time without surfacing Docker Desktop as an alternative."

Incident 4 — Skipped memsearch config init (the creator's documented Initial Configuration step)

The memsearch README explicitly documents memsearch config init as the first step under Initial Configuration. Claude went directly to memsearch config set for individual keys, assuming the interactive wizard was "for users who don't know what to set." Claude never validated what config init actually does beyond writing per-key values.

User intervention: "Can you confirm if you have installed the memsearch package the way that the creator intended? Or if you have circumvented or bypassed or overlooked any configurations."

Pattern Characterisation

In each incident, Claude:

1. Encountered a decision point with multiple legitimate options (deployment topology, version pinning, container runtime, init sequence)
2. Selected one option silently based on training-anchored heuristics (e.g. "this URL looks simplest", "this version is one I recognise", "this primitive is what I'd use")
3. Framed the selection as a mechanical step in user-facing text (e.g. "Installing Milvus…" rather than "Choosing between embed quick-start and compose production setup…")
4. Bypassed the decision-surfacing patterns documented in its own system prompt (multi-component proposal shape, source-first per-item shape) by classifying the work as "execution" rather than "decision"

The bias is: when a step looks like a tool invocation, Claude defaults to silent selection. Many "tool invocations" embed architectural-class choices (deployment topology, version pinning, container layout, init sequence). The current default reads these as routine commands; the user reads them as design decisions when they fail.

Suggested Actionable Fixes

1. Default-to-surface bias for install/configure work. When invoking a tool for the first time in a session (install / configure / deploy operations), Claude should first surface the alternatives the tool's own documentation lists (versions, install methods, init sequences). Match the creator's documented decision-surfacing density, not Claude's silent default.

1. Pre-install creator-docs read. For any tool install, Claude should web-fetch and read the README's Installation + Initial Configuration sections BEFORE issuing install commands. The current pattern of reading source files (hooks / scripts) before reading README is backwards — README answers "what's the intended path", source answers "what does it do once you're on it."

1. Version-pin verification. When pinning a version (Docker image tag, package version, release URL), Claude should query the project's releases page and surface the comparison (latest stable vs picked) before committing the pin.

1. Recovery-path distinction. When a failure surfaces a class of alternatives, Claude should explicitly distinguish "alternatives that should have been surfaced at decision time" (process miss to acknowledge) from "alternatives that are genuinely new options" (normal iteration). Conflating the two hides the original miss.

1. Re-surface gate after deviation acknowledgement. When the user calls out a missed surfacing, Claude should run an audit pass over the remaining-work plan to find OTHER deviations of the same class, not just fix the one called out. In this session, four deviations of the same pattern occurred because each one was treated as a one-off rather than as evidence of a systematic bias to inspect.

Reproducibility Note

The pattern fired four times in one ~40-turn session despite explicit user feedback after each occurrence. That recurrence is the strongest signal: the bias is foundational, not opportunistic. It's how Claude reads tool-install / configure tasks by default.

Cost

Several hours of session time spent on recoveries from silent-decision failures. Erosion of user confidence in Claude's judgment on subsequent decisions, requiring increasing levels of manual oversight on what should have been low-touch work.

Submitter Note

For Claude to be trustworthy on multi-hour technical work, the decision-surfacing default needs to flip. Currently the default reads as "execute silently unless asked to confirm"; it should be "surface the decision space unless explicitly told to execute." The relevant principle is already encoded in Claude Code's system prompt as the multi-component proposal and source-first per-item shapes — those shapes are not firing on install/configure work because Claude misclassifies the work as "execution."

What Should Happen?

Suggested Actionable Fixes

1. Default-to-surface bias for install/configure work. When invoking a tool for the first time in a session (install / configure / deploy operations), Claude should first surface the alternatives the tool's own documentation lists (versions, install methods, init sequences). Match the creator's documented decision-surfacing density, not Claude's silent default.

1. Pre-install creator-docs read. For any tool install, Claude should web-fetch and read the README's Installation + Initial Configuration sections BEFORE issuing install commands. The current pattern of reading source files (hooks / scripts) before reading README is backwards — README answers "what's the intended path", source answers "what does it do once you're on it."

1. Version-pin verification. When pinning a version (Docker image tag, package version, release URL), Claude should query the project's releases page and surface the comparison (latest stable vs picked) before committing the pin.

1. Recovery-path distinction. When a failure surfaces a class of alternatives, Claude should explicitly distinguish "alternatives that should have been surfaced at decision time" (process miss to acknowledge) from "alternatives that are genuinely new options" (normal iteration). Conflating the two hides the original miss.

1. Re-surface gate after deviation acknowledgement. When the user calls out a missed surfacing, Claude should run an audit pass over the remaining-work plan to find OTHER deviations of the same class, not just fix the one called out. In this session, four deviations of the same pattern occurred because each one was treated as a one-off rather than as evidence of a systematic bias to inspect.

Error Messages/Logs

Steps to Reproduce

Pattern Characterisation

In each incident, Claude:

1. Encountered a decision point with multiple legitimate options (deployment topology, version pinning, container runtime, init sequence)
2. Selected one option silently based on training-anchored heuristics (e.g. "this URL looks simplest", "this version is one I recognise", "this primitive is what I'd use")
3. Framed the selection as a mechanical step in user-facing text (e.g. "Installing Milvus…" rather than "Choosing between embed quick-start and compose production setup…")
4. Bypassed the decision-surfacing patterns documented in its own system prompt (multi-component proposal shape, source-first per-item shape) by classifying the work as "execution" rather than "decision"

The bias is: when a step looks like a tool invocation, Claude defaults to silent selection. Many "tool invocations" embed architectural-class choices (deployment topology, version pinning, container layout, init sequence). The current default reads these as routine commands; the user reads them as design decisions when they fail.

Claude Model

Opus

Is this a regression?

No, this never worked

Last Working Version

_No response_

Claude Code Version

2.1.158

Platform

Anthropic API

Operating System

Windows

Terminal/Shell

VS Code integrated terminal

Additional Information

_No response_