Docs as Source

The core of "Docs as Source" is the practice of treating human-readable documentation — specifically, agent context files like AGENTS.md, CLAUDE.md, and brand-specific maps — as the authoritative source for how systems should behave and products should function.

What it is

This approach formalizes documentation, elevating it from passive explanation to active instruction. Instead of merely describing what a system does, these documents dictate what it should do. For me, this means markdown files living directly in the monorepo, version-controlled alongside the application code. These aren't just READMEs for humans; they are the explicit instruction sets consumed by my AI agents. They define expected behavior, operational constraints, and detailed product logic. This includes everything from the desired output format for an API response to the specific tone for a marketing email generated for Inky.

Why I do it this way

The primary driver is preventing agent drift. As the initial hook states: `AGENTS.md / CLAUDE.md / brand-specific maps are agent context. Keep them current or watch agents drift.` If the documentation an agent references is outdated or ambiguous, the agent's output will reflect that outdated understanding. By making the docs the source, I ensure that when I update a requirement, I update it in one place, and both humans (myself, in six months) and the agents operate from the same, current specification. This directly supports Agent-First Development by providing a machine-readable, human-authored specification for tasks. It also ensures that when Claude Code as the Engineer is tasked with generating code, it's working from the most current understanding of the requirements, reducing the need for extensive post-generation corrections. This consistency is critical across all Total Ventures products, from the data processing for Total Formula 1 to the user interface logic for Pregnancy Power Hour.

How it works in practice

In practice, `AGENTS.md` files define the overarching mission and capabilities of specific agent personas within VERA, my agent orchestration layer. `CLAUDE.md` provides Claude-specific instructions, outlining preferred output formats, coding conventions, and interaction protocols. Brand-specific context maps detail product features, user flows, and business logic. For Total Formula 1, a context map might specify how race results are parsed from an external API, how historical data is stored in Firebase, and how it should be displayed on the frontend via Vercel.

These markdown files are committed to Git. When an agent is invoked for a task—whether it's generating a Resend email template, proposing a Stripe integration change, or writing a blog post for Inky—VERA pulls the relevant context documents directly into the agent's prompt. This ensures the agent is operating with the latest information. If I need to modify a product feature or refine an agent's behavior, I edit the markdown file, commit the change, and the agents immediately begin using the updated context on their next run. This creates a tight feedback loop, allowing me to specify requirements and see the agent's output reflect those changes without needing to re-prompt or manually correct.

Where this breaks down

This approach demands meticulous maintenance. If the documentation drifts from the actual system behavior or current requirements, the agents will inevitably drift as well, building to an outdated or incorrect specification. This is the primary failure mode. Ambiguity in markdown, while human-readable, can still lead to misinterpretations by agents. I've learned to be extremely precise in language, using clear headings, bullet points, and code blocks to minimize misreadings. For highly complex, branching logic, pure markdown can become cumbersome; in such cases, I might supplement with structured configuration files, but the principle of a single, authoritative source remains. Finally, a robust agent orchestration layer like VERA is essential to reliably inject and interpret these documents. This also highlights the importance of Human-in-the-Loop Where It Matters, as I need to review agent outputs to catch any misinterpretations of the documentation before they are shipped.