Staying on Top of Mental Models Whilst Context Engineering

The Irony of lost context

For years, I worked on the problem of machines that couldn't understand context. Research explored ambient intelligence systems, mobile computing, and context-aware interfaces—all centered on helping technology become more attuned to the situations in which it was used. That work assumed that context could be modeled, captured, and encoded: sensors would observe activity, heuristics would infer intent, and systems would adapt. The promise was seductive; the results were mixed.

The irony cuts deep. The very tools designed to amplify developer productivity can paradoxically erode our understanding of what we're building. This isn't a technical failure—it's a cognitive one. When generation happens faster than comprehension, context slips away. What remains is working software with an increasingly opaque rationale.

The 80% problem: When velocity becomes vertigo

You've probably experienced it. A project rockets forward at unprecedented speed. Features materialize. APIs connect. The architecture takes shape. You're at 80% completion in days instead of weeks. Then something small breaks, or a new requirement appears, or someone else looks at the code and doesn't understand why a decision was made—and progress stalls.

This is the moment you take a break and the day after you start over.

The problem isn't the AI's capability. It's that we've exceeded our cognitive bandwidth for maintaining contextual understanding. The AI generates code faster than we can integrate it into our mental models. Those models are the scaffolding we use to reason about trade-offs, to predict consequences, and to plan future work. When the scaffolding crumbles, velocity becomes vertigo.

The Technical Solution: Dual-Context Architecture

My approach addresses this through architectural separation and deliberate process constraints.

Containerized AI Development Environment

I work with a Docker-based image that serves as the foundation for AI-assisted development. This creates an idempotent, reproducible environment that can be versioned and switched between projects—a stable boundary around tooling that otherwise mutates rapidly. The image encapsulates the agent tooling, code generators, linters, test runners, and any privileged integrations. That containment reduces accidental drift and creates an explicit dependency graph for the collaboration framework.

But more importantly, it creates a conceptual boundary. The model context becomes explicitly two-fold:

1. AI Environment Context: Instructions, behavior guardrails, tooling configuration
2. Domain Workspace Context: Business logic, application architecture, the actual software being built

This separation mirrors what distributed systems engineers call "separation of concerns," but applied to human-AI collaboration. The AI environment defines how we work together. The workspace defines what we are building. Keeping those contexts distinct prevents one from subsuming the other.

The overhead of meta-tooling

This division comes with a cost. The workspace task sometimes gets overshadowed by the tooling itself becoming the workspace. The AI dev environment becomes a secondary domain in its own right. I find teams spending disproportionate effort curating prompts, maintaining agent configurations, and evolving the meta-tooling; those are legitimate activities, but they can eclipse product work if not managed.

This isn't a bug—it's a feature that must be managed. The meta-work of maintaining the collaboration framework is real work. Ignoring it leads back to the 80% problem. Acknowledging it allows you to budget for it explicitly.

The Cognitive Science framework

Research into ambient intelligence and context-aware computing provides useful theoretical scaffolding for understanding why these practices work.

Interactionally determined context

Context isn't a set of variables to be encoded—it emerges through participation in the world. This principle, articulated by Paul Dourish in his foundational work on context-aware computing, applies directly to developer-AI collaboration. Context is constructed through action: commits, reviews, conversations, and deployments. It's not merely a static description.

When you let an AI agent run fully automated—whether it's Claude Code executing terminal commands, Ollama generating local completions, or Copilot writing entire functions—you lose participatory synthesis. The actions still happen, but the human contribution that would normally couple intent with implementation is removed.

Your git commits, your architectural decisions, your refactorings—these are not just artifacts. They are the actions through which context is constructed. When the AI performs these actions for you, the external record remains, but the internal understanding erodes unless deliberately preserved.

The Frame Problem returns

The Frame Problem from AI research captures the impossibility of encoding all possible relations between all things in a dynamic environment. Rodney Brooks argued that "explicit representations and models" are fragile in open-ended activity. The lesson is humility: no representation fully captures a situated process.

