AI Agent Developer Guide for Redis Documentation

This guide helps AI agents (like myself) work more effectively on the Redis documentation codebase.

Quick Navigation for AI Agents

🎯 Start Here

Use this decision tree to find the right guidance for your task:

question: "What type of task are you working on?"
steps:
  - option: "Fixing typos, updating text, or making small content changes"
    next: "small_change"
  - option: "Adding or modifying code examples (description, difficulty, etc.)"
    next: "code_examples"
  - option: "Creating a new render hook (checklist, hierarchy, decision tree)"
    next: "render_hook"
  - option: "Working with page metadata (TOC, command info, etc.)"
    next: "metadata"
  - option: "Understanding or modifying the build system"
    next: "build_system"
  - option: "Something else"
    next: "general"

outcomes:
  small_change:
    description: "Small content updates"
    guidance: "You can proceed directly with your task. No special preparation needed. Make your changes and test them."

  code_examples:
    description: "Adding/modifying code examples"
    guidance: "Read [`for-ais-only/tcedocs/README.md`](for-ais-only/tcedocs/README.md) first, especially the sections on [Writing effective descriptions](for-ais-only/tcedocs/README.md#writing-effective-descriptions) and [Choosing difficulty levels](for-ais-only/tcedocs/README.md#choosing-difficulty-levels). Then review examples in [`content/develop/data-types/strings.md`](../content/develop/data-types/strings.md) to see the pattern in action. Once you understand the pattern, proceed with adding or modifying your code examples."

  render_hook:
    description: "Creating a new render hook"
    guidance: "Read [`for-ais-only/render_hook_docs/README.md`](for-ais-only/render_hook_docs/README.md) for an overview, then study [`for-ais-only/render_hook_docs/AI_RENDER_HOOK_LESSONS.md`](for-ais-only/render_hook_docs/AI_RENDER_HOOK_LESSONS.md) (Lessons 1-12). Review existing render hooks in [`layouts/_default/_markup/`](../layouts/_default/_markup/) as examples. Once you understand the patterns, implement your render hook."

  metadata:
    description: "Working with page metadata"
    guidance: "Read [`for-ais-only/metadata_docs/PAGE_METADATA_FORMAT.md`](for-ais-only/metadata_docs/PAGE_METADATA_FORMAT.md) for the complete structure, then [`for-ais-only/metadata_docs/IMPLEMENTATION_NOTES.md`](for-ais-only/metadata_docs/IMPLEMENTATION_NOTES.md) for implementation patterns and lessons learned. Then apply this knowledge to your metadata task."

  build_system:
    description: "Understanding the build system"
    guidance: "Read [`for-ais-only/BUILD_SYSTEM_ARCHITECTURE.md`](for-ais-only/BUILD_SYSTEM_ARCHITECTURE.md) for an overview, then check the [`Makefile`](../Makefile) and [`build/make.py`](../build/make.py) for specific implementation details. Once you understand the system, proceed with your build-related task."

  general:
    description: "Other tasks"
    guidance: "Start by reading [`for-ais-only/REPOSITORY_MAP_FOR_AI_AGENTS.md`](for-ais-only/REPOSITORY_MAP_FOR_AI_AGENTS.md) to understand the codebase structure and find documentation relevant to your task. Then proceed with your work."

📚 AI-Specific Documentation (Critical for AI Agents)

These files contain patterns, conventions, and implementation details that AI agents should reference:

Render Hooks & Interactive Components

• for-ais-only/render_hook_docs/README.md - Overview of all render hooks (checklists, hierarchies, decision trees)
• for-ais-only/render_hook_docs/AI_RENDER_HOOK_LESSONS.md - 12+ lessons on progressive enhancement, security, and patterns
• for-ais-only/render_hook_docs/DECISION_TREE_FORMAT.md - YAML format for decision trees
• for-ais-only/render_hook_docs/HIERARCHY_FORMAT.md - YAML format for hierarchies
• for-ais-only/render_hook_docs/DECISION_TREE_IMPLEMENTATION_NOTES.md - Implementation details and gotchas

Page Metadata System

• for-ais-only/metadata_docs/PAGE_METADATA_FORMAT.md - Complete metadata structure (TOC, code examples, command info)
• for-ais-only/metadata_docs/IMPLEMENTATION_NOTES.md - 10 key lessons on metadata design and implementation

Code Examples System

