20251018
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 computers grasp the situational factors humans intuitively navigate. Now, working with LLMs and code assistants like local Ollama models, Claude Code, and GitHub Copilot, I find myself wrestling with the inverse problem: I’m the one losing context.
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. And it manifests in a pattern I’ve come to recognize as the “80% problem.”
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 breaks, or worse—you realize you can’t confidently explain how your own system works or why you need an in-memory data structure store for your initially simple project. The structure has become opaque. The inner workings, mysterious. Sometimes, even the original purpose feels hazy.
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 model of the system. We’ve created what I call a representational divergence—the gap between what the code is and what we understand it to be.
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—and it avoids the majority of ‘works on my machine’ scenarios. Whether working with Claude Code’s agentic workflows, Ollama’s local models, or GitHub Copilot’s inline suggestions, the containerization solves the practical problem of managing different projects with peculiar technical prerequisites.
But more importantly, it creates a conceptual boundary. The model context becomes explicitly two-fold:
- AI Environment Context: Instructions, behavior guardrails, tooling configuration
- 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’re building.
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 myself running an additional container for fiddling with the AI dev environment itself. It is a meta-design process where you sharpen or adjust your tools whilst working, just like a craftsman would.
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 cognitive resources accordingly.
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 AI-assisted development.
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 status. The context becomes something that happened rather than something you’re generating. The representational nature of the AI’s understanding—its model of what you want—cannot capture the actual unfolding of development work.
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 context gets constructed without you.
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 of the world simply get in the way. It turns out to be better to use the world as its own model.”
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 relationships between components continuously evolve. The AI’s representation inevitably lags behind reality.
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 to locate your vehicle in a parking lot. You push the button, the car responds immediately. The temporal immediacy creates understanding without needing a map.
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 causality feels lost. What changed? Why? How?
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 manual action creates a temporal marker you can use to understand cause and effect.
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 rate exceeds filtering capacity.
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” but “rich to insiders because of contextual meaning within the group.”
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 specific architectural patterns or fine-tuning Ollama models with domain-specific examples, you develop a shared vocabulary. The AI learns your patterns; you learn its capabilities and failure modes.
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.
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 understanding captured alongside it.
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 running code.
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 the ADR before implementing. This forces you to understand why, not just what.
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 gone. The reasoning remains.
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 Code might install a Python dependency, Ollama might reference an obscure utility—but they’re less good at maintaining a coherent dependency strategy. The BOM makes implicit complexity visible.
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 debt and architectural leverage points.
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 rewrites it in Rust tomorrow, your ADRs still explain why the system is structured as it is. Your developer guide still captures domain insights. Your BOM still maps dependencies and integration points.
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 formalize the relationship between intention and implementation.
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 Claude Code suggests an implementation, writing the corresponding Terraform or Kubernetes manifest forces you to understand what you’re deploying, not just how.
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 about implementation.
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 deployments increasing? You might be losing control.
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?” These aren’t just validation—they externalize the AI’s mental model so you can compare it with yours. This works whether you’re prompting Claude Code in natural language, reviewing Copilot suggestions in your IDE, or examining Ollama’s local completions.
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 commit validates one step. The PR reviews the whole solution.
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 line by line. These moments of “friction” are where understanding crystallizes.
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. This approach is widely appreciated in the military as ‘Slow is smooth, smooth is fast’.
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 technical and cognitive debt faster than you can metabolize it.
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. They ensure you’re ready to receive what comes back.
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 activity. We accept this as necessary for shared understanding.
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 realistic Hitchslaps), don’t need coffee breaks. These feel like pure advantages. But they remove natural pacing mechanisms that human collaboration provides. You have to engineer them back in.
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 answers an agent can provide.
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 tradeoffs that balance today’s needs against tomorrow’s unknowns.
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 is helpful and the suggestions seem reasonable, you follow along. Until you realize you’re building something you didn’t intend.
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. It’s the high-value activity that AI enables you to focus on by removing implementation burden.
Maintaining objective clarity requires:
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.
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.
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 is design—making conscious choices about what not to build.
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 the connective tissue between strategy and execution.
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 or fails.
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—rapid progress followed by large rewrites.
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 collective loss of understanding.
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 forcing functions for team-level clarity of intent. When infrastructure is code and deployments are declarative, you must articulate what you want before you can deploy it.
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.
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. You handle the harder problems: understanding the domain, articulating requirements, making architectural decisions, and maintaining conceptual integrity.
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 it—the business intention and purpose captured in documentation, the architectural reasoning preserved in ADRs, the domain understanding embedded in well-structured models.
The practices outlined here—dual-context architecture, deliberate constraints, comprehensive documentation, GitOps discipline—are mechanisms for ensuring that AI assistance amplifies the durable work while automating the ephemeral.
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 high-value activities. AI assistance just makes them the only activities worth your time.
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 anymore. It’s understanding. It’s judgment. It’s purpose.
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, the documentation, the architectural thinking that outlives any particular 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 preserve understanding in an age where code generation is solved but system comprehension remains distinctly human.
AI doesn’t replace developers. It finally allows us to focus on analysis, design and development.