Documentation Best Practices for AI Codebases: Beyond the Docstring

In traditional software engineering, a good docstring and a README are often enough. But AI-driven applications introduce a new dimension of complexity: non-determinism. When your code’s logic is partially defined by a probabilistic model and a natural language prompt, standard documentation falls short.

Documenting AI codebases requires capturing not just what the code does, but why a specific model was chosen, how a prompt was tuned, and what the expected variance is.

Prerequisites

• Familiarity with AI/LLM integration.
• Experience with version control (Git).
• Basic understanding of Agentic workflows.

1. Documenting Prompt Versions and Logic

Prompts are effectively “soft code.” If you change a word, the system’s behavior changes. Treat them with the same rigor as source code.

• Version your prompts: Don’t just hardcode them. Store them in structured files (YAML/JSON) with metadata.
• Explain the “Why”: Why did you add “Think step-by-step”? Was it to fix a specific reasoning error?

# prompts/v1/summarizer.yaml
version: "1.2.0"
model_id: "gemini-1.5-pro"
temperature: 0.2
system_instruction: |
  You are a technical editor. Summarize the following text in exactly three bullet points.
  # Note: 1.2.0 added the 'three bullet points' constraint to prevent verbosity.

2. Using llms.txt for AI-to-AI Documentation

As we build agents that build agents, we need documentation specifically for AI consumption. The llms.txt standard (pioneered by AnswerDotAI) provides a concise, LLM-friendly map of your codebase.

• Purpose: Helps coding assistants understand your project’s architecture, key APIs, and constraints without scanning every file.
• Location: Keep a /llms.txt in your root.

# Project: Agentic-Flow
Modular framework for multi-agent orchestration.

## Key Modules
- src/core/agent.ts: Base class for all agents.
- src/tools/search.ts: Tool for Google Search integration.

## Constraints
- Use asynchronous patterns for all tool calls.
- Avoid external dependencies outside of the 'pydantic' ecosystem.

3. Tracking Model Dependencies

AI applications depend on specific model versions (e.g., gpt-4o-2024-08-06). When providers update models, your “code” (the model) changes underneath you.

• Inventory your models: Document which parts of the app use which model and why (cost vs. latency vs. reasoning).
• Record Provider Nuances: Does the model support system instructions? Does it have a specific context window limit?

4. Explaining Non-Deterministic Code Behavior

If a function returns a slightly different JSON object every time, standard unit tests might fail. Documentation must bridge this gap.

• Define Success Margins: Document what constitutes a “valid” response beyond strict schema matching.
• Document Retry Logic: Explain the strategy for handling “hallucinations” or transient model failures.

/**
 * processesUserRequest(input: string)
 * 
 * NOTE: This function uses an LLM. Output is probabilistic.
 * - Retry strategy: 3 attempts with exponential backoff on 429/500 errors.
 * - Validation: Uses Pydantic for schema enforcement; expects 95% pass rate.
 */
async function processesUserRequest(input: string) { ... }

5. Architectural Diagrams for Agentic Systems

Loops and tool-use make agentic systems hard to follow in text. Visual diagrams are essential for understanding the state transitions.

• Visualize the Loop: Use Mermaid.js or similar tools to show how an agent iterates.
• Map Tool Access: Clearly show which agents have access to which tools (database, browser, etc.).

graph TD
    User -->|Query| Orchestrator
    Orchestrator -->|Analyze| AgentA
    AgentA -->|Search| Tool[Google Search]
    Tool -->|Results| AgentA
    AgentA -->|Synthesis| Orchestrator
    Orchestrator -->|Response| User

Putting It All Together

A well-documented AI codebase isn’t just for humans; it’s for the AI that will inevitably help you maintain it. By moving beyond simple docstrings and into prompt versioning, llms.txt, and behavioral documentation, you create a system that is resilient, transparent, and ready for the agentic era.

Conclusion & Next Steps

Documentation in the age of AI is a living entity. Don’t just write it and forget it.

• Audit your prompts: Check if the documented logic still matches the actual output.
• Generate an llms.txt: Start with a simple summary of your src/ directory.
• Visualize one loop: Take your most complex agent and draw its decision tree.