AI-assisted development recreates this problem. The AI maintains an encoded representation of your codebase, your intentions, your architecture. But software development is a dynamic environment where stakeholders, requirements, and incentives change. The representation decays unless humans remain in the loop to validate and adapt it.

Your solution isn't to create a better representation—it's to maintain continuous participation in the generative process so that your own understanding stays coupled with the emerging reality.

Causal interaction and temporal coherence

Research on ambient displays emphasized causal interaction techniques—using temporal relationships to establish meaning without requiring encoded references. A classic example: using your car alarm as a temporal cue to remember that you locked the door. The timing of events creates a narrative that helps people interpret signals.

AI code generation breaks this causal chain. The AI can produce hundreds of lines in seconds. The temporal relationship between your request and the result becomes compressed to the point where causal attribution is difficult: who made which decision, and why?

Your deliberate slowdown—manually reviewing code, crafting commit messages yourself, refusing full automation—reconstructs the causal chain. Each small commit represents a comprehensible delta. Each review comment is a conversational turn that embeds reasoning in the version history. Those small actions preserve temporal coherence.

Cognitive bandwidth and information overload

In context-aware computing, we worried about information overload in mobile devices. The solution was filtering—using context to present only relevant information.

In AI-assisted development, you are the filter. The AI can generate unlimited information (code, documentation, tests). Your cognitive bandwidth is the constraint. The 80% problem occurs when generation outstrips your ability to filter, integrate, and internalize changes.

The deliberate constraints—small commits, control questions, manual documentation—are filtering mechanisms. They force information through a cognitive bottleneck that ensures comprehension.

Social navigation and turn-taking

Research by Kurvinen and Oulasvirta showed that context is dynamically constructed through turn-taking interactions. Communication develops group-specific practices that become "uninformative to outsiders" because they rely on shared history and tacit assumptions.

This describes your evolving relationship with any AI assistant. Over time, your instructions become more sophisticated. Your control questions more pointed. Whether you're prompting Claude Code with increasingly precise templates or refining Copilot's suggestions, the collaboration develops its own conversational norms.

But this creates a documentation problem: the shared context exists only in the interaction history. A new developer (or your future self) lacks the "insider" understanding without explicit knowledge capture.

The methodological synthesis

Documentation as long-term value creation

The opacity problem of developer-AI collaboration requires explicit countermeasures. But documentation isn't just a defensive measure—it's where lasting business value resides.

Code is a short-term artifact. Technology evolves. Economic conditions shift. Dependencies become obsolete. The running system you deploy today will be replaced, refactored, or retired. What endures is the explanation of choices and the context that gave rise to them.

In solution architecture, the influence of the agent means that the architecture needs to address context: both the predetermined domain goal and the interactional changes between the metamodel and the implementation.

Architecture Decision Records (ADRs): Every significant architectural choice should be documented with its context, consequences, and alternatives considered. When an AI suggests a pattern, write an ADR that explains why you accepted or rejected it. That artifact is invaluable when patterns evolve or teams turn over.

The ADR outlives the code it describes. When you rewrite the system in three years, you'll reference the ADR to understand what problems you were solving and what tradeoffs you made. The code will be opaque without that context.

Bill of Materials: Maintain explicit inventories of dependencies, services, and integration points. AI assistants excel at adding libraries—GitHub Copilot might suggest a new npm package, Claude might add a dependency, and local agents can scaffold integrations quickly.

More importantly, it documents your technical estate. When you migrate platforms or evaluate modernization, the BOM tells you what you're actually dealing with. It's business intelligence about technical assets.

Developer Guide: Document not just how the code works, but how to work with the code. Include common patterns, conventions, and—crucially—the reasoning behind non-obvious choices.

This is organizational memory. New team members learn faster. Context doesn't get siloed in AI conversation logs or individual developers' heads. The knowledge becomes portable, sharable, and durable.

