clear/LLM-SHIFT.md

The LLM Shift: From Comprehension Limits to Intention Clarity

What Fundamentally Changes

1. Cognitive Load → Verification Load LLMs can hold 100k+ tokens in context and traverse codebases instantly. The bottleneck shifts from "Can I understand this?" to "Can I verify this is correct?" Design now optimizes for inspectability and testability over raw simplicity.

New pattern: Boundaries become verification checkpoints. Each module needs clear invariants and contracts that can be mechanically verified, not just conceptually understood.

2. Minimize Coupling → Maximize Autonomy When an LLM agent can modify code, loose coupling becomes existential. A poorly bounded module lets the LLM cascade changes across the system. Design for blast radius containment.

New pattern: Modules become "agentic workspaces" - zones where an LLM can operate freely without risking the broader system. Tests act as guard rails, not just safety nets.

3. Explicit Dependencies → Explicit Invariants LLMs can trace dependencies easily. What they can't infer are the "why" and the constraints. The critical information shifts from "what depends on what" to "what must never break."

New pattern: Property-based tests, design-by-contract, and formal invariants become first-class citizens. Document constraints, not structure.

What Intensifies

4. Optimize for Deletion → Optimize for Regeneration If an LLM can rewrite a module from specs, deletion is cheap. But so is generation. The new risk: code obesity - systems that balloon because generation is easier than curation.

New pattern: Design for ephemerality. Distinguish "canonical" (hand-crafted, precious) from "derived" (LLM-generated, disposable). Make derived code obvious and replaceable.

5. Align with Reality → Align with Intent LLMs amplify misalignment catastrophically. If your domain model doesn't match reality, the LLM will generate mountains of wrong-but-plausible code.

New pattern: Invest heavily in ubiquitous language and domain modeling. The clearer your domain concepts, the better the LLM performs. DDD becomes more important, not less.

The New Forces

6. Make the Implicit Explicit Humans rely on context and intuition. LLMs need it spelled out. Tribal knowledge, unwritten rules, "we just don't do that here" - these must be codified.

New tooling: Architectural Decision Records (ADRs), explicit design constraints, linting rules that encode team wisdom, comprehensive example-driven documentation.

7. Design for Observable Correctness When an LLM makes a change, you need to know instantly if it broke something. The faster feedback, the more autonomy you can grant.

New investment: Type systems, contract tests, property tests, mutation testing, runtime assertions. Make correctness visible, not just possible.

---

The Principal's New Stance

You become a curator of constraints, not complexity.

Your role shifts from "help humans navigate complexity" to "define safe operating boundaries for human-LLM teams."

• Less time: Explaining how the system works (LLM does this)

• More time: Defining what the system must never do (LLM needs this)

• Less time: Refactoring for readability (LLM reads anything)

• More time: Architecting for verifiability (LLM changes must be checkable)

• Less time: Documentation of implementation (LLM can traverse)

• More time: Documentation of intent and constraints (LLM can't infer)

The paradox: LLMs make bad design more tolerable in the short term (can navigate spaghetti) but more catastrophic in the long term (can generate more spaghetti faster than humans can audit).

The answer isn't to abandon design principles - it's to double down on the ones LLMs can't compensate for: clear boundaries, explicit invariants, comprehensive verification, and ruthless curation.