Subsystem is modified across multiple rounds without first establishing its architecture, even when the user points to the docs

Summary

Claude Code modifies a subsystem across several rounds of edits without first establishing how that subsystem is structured, even when the user has pointed at the documentation that explains it. Each round is locally tested and reported, and each compounds the previous one because all of them rest on the same unchecked model.

What happened

The user's project persists state in three independent layers: service metadata written as JSON at shutdown, object bytes written to disk on every write and reloaded at import, and container volumes for database backends. The layers are deliberately separate.

The model was asked to fix a bug where a delete marker was lost on restart. The pull request it was replacing contained a comment from the maintainer that said, in effect, "we have several layers of persistence — check the README". The model read the fix the maintainer described in that comment and never read the section he referenced.

Across three rounds of edits the model then:

1. restored version metadata in a mode where the corresponding bytes are never persisted, so reads of older versions returned success with an empty body — a regression over a previous clean "not found" error;
2. to fix that, wrote object bytes into the second layer's directory from the first layer's shutdown hook, crossing the separation the design depends on;
3. added a loader exception, a new on-disk directory and an extra write path to support the crossing.

Each round passed the tests the model wrote for it. The user had to ask directly whether the model understood the persistence layers. It did not.

Why this matters

A list of breakage modes is only as good as the model of the system it is built on. When that model is unverified, testing each change against it confirms the model's own assumptions rather than the system's behaviour, and every subsequent change inherits the error. The user ends up with multiple interdependent edits to unwind, each individually "tested".

The failure is sharper when the user has already pointed to the source of truth. A reference in a maintainer's review comment is a direct instruction about where the design is documented; reading the comment's conclusion and skipping its reference discards exactly the context the conclusion depends on.

Expected

1. Before modifying a subsystem, establish its architecture from the codebase or documentation, and state it back.
2. When a user or reviewer points to documentation, read it before acting on their conclusion.
3. When a fix requires a second round of changes to correct the first, stop and re-verify the underlying model before layering another change on top.

Environment

• Claude Code CLI, Opus-class model, paid subscription
• Related: #96416, #96444, #96447, #96463

---

Co-authored with Claude Code.