Introduction
For more than two decades the Agile Manifesto has defined mainstream software practice. By valuing "individuals and interactions over processes and tools" and "working software over comprehensive documentation", agile practices such as Scrum and Kanban gave teams the freedom to ship early and iterate. In the classic start-up narrative this lightweight governance accelerated feature velocity and empowered developers. In 2025, however, the rise of large-language models (LLMs), generative artificial intelligence and code-automation tools forces us to re-examine those values. When your "teammate" is an AI that cannot read your mind, the tacit knowledge and tribal memory that agile culture takes for granted become liabilities. This essay argues that Agile's low-documentation ethos is mis-aligned with the demands of AI-driven development and proposes a shift to context-driven practices that retain agile's iterative strengths while feeding AIs the structured information they need.
The Low-Documentation Culture of Agile
Agile emerged as a reaction against heavyweight waterfall methodologies that generated voluminous specifications and design documents. The Manifesto explicitly values working software over comprehensive documentation, and many agile practitioners internalised this as "documentation is waste." Technical writers working in agile contexts are encouraged to produce only minimum viable documentation and to collaborate closely with developers so that documents stay aligned with the product's evolution. The result is a cultural bias toward shipping code and leaving knowledge in people's heads rather than in durable artifacts.
That ethos has consequences. A recent survey summarised in Full Scale's 2024 documentation report found that 78 % of development teams report challenges with outdated or insufficient documentation and that 64 % of developers spend at least four hours per week searching for project information. Poor documentation increases bug-fix time by 3.2x and extends code review duration by 2.5x. The same report cites Forrester research showing that inadequate documentation leads to 32 % more failed deployments and 27 % higher bug rates in production. Agile teams that treat documentation as an afterthought thus trade immediate velocity for downstream friction and lost productivity.
Bug reporting illustrates the problem. In well-run projects a bug report includes a descriptive title, the environment, reproducible steps and expected versus actual behaviour. Atlassian's bug-triage guidelines note that formatting bug reports properly is essential for effective triage and emphasise that clear documentation of the triage process ensures that "everyone understands the bug triage process". Yet many agile teams treat bug tickets as quick reminders rather than communication artifacts. The author has witnessed a steady decline in bug report quality over the past decade; many new developers now post issues with blank descriptions or vague titles, assuming that someone who knows the system will pick it up. When knowledge is tacit and scattered across chats and stand-ups, an AI agent cannot reconstruct context. This de-skilling of communication has serious implications when the "developer" is an LLM that depends on explicit instructions.
AI's Hunger for Context
Large-language models such as ChatGPT and Claude do not understand intent; they pattern-match on the input they are given. OpenAI's own prompt-engineering guide explains that model output improves when you provide precise instructions, examples and necessary context that are not part of the model's training data. In other words, the quality of an AI's output is bounded by the quality of its inputs. Without context it hallucinates; with rich context it can generate, refactor or test code that aligns with your domain.
A RAND Corporation report for the U.S. Department of Defense illustrates how miscommunication and rigid processes undermine AI projects. Based on interviews with 65 data-science professionals, the study notes that while agile practices have succeeded in conventional software projects, 10 of 50 interviewees believed that rigid interpretations of agile processes were a poor fit for AI projects. AI work requires exploratory research and iterative data refinement, which do not always fit two-week sprint cycles. The report lists misunderstood problems, inadequate data, focus on technology over solutions, insufficient infrastructure and overly ambitious applications as leading causes of AI project failure. Most of these failures stem from poor communication between technical experts and business stakeholders. The report's recommendations begin with open communication; it warns that misunderstandings about a project's intent are a common reason for failure and urges teams to commit to long-term goals, focus on problem-solving rather than technology, invest in infrastructure and involve technical experts early.
The mismatch between agile's tacit knowledge and AI's hunger for explicit context is also visible in the open-source security community. Developers have complained that AI-generated vulnerability reports are "low-quality, spammy and LLM-hallucinated" because models lack human-level understanding and are not provided with sufficient context. Daniel Stenberg, maintainer of the curl project, reported that around two-thirds of 415 vulnerability reports were worthless due to AI assistance. Without structured problem statements and reproducible inputs, AI tools produce noise and distract maintainers. This phenomenon reinforces the point: context matters.
Garbage in, garbage out
Many teams encountering generative code assistants for the first time conclude that "the AI is dumb." In reality, they are experiencing garbage in, garbage out. When prompts consist of half-formed user stories or incomplete bug tickets, the AI cannot derive intent. Without an architecture spec, it may choose suboptimal patterns. Without data quality constraints, it may train on biased or inadequate sets. This is not a defect of the AI but a reflection of the team's communication discipline. To harness AI effectively, teams must treat context as first-class data.
Preserving Agile's Strengths
Critics who call for abandoning agile entirely miss its enduring benefits. The Top 10 Benefits of Agile article summarises why the methodology remains appealing. Improved collaboration—through daily stand-ups and retrospectives—keeps everyone aligned. Faster time-to-market is achieved by breaking work into sprints and delivering incremental value. Agile's flexibility and adaptability allow teams to pivot when requirements change. Continuous integration and testing deliver higher-quality products by catching defects early. These strengths are as valuable in AI projects as in traditional software—possibly more so because AI development is inherently exploratory. The challenge is to retain these benefits while addressing the documentation gap.
Agile also promotes self-organising teams where cross-functional members collaborate closely. AI initiatives require close cooperation between domain experts, data engineers, machine-learning scientists, ethicists and product owners. RAND's report stresses that technical teams must engage in frequent and open communication with business stakeholders to ensure alignment and trust. This is an agile value—individuals and interactions over processes and tools—but it cannot function if the conversation remains verbal and undocumented.
Toward Context-Driven Development
How do we evolve agile for the AI age? The answer is not to resurrect hundred-page design documents; rather, it is to treat context as a product artifact. Below are concrete practices for Context-Driven Development:
Write Prompts as Product Requirement Documents (PRDs). Treat the prompts fed to AI assistants as you would treat user stories or PRDs. Include the problem statement, acceptance criteria, edge cases, examples and constraints. Store these prompts in version control alongside the code. They become living documents that evolve as the product does.
Version and Link Context. Create a single source of truth for architecture diagrams, API contracts, data schemas and domain glossaries. Use tools like OpenAPI or AsyncAPI for machine-readable specs. Ensure that every AI call references the specific version of the context it depends on. When the design changes, update both code and context concurrently.
Enforce Quality in Bug Reports and User Stories. Use templates that require reproducible steps, expected behaviour and environment details. Implement linting or continuous-integration hooks that reject tickets with blank descriptions. Atlassian's bug-triage guidance emphasises that proper formatting is crucial for effective triage, and clear documentation ensures everyone understands the process. In an AI-augmented workflow, these templates become even more critical because they feed the model.
Close the Loop with Data. When AI models generate code or decisions, capture the input prompt, the context provided and the output. Evaluate the output against acceptance tests and user feedback. Refine the context iteratively. This preserves agile's short feedback loops while building a corpus of high-quality examples for future prompts.
Use AI to Generate Documentation, then Review. Generative models can draft documentation based on code or conversation transcripts. Use them to produce first drafts of API docs, design rationale or change logs. Human experts must review and correct these drafts to ensure accuracy and completeness. Over time, the AI learns from these corrections, improving its ability to generate useful documentation.
Expand the Definition of "Done." In agile, a task is "done" when the feature is implemented and tested. In context-driven development, a task is not complete until its associated context has been updated. This includes updating the prompt repository, design docs and data lineage. Embedding context updates into the definition of done ensures that knowledge stays in sync with the code.
Applying Agile Strengths to AI
By integrating the practices above, teams can retain agile's benefits while equipping AI agents with the information they need. For example:
- Fast Feedback Loops: Use short iterations to test AI-generated code or models. Provide explicit metrics and acceptance tests. Use continuous integration to evaluate AI output on each iteration. This preserves agile's rapid learning while giving the AI concrete signals.
- Self-Organising, Cross-Functional Teams: Form squads that include domain experts, data scientists and prompt engineers. Encourage them to collaborate in refining context documents and prompts. This harnesses agile's empowerment while acknowledging that AI requires multidisciplinary input.
- Incremental Delivery: In AI projects, deliver incremental models or features that solve sub-problems. Document the context used for each model so that improvements build on past work. This reduces risk and surfaces issues early.
- Continuous Improvement: Use retrospectives not only to improve process but also to refine context artifacts. Ask: Did our prompts lead to the desired output? Did we capture the right assumptions? Are there biases in our data? Update the context accordingly.
Conclusion
Agile transformed software development by prioritising collaboration and adaptability, but its low-documentation culture is mis-aligned with the requirements of AI. Large-language models and generative AI systems cannot infer tacit knowledge; they need structured context and clear specifications. Surveys show that poor documentation already costs teams productivity and increases bug rates. Research from RAND indicates that rigid agile processes contribute to AI project failures and that miscommunication between business and technical stakeholders is a primary culprit. Meanwhile, open-source maintainers report being flooded with low-quality AI-generated bug reports because models lack context.
Rather than abandoning agile, we should evolve it. Context-Driven Development proposes weaving context capture into agile practices: treat prompts as version-controlled specifications, enforce high-quality bug reports, link documentation to code, and expand the definition of done. By feeding AI agents the information they need while preserving short feedback cycles and collaboration, we can unlock the promise of AI-augmented development without shooting ourselves in the foot. The future of software is not just about working software over documentation; it is about working software with documentation that machines can understand.