Six architectural principles to prevent AI spaghetti code
How to structure AI features without creating enterprise chaos
1The Winchester House problem
Sarah Winchester's 38-year construction spree created a mansion with staircases to nowhere, mirroring how AI features are often added haphazardly in enterprise software. Without architectural planning, each new AI capability like copilots or summarizers creates isolated functionality that doesn't integrate. Currently 90% of organizations use AI but haven't restructured workflows around it, leading to disjointed systems where each feature operates with its own logic and output formats.
2Define the object model first
Before implementing features, teams must establish a shared object model - the core nouns (documents, projects) and verbs (archive, share) that define the product's universe. This scaffolding prevents features from inventing undefined concepts like 'follow-ups' that exist outside the system's architecture. The constraints in this model (e.g., invoices can be approved but never archived) provide the structure that keeps features aligned with business logic rather than creating parallel realities.
3Pattern library over ad-hoc solutions
Most teams have 40 features but zero standardized interaction patterns for behaviors like drafting or summarizing. Without predefined patterns, each engineer improvises failure states and recovery flows, creating inconsistency. A small library of 5-6 named interaction patterns (suggest, draft, summarize) with defined states (entry, in-progress, recovery) ensures features behave predictably rather than inventing new solutions for solved problems.
4Living information architecture
Most product teams treat information architecture as a one-time deliverable created before launch. As features accumulate, the original map becomes obsolete, making it impossible to scope new work appropriately. The solution is treating IA as a living document updated with each release, generated from actual router configurations rather than theoretical designs, showing what users actually navigate today rather than the original plan.
5Scheduled refactoring cadence
Like Sarah Winchester sealing off earthquake-damaged rooms instead of repairing them, teams often deprecate features behind flags rather than properly removing them. Without scheduled architecture reconciliation, objects bypass contracts, components get forked, and patterns are violated 'just this once.' Quarterly refactoring blocks must be roadmap items to retire technical debt before it compounds.
6Contextual feature scope
AI features often behave like omniscient boxes floating above the application rather than respecting location context. A document-level AI should offer document verbs, while project-level AI handles project actions. Binding feature scope to information architecture levels makes capabilities discoverable through interface context rather than requiring users to mentally model the entire system to formulate requests.
7Built-in traceability
Teams often delay implementing source attribution and confidence indicators until compliance demands it. Research shows generative tools provide incorrect answers to 60% of queries, often with high confidence. Making traceability (sources, confidence levels, 'show your work' panels) a first-class component in the design system ensures all AI outputs carry appropriate context about their origins and reliability.
8Semantic contracts
A published contract signed by engineering and design aligns teams on object models, verbs, and relationships. This prevents vocabulary drift where different teams use different terms for the same concepts. The contract serves as a single source of truth for what exists in the system's universe and what operations are valid, ensuring features build within the defined world rather than creating parallel ones.
9Controlled output vocabulary
Just as Simplified Technical English standardizes aircraft manuals, product teams need deliberately narrowed output vocabularies. Features shouldn't render free-form prose but structured payloads resolving to predefined components (cards, tables). An allowlist of output types with strict schema requirements prevents interface fragmentation while still allowing new component types through justified additions.
10The reconciliation gap
The difference between the published semantic contract and the actual object model in the code represents architectural drift. Quarterly reconciliation involves reading the true model from the codebase and updating documentation to match reality. This gap measurement provides concrete technical debt metrics and prevents undocumented 'shadow architecture' from overtaking the official system design.
11Location carries intent
When features inherit scope from their position in information architecture, the interface communicates capabilities contextually. Users shouldn't need system-wide knowledge to use AI features - the screen they're on should make obvious what actions are available. Scoping tables that map verbs to IA levels turn tribal knowledge into discoverable interface affordances.
12Failure as design primitive
Error states aren't edge cases but fundamental interaction patterns that should be designed once at the library level. Standardized treatments for empty states, low-confidence results, and timeouts ensure consistency across features. When 40 features share the same recovery pattern, users develop reliable mental models rather than facing unique failure modes for each capability.
Original article: UX Collective - Medium — Six architectural principles to prevent AI spaghetti code