“Who wrote this code?”
The feature still worked and its tests passed. A few weeks after building it with AI assistance, however, changing it required reconstructing decisions that had never been recorded.
The issue was not the generated code itself. It was the missing link between the code, its requirements, the constraints behind it and the evidence used to accept it.
What AI-assisted development leaves out
McKinsey’s 2024 report on generative AI in software describes productivity gains in implementation, documentation and refactoring. Those measures describe how quickly work is produced, not how easily another person can understand or change it later.
A 2023 McKinsey study on developer productivity with generative AI also notes that general-purpose tools do not know the specific needs of a project or organization. That context still has to be supplied and reviewed by people.
From a linear process to a feedback loop
After spending three days modifying that feature, the missing artifact was clear: the reasons behind its design choices had not travelled with the code.
Research on AI-assisted development keeps landing on the same asymmetry: productivity gains concentrate in straightforward tasks, while complex development work needs its design context and intent preserved to benefit at all. In this emerging paradigm, the reasoning behind decisions becomes as critical as the code itself.
This is a workflow problem. If intent disappears after implementation, the next change starts with reconstruction. The article on context in AI-assisted development explains how those links can be preserved.
Five operating principles for AI-first development
1. Context as Primary Creation
According to Stack Overflow’s 2023 Developer Survey, 63% of professional developers report spending more than 30 minutes per day searching for answers or solutions. Recording context as part of the work reduces how much has to be reconstructed later.
In AI-first development, the requirement, decision and acceptance evidence are first-class artifacts. Code is one implementation of that context, not its only record.
The shift this points to is from “code as product” to “knowledge as product”: the organizations that treat what they know, and why, as their primary asset are the ones whose AI investments compound instead of rotting.
2. Intent-Driven Architecture
The McKinsey Center for Future Mobility 2024 report notes that teams using generative AI to understand business requirements and design architecture based on intent “helps developers capture and translate business needs into technical specifications more accurately, which reduces miscommunication.”
Intent-driven architecture records why a boundary exists as well as how it works. The purpose and constraints of a component remain available when its implementation changes.
Industry analysts have been tracking the same drift toward intent-based systems in infrastructure. The underlying recognition is broader than any one report: in complex AI-enabled environments, architecture must be designed around intent and purpose rather than just technical functionality.
3. Knowledge as a Living Entity
GitHub’s 2024 Octoverse report measured a 98% year-over-year growth in generative AI projects on the platform. Adoption of the tools is settled; what distinguishes teams now is whether the knowledge those tools produce and consume is kept alive.
Project knowledge changes with the system. Documentation therefore needs ownership, versioning and links to the work it describes rather than living as a detached snapshot.
According to McKinsey’s 2023 report on the state of AI, organizations that have embedded knowledge graphs in their business processes alongside AI capabilities consistently demonstrate higher performance. The study found that AI high-performers—companies attributing at least 20% of EBIT to AI—are “much more likely than others to say that their organizations have embedded knowledge graphs in at least one product or business function process,” enabling better contextualization of information and more accurate AI outputs.
4. Human review with AI assistance
Research from McKinsey’s 2024 study on automotive software development found that developers with proper AI training “used gen AI 60% more often per week than when they didn’t have these programs. Not only did engagement improve, but after the trainings, 95% of developers also reported that gen AI has a positive impact on their developer experience.”
AI can draft and transform implementation, while people remain responsible for requirements, trade-offs and acceptance. The useful boundary is responsibility, not who typed each line.
The years since have borne this out in practice: the developers getting the most out of agents are not the fastest typists but the ones who structure context, intent and verification around the collaboration.
5. Contextual Decision Architecture
McKinsey’s 2023 report on the economic potential of generative AI estimates that this technology could add between $2.6 trillion to $4.4 trillion annually to the global economy. Capturing any of that value over time depends on something the headline number hides: knowing, later, why the systems you built are the way they are.
Decision records need the reason, constraints and rejected alternatives, not only the selected option.
According to Harvard Business Review’s 2023 analysis of AI implementation, organizations that document not just what decisions were made but why they were made are significantly more successful at maintaining AI systems over time and extracting sustained value from their AI investments.
How this differs from adjacent approaches
The practical difference is where each approach places context and decisions:
| Paradigm | Primary Focus | Knowledge Treatment | Decision Approach | Primary Output |
|---|---|---|---|---|
| Waterfall | Sequential Process | Static Documentation | Pre-implementation | Code Correctness |
| Agile | Iterative Delivery | Updated Documentation | During Iterations | Working Software |
| DevOps | Integration Pipeline | Automated Documentation | Continuous | Deployment Speed |
| AI-First | Context Preservation | Living Knowledge | Intent-Driven | Context + Code |
The pattern across the table is consistent: traditional paradigms treat knowledge as a by-product of development, while AI-First treats it as the primary product, with code as its expression.
Implications for software teams
McKinsey’s 2024 report on enterprise technology’s next chapter describes three effects teams need to plan for:
- “As staff productivity increases, the speed at which IT can conceive, build, and launch capabilities is also expected to increase, while the cost of that work will likely decrease.”
- However, “Gen AI may not reduce enterprise technology budgets outright. Instead, it will drive a strategic reallocation within the enterprise technology portfolio, with tech leaders increasingly focusing on growth-oriented projects rather than routine maintenance.”
- Organizations need to “strengthen planning and risk management efforts to sustain the rapid pace.”
The report also recommends reviewing how artisan and factory patterns are balanced as business priorities change.
For software teams, that means preserving not just what was built, but why decisions were made and which evidence supported them.
What these principles change
These principles are operational: record why a change exists, keep requirements connected to implementation and attach verification to the same context. That reduces reconstruction work and gives people and agents a better basis for future changes.
For teams looking to implement these principles in practice, the PAELLADOC framework provides a comprehensive system for context preservation throughout the entire development lifecycle.
This article establishes the philosophical foundations of AI-First Development. Sources last reviewed in July 2026; figures that could no longer be traced to their original studies were removed rather than kept on faith.
The PAELLADOC context article shows how these principles map to a working structure.
Frequently asked questions
Why does AI-generated code become unmaintainable?
AI generates code that works and passes tests, but it rarely records why a decision was made. Months later, changing that code means reconstructing intent that was never captured: the constraints, the rejected alternatives, the business reason. The code is not low quality; the context around it is missing. That gap, not the AI itself, is what turns a quick feature into a maze nobody wants to touch.
What are the principles of AI-first development?
This article frames five: context as the primary creation rather than a by-product; intent-driven architecture organised around purpose instead of pure function; knowledge treated as a living entity that evolves with the system; human-AI collaboration as a genuine partnership; and a decision architecture that records why choices were made, not just what was decided. Together they invert the old order where code was primary and context secondary.
Does AI-generated code need documentation?
It needs something better than traditional documentation: context linked to the code and kept alive as the code changes. Static docs in a separate wiki rot and get ignored. What matters is capturing the reasoning behind AI-generated decisions — requirements, trade-offs, rejected paths — close to the code, so the next person, or the next AI session, can act on intent instead of guessing it.