These documentation practices represent the business intention and purpose—the long-term value that transcends any particular implementation. When the AI writes your code in Python today and someone else rewrites the system later, the documented intent remains.

The running code is ephemeral. The context is permanent.

GitOps as cognitive scaffolding

The GitOps approach—policy as code, declarative deployments, infrastructure as code—provides structure that extends beyond immediate technical benefits. Tools like ArgoCD, Flux, and Terraform form a declarative substrate for operations that makes system state auditable and reproducible.

Declarative specifications: Force you to articulate desired state, not just implementation. This is a cognitive checkpoint. Can you declare what you want? If not, you don't understand it yet. When you can express desired state declaratively, you clarify assumptions and constraints.

Version control as epistemology: Git history becomes a record of how understanding evolved. Each commit is a knowledge state. Tags mark conceptual milestones. Branches represent alternative hypotheses under exploration.

Data-driven reporting: Management gets metrics without disrupting flow. But more importantly, you get feedback on your own process. Are commits getting larger? That's a warning sign. Is time between reviews increasing? That's a sign of cognitive overload.

The discipline of deliberate participation

The core method is deceptively simple: maintain active, conscious participation in the development process.

Control questions: Regularly query the AI about its instructions and understanding. "What architectural pattern are we using here?" "What's your understanding of the user authentication flow?" Those questions force synthesis and expose drift.

Manual commits: Write your own commit messages. This forces synthesis. You must understand what changed well enough to explain it in a sentence. If you can't, you don't understand the change.

Issue → Branch → Commit → Pull Request: Traditional flow becomes cognitive scaffolding. Each stage is a checkpoint. The issue forces you to articulate the problem. The branch represents a hypothesis. The PR is an opportunity for communal sense-making.

Refuse convenient automation: The AI can write your commit messages. Don't let it. Claude Code can execute git commands autonomously. Stop it. GitHub Copilot can generate entire files. Review them before accepting. Those resistances maintain your engagement with the work.

The Paradox of productive constraint

We hire AI assistants to go faster. Then we deliberately slow down. This feels contradictory until you recognize that sustainable velocity requires maintained understanding. Short sprints without comprehension produce fragile systems. Sustainable velocity is paced by comprehension.

Think of it like physical training. Sprinting maximizes short-term distance. But marathon runners maintain a pace that they can sustain while staying aerobic. The 80% problem is going anaerobic—accumulating debt faster than you can pay it down.

Your constraints aren't anti-patterns. They're pacing mechanisms.

The football metaphor reconsidered

I described AI-assisted development like kicking a football against a wall—but one that returns faster than you kicked it. This creates a problem: you're not ready for the return.

The solution isn't to kick softer. It's to position yourself correctly before kicking. Your containerized environment, your documentation practices, your deliberate process—these are positioning strategies that let you receive the return with understanding.

But there's a deeper insight. In collaborative human development, some time is spent formalizing, coordinating, and recapturing purpose and status. This coordination overhead is often the predominant cost of collaboration. Human-AI collaboration shouldn't hide those costs; it should make them explicit and manageable.

Why should human-AI collaboration be different?

AI assistants don't get tired, don't argue (though I once built a mixture-of-experts analysis coach with one expert modeled after Christopher Hitchens—my ears still redden from the surprisingly real rhetorical flourish). They don't substitute for organizational negotiation, prioritization, and the messy work of maintaining shared intent.

Having a clear objective: The Meta-Superpower

In context engineering, clarity of objective is transformative. Your mental model of what you're trying to achieve directly affects the clarity of questions you can pose, and therefore the quality of the AI's responses. Clarity amplifies the signal-to-noise ratio of collaboration.

This is where developers reclaim control. The AI can generate implementations, but it cannot divine business purpose. It cannot prioritize competing concerns. It cannot make strategic architectural trade-offs that reconcile cost, time, risk, and product strategy.

This might be the most important insight: the 80% problem often stems from objective drift. You started building X, but the AI's suggestions gradually shifted the implementation toward Y. Because the AI optimizes for helpful completions, not long-term product coherence, you must steward the objective.

