The Audience

You’re onboarding an AI agent to a complex legacy system. You point it at the repo and give it a feature request. The output is functional but fundamentally misunderstands the system’s constraints, security model, and performance characteristics.

The root cause? Documentation written for humans, not the machines now reading it with perfect but context-blind recall.

LLMs and autonomous coding agents parse your entire documentation corpus—READMEs, comments, tests, wikis—with perfect recall but without human intuition. This creates both unprecedented opportunity and new failure modes. The same principle now extends far beyond code into every form of written communication we produce.

TL;DR

AI treats all written material as primary context rather than supplementary reading
READMEs function as system prompts; tests as behavioral contracts; communications as style and intent signals
Intent-driven comments, structured docs, and consistent external writing reduce hallucinations and improve coherence
Concrete practices across code and non-code writing yield measurable improvements in agent reliability, personal representation, and output quality
All forms of writing are now infrastructure for AI-native workflows

The Shift: Documentation and Communication as Context Infrastructure

We once maintained docs and communications as checkboxes for human collaborators who might never read them in full. Comments were afterthoughts. Tests were strictly for verification. Emails and messages were ephemeral. Web posts were for human audiences.

Today, every line is ingested repeatedly by tools that lack our implicit knowledge of the domain, history, and preferences. One notes, with some irony, that agents don’t just read your code docs—they analyze your email threads for decision history, review IM conversations for context clues, and study your web posts and articles to understand your voice and expertise.

The cruel irony: documentation, once the most painful and time-consuming part of the engineering job—the part we procrastinated, delegated, or quietly resented—must now become essential daily practice. What was drudgery is now infrastructure. (It does raise the inevitable question of context size, a matter best reserved for a future article.)

“Programs must be written for people to read, and only incidentally for machines to execute.” — Harold Abelson & Gerald Jay Sussman (Structure and Interpretation of Computer Programs)

Recent work on context files demonstrates that well-structured base materials allow AI to generate supporting documentation that outperforms sparse human efforts. Quality of written output directly correlates with AI effectiveness across your professional and public presence. Your lazy README haunts you exponentially now.

README.md: The AI Onboarding Manual

Your README is no longer a polite welcome mat—it’s the foundational context window for any agent entering your codebase. Agents parse it first to build their understanding of scope, conventions, and constraints. A weak README forces the AI to make assumptions that compound through subsequent interactions.

Ineffective (human-centric):

Vague setup steps that assume institutional knowledge
High-level feature lists without implementation details
Boilerplate contribution sections that don’t address AI-assisted contributions

Effective (agent-optimized):

Self-contained architecture summaries with visual diagrams in multiple formats
Verifiable one-command bootstrap sequences including dependency graphs and environment variables
Non-functional requirements, scaling considerations, and invariants spelled out with examples
Dedicated sections on core mental models, common pitfalls with real scenarios, and debugging decision trees
Sample interaction patterns, effective prompt templates tailored to the domain, and examples of past AI contributions

Successful patterns include dedicated instruction files that define boundaries, preferred reasoning approaches, and escalation paths for when the agent encounters ambiguity. When agents can bootstrap correctly from docs alone, downstream tasks succeed at higher rates with fewer clarification loops. This reduces token usage and improves overall efficiency in long-running agent sessions.

Documentation: Structured Knowledge for Inference

Beyond READMEs, detailed specs, architecture decision records (ADRs), API references, and module overviews serve as the long-term memory for AI systems working across your project over extended periods.

Practices that matter for both humans and AI:

Machine-readable consistency through standardized headings, metadata tags, and cross-linking conventions
Emphasis on tradeoffs, rejected alternatives, and the context in which decisions were made
Rich cross-references between documentation, code implementations, test cases, and related communications
Living documents updated alongside code changes with clear change logs and rationale
Historical context and system evolution to help AI understand why certain patterns exist

LLM performance benchmarks consistently show significantly better results on tasks with rich, structured supplementary documentation versus code-only context. The AI can better maintain consistency with original design goals and avoid introducing regressions when this knowledge is explicitly available.

Comments: Encoding Decision Rationale

Inline comments have evolved from simple developer notes to critical signals that shape how AI reasons about your implementation choices and maintains fidelity to original intent over time.

Low-value patterns to eliminate:

Redundant restatements of obvious code logic
Generic TODOs without associated context, owners, or acceptance criteria
Comments that duplicate information available elsewhere in docs or tests

And then there are the comments that were never meant to see the light of day—filled with profanity, insults aimed at never-ending bugs or the original author (sometimes by name). AI will read them too. A summary could end up in a generated distributed status report.

High-value patterns that provide leverage:

Direct links between specific code and underlying business or domain requirements
Detailed documentation of performance, security, or compliance considerations that influenced the approach
Notes on subtle interactions, gotchas discovered during development, or environmental assumptions
References to related test cases, email discussions, or IM threads that validate or explain the logic
Forward-looking comments about planned extensions or known limitations for future AI work

