Skip to main content

AI Documentation Standards

This guide outlines how to create and maintain documentation that is highly effective for both human developers and AI agents (LLMs).

Core Philosophy​

Documentation should be deterministic, semantically dense, and structurally consistent. For an AI agent, documentation isn't just "reading material"—it's an operating manifest.

1. The Dual-Layer Strategy​

We separate documentation into two distinct layers to manage the agent's context window efficiently:

Layer 1: Durable Engineering Standards​

  • Location: AI-NOTES.md (root), AGENTS.md (root), and apps/docs/docs/.
  • Content: Architectural patterns, technical constraints, "how-to" guides, and "why" explanations.
  • Goal: Provide the "long-term memory" and foundational rules for the project.

Layer 2: Transient Agent Context​

  • Location: .agents/ and .cursorrules.
  • Content: Profiles, task-specific instructions, and immediate behavioral steering.
  • Goal: Provide the "short-term memory" and active operational guidance.

2. Writing for AI Agents​

When writing documentation intended for AI consumption, follow these principles:

Use the Diátaxis Framework​

  • Tutorials: Learning-oriented.
  • How-to Guides: Goal-oriented.
  • Explanations: Understanding-oriented.
  • References: Information-oriented. AI agents excel at parsing these categories to find exactly what they need for a specific task.

Semantically Dense Descriptions​

Avoid vague names. Instead of url, use target_browser_url. Instead of timeout, specify the unit: timeout_ms. In schema.json files for executors, the description fields should be treated as prompts that explain when and how to use the tool.

Contrast "Correct" vs. "Incorrect"​

AI agents learn best from negative constraints. Show examples of common mistakes and their verified solutions. Example:

INCORRECT: Using http://127.0.0.1:4200 for local Angular checks. CORRECT: Always use http://localhost:4200 to ensure proper host-binding in this workspace.

Leverage Structural Metadata​

  • Use Nx Project Tags (scope:, type:) to define domain boundaries.
  • Use Markdown Frontmatter in Docusaurus to provide machine-readable metadata.
  • Use Mermaid Diagrams to explain complex flows; LLMs can parse the Mermaid syntax to understand architecture.

3. Reflexive Memory (Self-Correction)​

Documentation should be a "living" entity. After an AI agent encounters a recurring error or architectural misunderstanding:

  1. Analyze the root cause.
  2. Update AI-NOTES.md with the specific "Lesson Learned".
  3. Commit the change. This ensures the agent "remembers" the fix in future sessions via the Git history and updated documentation.

4. Documentation as a Tool (MCP)​

In this repository, documentation is exposed via Model Context Protocol (MCP) servers. Ensure your documentation is easily discoverable by using consistent naming conventions and clear hierarchies.