Good Architecture Eliminates Signals Agents Depend On
How system design impacts AI-assisted code retrieval and modification.
1AI's Code Retrieval Gap
AI tools like Copilot and Claude Code struggle to identify dependencies in codebases because the necessary information isn't stored in repositories they can access. This gap leads to inefficiencies in code modification and auditing, as developers spend significant time verifying AI-generated changes.
2Component-Based Systems
In component-based systems, dependencies are often hidden. For example, a chat widget in a learning platform might rely on a separate retrieval service. Changing the widget doesn't reveal its impact on the platform, as the connection isn't explicitly documented in the code.
3Similarity vs. Dependency
Code retrieval systems focus on finding code that resembles a query, but this approach misses dependencies. A theme file and a button may share no vocabulary, yet changing the theme can break the button. This mismatch highlights the limitations of similarity-based indexing.
4Contract-Based Design
Proper engineering involves creating neutral contracts between components. For example, an authentication kit can switch providers without altering consumer code. This design removes vocabulary overlaps that similarity indexes rely on, making dependencies harder to detect.
5Build Environment Impact
A build environment affects compilation, dependency resolution, and test setup across multiple components. However, these dependencies aren't reflected in the code's text, rendering similarity scores useless for identifying critical relationships.
6Service Reuse Challenges
Reusable services and backends often resemble their consumers the least, making them difficult to discover. This disconnect leads to unnecessary rebuilding of services that already exist but aren't visible through similarity indexes.
7Import Limitations
Reading imports helps identify dependencies, but this approach breaks in well-assembled systems. Imports may survive but become unfollowable, or disappear entirely in cases where applications and services are assembled rather than imported.
8Platform Assembly
Platform components assemble applications and services without explicit imports. For example, a React application and Node services might be named in a configuration array, making their dependencies invisible to tools like Nx unless manually declared.
9Version Records
Dependencies are computed and stored as version records during the build process. These records declare which units ship together, providing a blast-radius signal for changes. However, they don't capture assumptions about response shapes or deploy-time agreements.
10Agent Query Capabilities
Agents can query component dependencies recorded during version creation, preventing duplication and implicit contract changes. This capability ensures shared components are reused correctly, avoiding the drift seen in separate implementations.
11Multi-Team Challenges
In multi-team organizations, publication boundaries align with team boundaries, making dependency tracking essential. Without visibility into shared contracts, changes can have unintended consequences across the system.
12Tooling Limitations
Existing tools like Nx and Sourcegraph index dependencies at repository or package granularity, missing component-level impacts. Recording edges at version creation eliminates the need for analysis and works across repositories and scopes.
Original article: Towards Data Science — Good Architecture Eliminates Signals Agents Depend On