Good Architecture Deletes the Signals Your Agent Depends On

# The problem in one sentence Similarity search answers "what looks like this?" but agents need "what will break if this changes?". Those are different questions and require different signals.

# Why similarity retrieval fails

DORA's 2025 State of AI-assisted Software Development report is cited: developers save time during generation but re-spend it on auditing and verification, and about 30% of developers reported little or no trust in AI-written code. The author isolates one structural cause: tooling expects overlap in vocabulary that architecture intentionally removes.

# Two sets that matter The article separates two sets of files:

• The resemblance set: files that look like the query. Retrieval is optimized for this.
• The impact set: files that will break when the target changes. Agents need this.

These sets overlap less than tooling assumes. For example, a theme file and a button may share no words, yet changing the theme contract breaks the button. Conversely, two validators written at different times may look alike and confuse an agent into reconciling them incorrectly.

# How good architecture hides signals

The author lists real shared artifacts across product scopes: visual primitives, a theme, a build environment, a running widget in another product, and a backend service in a different product. The more valuable and cross-cutting the artifact, the less it resembles its consumers. Those are exactly the things a code-change impact analysis must find, and similarity search performs worst on them.

# Why imports and package boundaries don't solve it Reading imports helps, but it breaks two ways and gets worse as systems become better assembled. Imports may exist but be followable only through build-time artifacts, package resolution, or monorepo boundaries that aren't indexed. Or imports resolve to a published package where consumer text is absent. A change that touches a build environment or runtime service can reach many components, yet none of those consumers contain text resembling the environment files.

# Practical implication

# Bottom line Good architecture removes the textual signals similarity-based agents rely on. If you want agents that change code safely, you must give them tools that find dependency impact rather than similar text.