Skip to content

ADR-0004: Separate Human and AI Documentation

Status

proposed — decided during initial drafting; not yet formally ratified by a human review checkpoint.

Date

2026-07-10

Context

This repository is read by two very different kinds of readers: humans trying to understand the company, its ventures, and its policies, and AI agents that need concrete, tool-agnostic operating instructions to work in the repository correctly (what to touch, what not to touch, what rules to follow). Mixing these into the same documents tends to produce material that serves neither audience well — human-facing prose gets cluttered with agent-specific procedural detail, and agent instructions get diluted with narrative context an agent doesn't need to act correctly.

Decision

Human-facing company documentation (docs/company/, docs/governance/, docs/standards/, docs/architecture/, docs/decisions/) and AI-agent operating documentation (root-level AGENTS.md, CLAUDE.md, GEMINI.md, and docs/ai/) remain distinct document sets, cross-linked where relevant, rather than merged into one undifferentiated documentation tree.

Consequences

  • Each document set can be optimized for its actual reader: human documentation can use fuller narrative and context; AI operating documentation can be terse, explicit, and structured as an operating contract.
  • Avoids bloating company policy documents with tool-specific or agent-specific procedural instructions that would age quickly as tooling changes.
  • Keeps AI-agent instructions tool-agnostic where possible (a rule stated once in docs/ai/ rather than duplicated per AI tool's root file), reducing the risk of the different root files drifting out of sync with each other.
  • Requires maintaining cross-links so an AI agent's operating instructions can still point back to the human-facing policy that motivates a given rule, and so a human reader can understand what agents are instructed to do.

Alternatives Considered

  • A single unified documentation tree with no distinction between human and AI-facing content. Rejected: tends to produce documents that are simultaneously too verbose for quick agent consumption and too mechanical/procedural for pleasant human reading.
  • AI instructions embedded per-document (each policy document carries its own "AI agent instructions" section). Rejected: creates many small, easily-missed pockets of agent instruction scattered across the repository, rather than one place an agent can reliably check.

Follow-up Actions

  • Ensure docs/ai/ documents link back to the company-level policy or standard they operationalize, rather than restating the reasoning.
  • Keep root-level AGENTS.md, CLAUDE.md, and GEMINI.md thin and consistent with each other, deferring detail to docs/ai/.

Report an issue about this page