====== Distributed Documentation (AGENTS.md) ======
**Distributed Documentation**, exemplified by OpenAI's **AGENTS.md** pattern, refers to an architectural practice of embedding module-specific documentation files throughout a codebase rather than maintaining centralized documentation repositories. This approach embeds contextual guidelines, architectural rules, and implementation constraints at the point where developers and AI agents make decisions, reducing cognitive load and minimizing implementation errors.

===== Overview and Rationale =====
Traditional software documentation practices typically centralize all architectural guidance, API specifications, and coding standards in dedicated repositories or wiki systems. The distributed documentation approach inverts this model by placing documentation artifacts directly adjacent to the code they describe. Each module, service, or functional area maintains its own **AGENTS.md** file containing rules, constraints, and architectural context specific to that component (([[https://alphasignalai.substack.com/p/a-closer-look-at-harness-engineering|AlphaSignal - Distributed Documentation in Agent Engineering (2026]])).

This pattern proves particularly valuable in agent-based systems where autonomous code generation and modification occurs. By embedding documentation at the point of action, agents encounter relevant constraints and guidelines when making architectural decisions, making correct implementations "obvious" while simultaneously making incorrect choices "harder to make accidentally" (([[https://alphasignalai.substack.com/p/a-closer-look-at-harness-engineering|AlphaSignal - Distributed Documentation in Agent Engineering (2026]])).

===== Technical Implementation =====
The AGENTS.md pattern typically includes several key components within each module's documentation file:

**Architectural Rules and Constraints**: Module-specific restrictions on how code should be structured, naming conventions to follow, and design patterns to apply. These rules provide immediate guidance without requiring context-switching to external documentation sources.

**Interface Specifications**: Clear definitions of input parameters, return types, and expected behavior for module exports. This information supports both human developers and code-generation agents in understanding correct usage patterns.

**Dependency Guidelines**: Rules governing which external modules can be imported, preferred integration patterns, and anti-patterns to avoid. This prevents circular dependencies and maintains architectural integrity.

**State Management Patterns**: Documentation of how module state should be managed, persistence requirements, and concurrency considerations (([[https://alphasignalai.substack.com/p/a-closer-look-at-harness-engineering|AlphaSignal - Distributed Documentation in Agent Engineering (2026]])).

The placement of these specifications directly within module directories ensures agents and developers encounter them during implementation tasks, reducing the likelihood of architectural violations and improving code consistency across the system.

===== Applications in Agent-Based Systems =====
Distributed documentation proves especially valuable in systems employing code-generating or code-modifying agents. When an agent receives a request to implement functionality or modify existing code, it can immediately access the AGENTS.md file relevant to the target module. This contextual information guides the agent toward compliant implementations without requiring external knowledge retrieval or context assembly.

Several use cases benefit from this pattern:

**Automated Code Generation**: When agents generate new code within a module, they reference the module's AGENTS.md file to ensure the generated code adheres to established patterns and constraints.

**Refactoring Operations**: During code refactoring tasks, agents consult distributed documentation to maintain architectural consistency across modifications.

**Integration Tasks**: When adding new functionality that spans multiple modules, distributed documentation helps agents understand interdependencies and integration constraints for each module involved (([[https://alphasignalai.substack.com/p/a-closer-look-at-harness-engineering|AlphaSignal - Distributed Documentation in Agent Engineering (2026]])).

===== Advantages and Challenges =====
The distributed documentation approach offers several advantages: **locality of reference** keeps relevant information proximate to decision points, **reduced cognitive overhead** eliminates context-switching between code and centralized documentation, and **improved agent compliance** with architectural rules through immediate constraint awareness.

However, practical challenges emerge in implementation. **Documentation consistency** across multiple modules requires governance mechanisms to prevent conflicting guidelines in interdependent components. **Maintenance burden** increases as documentation must be updated in multiple locations when cross-cutting architectural changes occur. **Discovery challenges** may arise when developers or agents need to understand system-wide patterns versus module-specific rules.

Additionally, the effectiveness of this approach depends significantly on agent sophistication. Agents must reliably locate and parse distributed documentation files, correctly interpret constraints, and apply guidelines appropriately (([[https://alphasignalai.substack.com/p/a-closer-look-at-harness-engineering|AlphaSignal - Distributed Documentation in Agent Engineering (2026]])).

===== Relationship to Software Architecture Patterns =====
Distributed documentation aligns with established software engineering principles. The pattern reflects principles from **domain-driven design**, where bounded contexts maintain their own guidelines and specifications. It also relates to **documentation-driven development** methodologies that emphasize keeping documentation proximate to implementation, and supports **constraint-based programming** approaches where rules are made explicit at points of decision.

The pattern particularly supports **architecture decision records** (ADRs) when applied at the module level, allowing teams to document why specific architectural choices were made and what constraints those choices impose on future development within that module.

===== Current Status and Adoption =====
While originating from OpenAI's internal engineering practices, the distributed documentation pattern remains relatively specialized in adoption. Its primary use case involves organizations employing code-generation agents for development tasks or maintaining large systems where architectural consistency proves critical. As agent-based development tools mature and autonomous code modification becomes more prevalent in enterprise environments, distributed documentation approaches may see broader adoption across organizations seeking to guide agent behavior through embedded contextual constraints.


===== See Also =====

  * [[agent_context_files|Agent Context Files]]
  * [[markdown_agent_definitions|Markdown Agent Definitions]]
  * [[api_tool_generation|API Tool Generation: Doc2Agent and LRASGen]]
  * [[openagents|OpenAgents: An Open Platform for Language Agents in the Wild]]
  * [[swe_agent|SWE-agent: Agent-Computer Interface for Software Engineering]]

===== References =====