AI has dramatically accelerated how quickly we can write software. Entire features can appear in minutes. But this speed introduces a new risk that traditional engineering practices were never designed for.

The real danger isn’t just technical debt. It’s comprehension debt.

As Addy Osmani describes, AI-generated code can grow faster than teams can understand it. The system continues to evolve, but the shared mental model of how it works slowly disappears.

At the same time, Steve Yegge points out another emerging risk in AI-assisted systems: heresy. A heresy is a bad architectural idea that takes root in the system and keeps returning. Even if you remove the code, one lingering reference in documentation or prompts can cause an agent to reintroduce it later.

The result is a dangerous feedback loop.

Traditional technical debt accumulates slowly and heresy spreads.

To manage this new reality, engineering teams need a stronger foundation for AI-driven systems.

The Importance of Foundations

In an AI-assisted codebase, the most important artifact is no longer the code itself. It’s the foundation that shapes what the system believes is correct.

This foundation exists in places like:

• architecture documentation
• system context files
• agent prompts
• skills and agent configurations
• engineering standards

If the foundation is weak or outdated, agents will produce inconsistent or incorrect implementations. A healthy system begins with clearly defined foundations.

But defining the foundation isn’t enough; it must also be enforced.

Guardrails: Enforcing the Foundation

Static analysis and architectural tooling act as guardrails that prevent the system from drifting away from its foundation.

Examples include:

• dependency boundary checks
• architecture tests
• module isolation rules
• linting and policy enforcement
• CI validation

• Foundation → defines intent
• Guardrails → enforce constraints
• Code → evolves safely

Restoring Human Understanding

AI can generate code faster than humans can review it. To prevent comprehension debt, teams need mechanisms that continuously regenerate understanding.

Generated documentation provides this missing layer. We can turn back to AI to help produce these high-level artifacts such as:

• architecture diagrams
• dependency graphs
• service maps
• feature flow summaries
• system narratives

This cycle prevents comprehension debt from accumulating and stops architectural heresies from spreading.

Hints of this approach can be seen in startups like Factory.ai which introduces a “Readiness” check to help establish and maintain that foundation. This approach can be taken further to help build documentation about the system being generated by the AI helping to bridge the comprehension gap we’ve been describing.

The Shift in Engineering

AI-assisted development changes the role of engineers.

Instead of focusing only on writing code, engineers increasingly focus on:

• shaping system foundations
• defining architectural constraints
• maintaining agent context
• reviewing system-level understanding

The teams that succeed in AI-driven development will be the ones that continuously regenerate shared understanding of the systems they build. Strong foundations make that possible.