The AI writes code. You write the specification of what code should exist. That specification—expressed through problem statements, scope boundaries, and purpose documentation—is analysis and design work that determines the system's long-term value.

Maintaining objective clarity requires:

1. Written Problem Statements: Before any AI assistance, write down what you're trying to accomplish and why. Make a drawing. This is your anchor. It's also a design artifact that outlives the implementation.
2. Regular Reconciliation: Periodically compare current trajectory against stated objective. Ask the AI: "How does what we're building serve the original goal?" This is analysis—checking that implementation aligns with intent.
3. Explicit Scope Boundaries: Define what's out of scope. When the AI suggests expanding scope (and it will—it's optimizing for helpfulness, not focus), you have criteria for declining. This preserves velocity where it matters.
4. Purpose Documentation: The ADRs, BOM, and developer guide should all connect back to overarching purpose. Every technical decision should have a traceable line to a business objective. This is accountability.

When AI handles implementation, your value proposition becomes entirely about analysis and design. You're not displaced—you're elevated to the work that actually determines whether the system succeeds.

Implications for leadership

If you're leading teams adopting AI-assisted development, these patterns have organizational implications:

• Velocity metrics need reinterpretation: Lines of code per day might increase 10x with tools like GitHub Copilot or Claude Code. That's not automatically good. Watch for the 80% problem at team scale—big jumps in output with shrinking shared understanding.
• Documentation becomes more critical, Not Less: AI can generate code without documentation. Humans can't maintain understanding without it. Budget time for ADRs, guides, and knowledge capture.
• Code Review Changes: Reviews should focus less on syntax and more on architectural coherence and contextual alignment. The question isn't "does this work?" but "do we understand why this works?"
• Process discipline increases: The temptation to "just let the AI handle it" is strong. Strong process guardrails—mandatory documentation, no direct commits to main, ADR requirements—protect teams from accumulating invisible debt.
• Onboarding gets harder: New team members can't learn by reading code alone. They need the contextual scaffolding—the ADRs, the commit history narrative, the developer guide. Invest in these upfront.
• The GitOps dividend: Tools like ArgoCD, Flux, and declarative infrastructure give management data-driven insight into development patterns without creating reporting overhead. But more importantly, they create reproducible state that anchors understanding.

Conclusion: AI returns developers to their core value

For years, we've debated what AI would do to the development profession. The answer is emerging: it's not putting developers out of business. It's putting them back in control of what actually matters—the analysis, the design, and the reasoning that produce durable systems.

When you spend less time typing boilerplate and more time on analysis and design, you're not being displaced—you're being elevated. Tools like Claude Code, Ollama, and GitHub Copilot handle code generation; humans handle contextualization, prioritization, and long-term trade-offs.

This represents a return to first principles. Code has always been the short-term artifact. It becomes obsolete as technology evolves and economic conditions shift. What endures is the thinking behind the code.

The practices outlined here—dual-context architecture, deliberate constraints, comprehensive documentation, GitOps discipline—are mechanisms for ensuring that AI assistance amplifies the durable work and not just the ephemeral output.

When AI writes your implementation code, your value shifts entirely to context development. You become the keeper of purpose, the designer of structure, the architect of understanding. These were always the roles that determine long-term success.

The irony of my journey from studying machines that lack context to engineering context in human-AI collaboration has taught me something unexpected: the distinctly human contribution isn't execution—it's the cultivation of shared understanding.

These can't be automated because they are the automation's foundation.

The question isn't whether AI will make us faster developers. It already does. The question is whether we can move fast while doing the work that creates lasting value—the analysis, the design, and the decisions that persist beyond any single implementation.

The answer requires engineering—not just of systems, but of practice, discipline, and consciousness itself. That's what context engineering really means: deliberately structuring how we think, work, and maintain shared intent.

AI doesn't replace developers. It finally allows us to focus on analysis, design and development.