Why AI coding needs documentary-style documentation for future debugging

Midnight coding sessions with AI tools can lead to cryptic messages like "are we using full Netflix-level documentation here?"—but the core question matters deeply. What began as a clarification during a Claude Code session evolved into a structured approach to documentation that preserves not just what changed, but why it changed. The result is a lightweight ruleset that ensures AI agents and human developers alike can reconstruct the full reasoning path behind every decision.

The hidden cost of AI-generated code: lost reasoning paths

Traditional documentation focuses on final states: README files describe system capabilities, CHANGELOG files list shipped versions, and commit messages document file changes. These artifacts are essential but insufficient when AI handles most of the coding workload. The critical gaps emerge in the reasoning paths—the alternatives considered, the rejected designs, the verification logs, and the false starts that never made it into the final code.

In human-driven development, this knowledge lingers in the developer’s mind for a week or two before fading. In AI-driven workflows, the problem compounds. An AI agent lacks intrinsic memory of rejected alternatives, leading to scenarios where months later it confidently suggests a previously discarded solution. Without a structured record, debugging becomes guesswork, and institutional knowledge erodes faster than it can be rebuilt.

The documentary approach addresses this by capturing not just the outcome, but the entire decision-making process. This turns documentation from a retrospective artifact into a living, searchable log that serves as both a technical record and a knowledge base for future work.

A two-file system for maintaining clarity

The system relies on two complementary files, each serving a distinct purpose in preserving the reasoning trail.

CHANGES.md: The chronological index

This file lives at the repository root and functions as a running log of every significant change. Entries are written in reverse chronological order (newest at the top) and updated in real time as work progresses—not after the fact. Each entry includes:

• What changed
• Why the change was necessary
• What decisions were made
• What alternatives were rejected
• How the change was verified
• Outstanding follow-ups or dependencies

Here’s a condensed example from a recent project, anonymized for clarity:

2026-05-16: Music sync row restored in iOS Settings view
After the backend consolidation on 2026-05-04, the iOS Settings view lost the row exposing Music sync. The sync pipeline remained intact; only the toggle was removed during cleanup. Restored via 6 lines in `App/Views/SettingsView.swift`, adding the row under "Data Sources." TestFlight build 47 includes the restored row.

Verification: Confirmed end-to-end by pulling a fresh sync from the device and verifying delivery UUID `8b4f2a9c-7d15-4e83-9bcd-12fa8e5c61d4` landed in the backend.

Decisions: Restored the row as-is rather than redesigning the Settings view (the consolidation rationale doesn’t apply here).
Rejected: Moving Music sync to a dedicated "Media" section—too much surface area for a single source.
Outstanding: Wire the new Qwen commit `a3f2c8e91` for next week’s audio path.
Commit: `e74b2c1`

This format ensures that even years later, a developer (or an AI assistant) can quickly grasp the context behind a seemingly arbitrary code change.

docs/narrative/-.md: The story behind the changes

While CHANGES.md acts as an index, narrative documents tell the story of major events—migrations, incidents, rewrites, or onboarding processes. These files live in a dedicated directory and follow a structured outline:

• The trigger: What made the issue noticeable (e.g., a failing test or user report)
• The diff: A precise breakdown of what was removed or altered, including line numbers
• What almost happened: The alternative paths considered before settling on the final solution
• Verification: Concrete proof that the solution works (e.g., test results, logs, or UUIDs)
• What’s unblocked: Dependencies resolved by this change and next steps

For the Music sync restoration, the narrative document—titled The Settings Row That Brought Music Back—explained how a test query revealed missing data, why a six-line Swift addition sufficed instead of a full redesign, and how the delivery UUID proved the integration worked end-to-end.

Implementing the discipline: from setup to habit

Adopting this system requires minimal overhead but demands consistency. The paper-trail ruleset provides a drop-in solution available at a public repository. Here’s how to integrate it into existing projects:

1. Copy the base template: Download DOCUMENTARY_STYLE_DOCUMENTATION.md and place it in your project’s root directory.

1. Update your CLAUDE.md: Add a reference to the template file in your top-level agent configuration.

1. Initialize CHANGES.md: Create an empty CHANGES.md file at the project root to start logging changes immediately.

1. Create narrative skeletons: For the first major migration or incident, set up a new file in docs/narrative/ using the provided template.

Once configured, AI agents like Claude Code will begin appending entries to CHANGES.md during active sessions. The system is designed to be grep-friendly, allowing both humans and future AI assistants to search for keywords like rejected, verified, or decided to trace reasoning paths efficiently.

For resource-constrained environments, a -LITE variant of the ruleset reduces scope by about 25% while maintaining the same core discipline.

The measurable cost of clarity

The primary cost is operational, not technical. In real-world usage, the documentary discipline consumes roughly 9% of weekly Claude Pro Max plan usage when measured via the /status command in Claude Code. This accounts for sessions explicitly dedicated to writing or updating narrative documentation.

The secondary cost is cognitive—requiring developers to shift from retrospective documentation (writing after work is done) to inline documentation (writing as work happens). While harder to quantify, this habit prevents the accumulation of undocumented technical debt that plagues long-lived projects.

The payoff, however, is substantial. Teams using this system report faster onboarding for new developers, fewer regressions during refactors, and the ability of AI assistants to make context-aware suggestions without repeating past mistakes. In an era where AI handles much of the coding, preserving human reasoning is not just valuable—it’s essential.

As AI tools become more autonomous, the line between code and documentation will blur further. Systems like paper-trail demonstrate that the future of software development lies not in eliminating human oversight, but in codifying it—ensuring that every line of code, whether written by human or machine, carries its full context forward.