• for-ais-only/tcedocs/README.md - User guide for adding multi-language code examples
• for-ais-only/tcedocs/SPECIFICATION.md - Technical specification (1600+ lines of detailed architecture)

Jupyter Notebook Conversion

• build/jupyterize/README.md - Tool for converting code examples to Jupyter notebooks

🏗️ Project Architecture

"build":
    _meta:
        link: "./build/"
        description: "Build scripts and utilities"
    "components":
        _meta:
            link: "./build/components/"
            description: "Code example processing"
    "jupyterize":
        _meta:
            link: "./build/jupyterize/"
            description: "Notebook conversion tool"
    "make.py":
        _meta:
            link: "./build/make.py"
            description: "Main build orchestrator"
    "...":
        _meta:
            ellipsis: true
            description: "Other build utilities"
"for-ais-only":
    _meta:
        link: "./for-ais-only/"
        description: "AI-friendly documentation"
    "render_hook_docs":
        _meta:
            link: "./for-ais-only/render_hook_docs/"
            description: "Render hook patterns & lessons"
    "metadata_docs":
        _meta:
            link: "./for-ais-only/metadata_docs/"
            description: "Page metadata documentation"
    "tcedocs":
        _meta:
            link: "./for-ais-only/tcedocs/"
            description: "Code example system docs"
"content":
    _meta:
        link: "./content/"
        description: "Documentation pages"
    "ai-agent-resources.md":
        _meta:
            link: "./content/ai-agent-resources.md"
            description: "AI-friendly resources index"
    "develop":
        _meta:
            link: "./content/develop/"
            description: "Development guides"
    "integrate":
        _meta:
            link: "./content/integrate/"
            description: "Integration guides"
    "operate":
        _meta:
            link: "./content/operate/"
            description: "Operations guides"
"layouts":
    _meta:
        link: "./layouts/"
        description: "Hugo templates"
    "partials":
        _meta:
            link: "./layouts/partials/"
            description: "Reusable template components"
    "shortcodes":
        _meta:
            link: "./layouts/shortcodes/"
            description: "Markdown shortcodes"
    "_default":
        _meta:
            link: "./layouts/_default/"
            description: "Default page templates"
"data":
    _meta:
        link: "./data/"
        description: "Data files"
    "components":
        _meta:
            link: "./data/components/"
            description: "Language/client configurations"
    "examples.json":
        _meta:
            link: "./data/examples.json"
            description: "Generated code example metadata"
"static":
    _meta:
        link: "./static/"
        description: "Static assets"
    "js":
        _meta:
            link: "./static/js/"
            description: "JavaScript for interactive components"
    "schemas":
        _meta:
            link: "./static/schemas/"
            description: "JSON schemas for metadata validation"

🔑 Key Concepts for AI Agents

1. Progressive Enhancement: Content works without JavaScript; JS enhances it
2. Page Store Pattern: Use Hugo's page store to avoid duplicate resources
3. Metadata Layers: Page-level (head/body), per-codetabs, per-panel
4. Stable Identifiers: Separate display names from stable IDs (langId vs. id)
5. Configuration Centralization: Use config.toml for mappings, not hardcoded values

📋 Common Tasks

Adding a new render hook: See build/render_hook_docs/AI_RENDER_HOOK_LESSONS.md (Lessons 1-12)

Implementing metadata: See for-ais-only/metadata_docs/IMPLEMENTATION_NOTES.md (Implementation Checklist)

Adding code examples: See for-ais-only/tcedocs/README.md (How to add multi-language examples)

Understanding page structure: See for-ais-only/metadata_docs/PAGE_METADATA_FORMAT.md

🔍 Discovery Strategy for AI Agents

When working on this project:

1. Check for-ais-only/ directory first - Contains all meta-documentation for AI agents
2. Read the README in the relevant subsystem - Each has comprehensive docs
3. Look for IMPLEMENTATION_NOTES or LESSONS files - Capture hard-won knowledge
4. Check config.toml - Source of truth for language/client mappings
5. Review existing render hooks - In layouts/_default/_markup/

⚠️ Critical Patterns to Remember

• Always preserve source content in <pre> for non-JS users and AI agents
• Use data attributes for element-level metadata, not separate blocks
• Include location markers when duplicating metadata (head vs. body)
• Centralize configuration - Don't hardcode language/client mappings
• Test multiple page types - Metadata features must work across different content
• Use Hugo's built-in functions before building custom solutions

---

Last Updated: 2026-01-08 Purpose: Help AI agents discover and understand Redis documentation architecture