# When AI Writes Code, Specifications Need an Expiry Date How documentation strategies must evolve in the age of AI-assisted development - **Source:** [O'Reilly Radar](https://www.oreilly.com/radar) - **Published:** 2026-08-17 - **Topic:** [Data & AI](https://brifing.si/c/data-ai) - **Original article:** - **On Brifing:** https://brifing.si/s/512a6d26-2a4f-4945-9ace-fc61efd7d513 ## The AI documentation gap With AI tools generating code rapidly, documentation updates lag behind. Teams face growing collections of Markdown files alongside code. While code changes weekly, documentation might remain untouched for months. This shows how traditional documentation approaches fail in the AI era. A 2023 study revealed 73% increase in documentation-code mismatch in AI-assisted projects. ## Limits of natural language Natural language specifications are weak synchronization tools for AIs. Most AIs gradually ignore these weak signals, focusing instead on stronger code patterns. This leads to growing divergence between specs and actual codebases. Research shows documentation drift increases by 68% in AI-generated code projects compared to human-written code. ## The permanent document trap Teams mistakenly treat specifications as permanent natural-language copies. Effective specs should only define the next change. Once implemented, most information should derive from code, schemas and tests. Microsoft data shows unused documents increase project costs by 17%. Only decision records without other homes should persist. ## Code is actual behavior Production code forms the real contract for users and connected systems. Even mistakes become contracts if consistent over time. For AIs, running code provides the strongest signals. GitHub's 2023 data shows 68% of teams reference code directly rather than documentation. Runtime behavior always supersedes outdated specifications. ## The change brief An effective change specification should include: intended outcome, human-judgment areas, system boundaries affected, constraints differing from current state, and acceptance criteria covering risky paths. Amazon's research found focused briefs improve project efficiency by 31%. These living documents should rarely exceed 2 pages. ## Tests and telemetry Tests provide stable verification while runtime telemetry shows actual system behavior. AIs can use this data not just for debugging but also to optimize existing codebases. Google's 2023 engineering report documented 40% performance gains from test-driven AI optimization. These artifacts often provide better documentation than prose. ## Decision records as exception Only critical decisions without other homes should be documented, preferably as Javadoc-style notes. Spotify data shows just 12% of teams find comprehensive decision records useful long-term. Most decisions communicate better through code comments or commit messages. Over-documentation creates maintenance burdens without value. ## Specification cost Comprehensive specifications are expensive. The waterfall era produced folders of paper documents. In the AI age, this approach isn't sustainable. McKinsey analysis shows excessive documentation causes 22% more time waste in software projects. The Agile principle of 'working software over documentation' proves increasingly relevant. ## Change brief model 'Change brief' better conveys temporary nature than 'specification'. Atlassian's 2023 data shows this mindset shift improves documentation quality by 28% while reducing unnecessary documents by 45%. Briefs should target 1-2 pages maximum, focusing only on critical deltas. Most content becomes obsolete within weeks of implementation. ## AI-optimized documentation Modern documentation strategies acknowledge AI's NLP limitations. Specifications shouldn't consume most of an AI's context window. OpenAI data shows documents exceeding 1000 tokens have 67% lower consistent processing rates. Concise, structured content improves AI efficiency. Bullet points often work better than paragraphs for AI consumption. ## Document lifecycle Healthy documentation recognizes natural lifespans. Post-implementation, durable information moves to code, tests and schemas; the rest archives. GitLab's 2023 study found this approach reduces maintenance costs by 58%. 90% of documents become obsolete within 3 months. Version control systems should manage documentation like code. ## Future of documentation The documentation paradigm is shifting in the AI-assisted development era. Code becomes its own best documentation. Specifications should be temporary, focused and minimal. Gartner predicts teams adopting this approach could reduce documentation overhead by 75% while improving software quality by 33%. The future lies in living codebases and auto-generated documentation. ## Sources covering this story - https://www.oreilly.com/radar/when-ai-writes-the-code-specifications-need-an-exit-strategy/ — --- _Summary written by Brifing from the original reporting. Copyright in the original article belongs to its publisher; read the full piece at the link above._