“Documentation is a love letter that you write to your future self.” — Damian Conway

These comments allow AI to reconstruct the original engineer’s intent and decision-making process rather than inferring solely from implementation details. This leads to more coherent extensions, refactors, and feature additions that stay true to the system’s foundational principles.

Tests as Behavioral Contracts

Test suites function as both executable validation and formal specification for AI agents, providing concrete, verifiable examples of expected system behavior.

They excel as unyielding behavioral contracts—the only language an LLM can’t misunderstand or creatively misinterpret—because:

Descriptive test names and structures clearly articulate intended behavior in natural language that AI maps directly to requirements
Individual assertions encode exact input/output boundaries, leaving no room for “creative” edge-case handling by the agent
Failing tests deliver immediate, grounded debugging targets complete with reproducible scenarios, rather than vague bug reports
Gaps in coverage naturally highlight areas where knowledge remains dangerously implicit or tribal
Integration with CI provides ongoing, ruthless validation that AI changes haven’t broken core functionality

Engineering teams consistently report that directing agents with precise instructions like “update this feature while keeping all existing tests green and adding coverage for new paths” produces far more reliable and maintainable results than vague or high-level requirements. This approach turns your test suite into a powerful constraint system that channels AI creativity within proven boundaries.

The Expanding Sphere: Emails, IM Messages, and Web Posts

The audience shift extends well beyond your codebase. AI systems now routinely generate and consume emails, instant messages, web posts, blog articles, and social content on our behalf.

Emails: AI draft responses, summarize long threads, and extract action items. Clear, structured emails with stated context, decisions, and follow-ups become the reference corpus for how AI should represent you. Vague or emotionally charged messages can lead to inappropriate tone in AI-generated replies. Consistent structure—context, decision, action items, rationale—helps AI maintain professional coherence. Your 2am passive-aggressive reply will be studied and replicated.

I once realized, mid-conversation with a vendor, that my AI was effectively talking to their AI via email—we were merely pushing Send.

IM Messages: Slack, Teams, and similar platforms generate massive volumes of conversational context. AI tools analyze these for project status, blocker identification, and decision history. Fragmented threads or ambiguous “thumbs-up” emojis confuse agents attempting to extract requirements. The lost context of an unthreaded “sure” becomes a major roadblock for an LLM trying to reconstruct a decision. Using threaded discussions, explicit summaries, and searchable keywords improves AI’s ability to synthesize accurate overviews and suggestions.

Web Posts and Public Content: Your blog posts, articles, social media, and documentation sites are crawled and used to understand your expertise, voice, and positions. Inconsistent messaging across platforms leads to AI producing content that doesn’t align with your established thought leadership. Maintaining a unified voice through style guides applied to all public writing ensures AI extensions of your work feel authentic.

This broader corpus means documentation discipline must become a universal habit. The same principles of clarity, structure, intent communication, and stated constraints apply to all written output. Teams and individuals who extend these practices to emails, messages, and web content see improved AI assistance across their entire workflow—not just coding tasks.

Practical Implementation Steps

Self-audit: Have an AI agent summarize your project’s architecture, recent decisions from emails/IMs, and public voice using only your current materials. Note gaps and inconsistencies. Prepare to be humbled.
Standardize for parseability: Adopt consistent formats, metadata, and linking conventions across code docs, emails, messages, and web content.
Elevate tests and examples: Focus on descriptive naming and comprehensive coverage as primary specification artifacts in both code and communications.
Close the loop with AI: Regularly use agents to critique, summarize, and enhance your documentation, emails, and posts for clarity and AI-friendliness.
Quantify results: Track metrics including successful first-attempt task completion rates, hallucination frequency, tone consistency in generated communications, and time saved in synthesis tasks.

For teams, practical documentation extends to shared context files (AGENTS.md equivalents), standardized decision records, and routine AI-assisted knowledge base maintenance—turning collective tribal knowledge into reliable agent fuel.

Establish systems and processes that create source-controlled documentation in easy-to-consume Markdown. Yes, it makes the repository larger, but everything becomes AI-consumable.

Coda

All forms of writing have undergone a phase change. What was once a maintenance burden or casual communication is now core infrastructure for reliable AI collaboration and personal representation. The documentation you skipped writing in 2023 because “the code is self-explanatory” is now costing you in agent hallucinations, misrouted decisions, and emails drafted in a voice you don’t recognize.

Individuals and teams that treat their entire written output with discipline gain compounding advantages. The rest are training their replacements to misunderstand them with perfect fidelity.

“The great enemy of clear language is insincerity.” — George Orwell

You and your teammates are no longer the audience. Our AIs are.

The Audience: When AI Reads Your Work