Documentation Governance

A systematic approach to maintaining consistent, accurate documentation across all AI tools and contexts.

Single Source of Truth

The Guardrails-AI project follows a single source of truth approach to documentation. This means all standards, guidelines, and requirements are defined once in canonical documents, then derived and optimized for specific AI tools.

Why Single Source of Truth?

• Consistency - All AI tools follow the same standards
• Maintainability - Update once, propagate to all tools
• Accuracy - Reduces documentation drift and conflicts
• Trust - Developers know where to look for authoritative information

Automated Synchronization (New!)

To eliminate manual effort and prevent configuration drift, AI Guardrails includes an automated standards synchronization system with preprocessing and tool-specific optimization.

CONTEXT.md → Parser → Preprocessor → AI Enhancement → Tool Configs
  (source)      (extract)   (transform)    (optional)      (outputs)
                             
                             ┌─→ Cursor (.mdc, imperative)
                             ├─→ Claude (.md, conversational)
                             ├─→ Copilot (.md, concise)
                             ├─→ Aider (.yml, structured)
                             └─→ Continue.dev (.yaml, rules)

How It Works

Step 1: Update CONTEXT.md (human edits canonical source)

vim CONTEXT.md
# Add new rule: "Never use eval() in Python"

Step 2: Run Sync Script (automation handles the rest)

./scripts/sync-standards.sh

# Automatically:
# - Parses CONTEXT.md
# - Transforms for each tool's style
# - Generates optimized configs
# - Validates consistency

Step 3: Review & Commit (human verifies changes)

git diff  # Review changes
git commit -am "Add rule: no eval() in Python"

Tool-Specific Preprocessing

The same rule transforms differently for each AI tool's optimal style:

## Never Use eval()

Python code MUST NOT use eval().
This is a security vulnerability.

❌ WRONG:
result = eval(user_input)

### Never Use eval()

You must never use eval() in Python.

Why this matters:
eval() can execute arbitrary code
and is a major security risk.

## No eval()

Never use eval() - security risk.

# ❌ Bad: eval(user_input)
# ✅ Good: ast.literal_eval()

Benefits

• 70% Time Savings: 15-30 minutes → 2 minutes per update
• Zero Configuration Drift: All tools automatically synchronized
• Tool Optimization Maintained: Each tool gets best format
• Validation Included: Automatic consistency checks
• Optional AI Enhancement: Use GPT-4/Claude for natural language refinement

Status & Documentation

✅ The synchronization system is IMPLEMENTED and ready for production use!

• 📄 STANDARDS_SYNC_DESIGN.md - Full technical architecture
• 🚀 STANDARDS_SYNC_QUICKSTART.md - Quick start guide
• 🧪 sync-standards-poc.py - Working proof of concept

Documentation Hierarchy

Level 1: Canonical Documents

These are the master documents that define all project standards:

Level 2: Tool-Specific Configurations

These files are derived from the canonical documents and optimized for specific AI tools:

• .cursor/rules/*.mdc - Cursor IDE rules (scoped, prioritized)
• CLAUDE.md - Claude Desktop instructions (conversational)
• .claudeprompt - Claude Projects (concise)
• .github/copilot-instructions.md - GitHub Copilot (example-heavy)
• .aider/.aider.conf.yml - Aider config (YAML, auto-reads CONTEXT.md)
• .continue/config.yaml - Continue.dev (rules + prompts)

Documentation Formatting Standards

Markdown Standards

Example: Properly Formatted Markdown

# Security Standards

## Never Commit Secrets

API keys, tokens, and passwords must NEVER be committed to the repository.

### Correct Approach

```python
import os

# Load from environment
api_key = os.environ.get("API_KEY")
if not api_key:
    raise ValueError("API_KEY not set")
```

### Incorrect Approach

```python
# ❌ NEVER do this!
api_key = "sk-1234567890abcdef"
```

## File Requirements

1. All code must pass pre-commit hooks
2. Type hints required for Python functions
3. Docstrings required for public APIs

Documentation File Types

Markdown (.md)

• Use for: Documentation, guides, standards
• Linter: markdownlint
• Config: .pymarkdown.json

MDC (.mdc)

• Use for: Cursor rules only
• Format: YAML frontmatter + Markdown
• Required fields: title, priority, scope

YAML (.yaml)

• Use for: Configuration files
• Extension: .yaml (NOT .yml)
• Indentation: 2 spaces
• Linter: yamllint

Documentation Maintenance Process

When Standards Change

🚀 Automated Method (Recommended - Available Now!)

With the automated synchronization system:

1. Update CONTEXT.md

   # Edit the canonical document
   vim CONTEXT.md
   # Add your new rule or update existing standard

2. Run sync script

   # Automatic preprocessing and tool-specific transformation
   ./scripts/sync-standards.sh
   
   # With AI enhancement (optional)
   ./scripts/sync-standards.sh --with-ai

3. Review & commit

   git diff  # Review all changes
   git commit -am "Add rule: [rule name]"

Time savings: 15-30 minutes → 2 minutes per update (70%+ reduction)

📝 Manual Method (Current)

Until automation is implemented, follow the manual process:

1. Update CONTEXT.md first

   # Edit the canonical document
   vim CONTEXT.md
   
   # Commit with clear message
   git add CONTEXT.md
   git commit -m "docs: update Python type hints standard"

2. Propagate to tool-specific files

   # Update Cursor rules
   vim .cursor/rules/004_python_standards.mdc
   
   # Update Claude instructions
   vim CLAUDE.md
   
   # Update Copilot instructions
   vim .github/copilot-instructions.md
   
   # Commit all changes together
   git add .cursor/ CLAUDE.md .github/
   git commit -m "docs: propagate Python standards to all AI tools"

3. Test with AI tools
   • Open project in Cursor - verify rules load
   • Open Claude - verify CLAUDE.md is read
   • Test Copilot completions follow new standards

Manual time: 15-30 minutes per update

Version Control

Documentation follows semantic versioning principles:

• Major change - Breaking changes to standards (e.g., new security requirement)
• Minor change - New guidelines or best practices (e.g., add type hint examples)
• Patch change - Clarifications, typo fixes, formatting improvements

Documentation Requirements

All Documentation Must

# Markdown linting
pre-commit run markdownlint --files CONTEXT.md

# YAML linting
pre-commit run yamllint --files .cursor/rules/001_workspace.mdc

This document is derived from CONTEXT.md.
For the canonical version, see: CONTEXT.md

Code Examples in Documentation

All code examples must:

• ✓ Be syntactically correct
• ✓ Follow the standards they demonstrate
• ✓ Include language identifier in fenced blocks
• ✓ Show context (imports, full function, not just snippets)
• ✓ Use realistic variable names (not foo/bar)

Cross-References

Link related documentation:

## Security Standards

See also:
- [Pre-commit Hooks](./pre-commit-hooks.html) - Automated secret detection
- [CI/CD](./ci-cd.html) - Security scanning in pipelines
- [CONTEXT.md](https://github.com/christopherpaquin/Guardrails-AI/blob/main/CONTEXT.md) - Full security requirements

Pre-commit Checks

All documentation changes are validated by pre-commit hooks:

• markdownlint - Markdown style and syntax
• trailing-whitespace - Remove trailing spaces
• end-of-file-fixer - Ensure newline at end
• check-yaml - Validate YAML syntax
• mixed-line-ending - Fix CRLF/LF issues