A Documentation Standard for Human ↔ Agent Collaborative Codebases
SAGE defines a hybrid documentation system optimized for codebases where both humans and AI coding agents (Claude Code, Codex, Cursor, etc.) collaborate. It addresses critical challenges in agent-assisted development:
- Preventing code duplication - Agents discover canonical homes and existing alternatives before creating new code
- Making architecture explicit - The "why" and "why not" are machine-discoverable
- Enforcing constraints - Rules are extractable via deterministic parsing (no NLP required)
- Minimizing drift - Parameter docs are co-located with signatures
- Serving dual audiences - Documentation works for both humans and agents
SAGE introduces a machine-parseable Contextual Relationship Graph embedded in docstrings using @ tags. These tags encode:
| Concept | Purpose |
|---|---|
| Canonical ownership | "Where does this live?" |
| Similarity/disambiguation | "Don't reinvent this" |
| Extension points | Safe extension vs sealed internals |
| Dependency injection | Lifecycle and collaborator expectations |
| Anti-patterns | Warnings tuned to agent failure modes |
"""HTTP client implementations for external service communication.
@notice: |
Canonical async HTTP client for outbound service calls.
Use create_http_client() or dependency injection; do not instantiate directly.
@dev: |
Repository-adapter pattern. All HTTP clients MUST be obtained through DI/factory.
Agents MUST NOT create parallel HTTP implementations.
@graph:
id: services.http_client
provides:
- services.http_client:HTTPClient
- services.http_client:create_http_client
consumes:
- config.http:HTTPClientConfig
- observability:Logger
pattern: repository-adapter
@similar:
- id: services.grpc_client
when: "Use for gRPC; this module is HTTP-only."
@agent-guidance:
do:
- "Use DI/factory to obtain HTTPClient instances."
do_not:
- "Create new HTTP client classes."
- "Use requests/urllib directly in production code."
"""SAGE synthesizes strengths from multiple documentation approaches:
| Approach | Influence |
|---|---|
| Uvicorn-style minimalism | Prefer type hints and descriptive names; avoid drift-prone prose |
| FastAPI-style co-location | Document parameters inline with Annotated[..., Doc(...)] |
| Google/pydantic-ai narrative | Keep familiar summary + optional examples for humans |
| Cursor-style discovery | Extract metadata into .sage/ artifacts agents can query on-demand |
| NatSpec (Solidity) | Audience-separated narrative (@notice vs @dev), inheritance (@inheritdoc) |
@graph- Component relationships (provides, consumes, pattern)@similar- Disambiguation ("use X instead when...")@canonical-home- Authoritative location for a concept@replaces- Migration from deprecated components
@pattern- Design pattern with rationale and violation consequences@extends- Allowed extension points vs sealed internals@collaborators- Dependency injection and lifecycle@implements- Protocol/interface implementation
@agent-guidance- Do/don't rules for agents@anti-patterns- Common mistakes with alternatives@prefer-over- Why to use this instead of alternatives
@pure- Referential transparency declaration@total- Totality (produces output for all valid inputs)@effects- Side effects (state, I/O, external, environment)@errors- Recoverable vs terminal error categories
@notice- User-facing description (API docs, tooltips)@dev- Developer/agent context (invariants, caveats)
@custom:<name>- Project-specific metadata (e.g.,@custom:stability: stable)
SAGE recommends extracting doc metadata into .sage/ artifacts:
.sage/
├── index.json
├── graph.json
├── patterns.json
├── anti-patterns.json
├── agent-guidance.json
├── canonical-homes.json
├── components/
│ ├── services.http_client.json
│ └── services.http_client.HTTPClient.json
└── similar/
└── http-clients.md
Agents load only what's needed, enabling efficient navigation of large codebases.
SAGE supports incremental adoption:
| Level | Scope | Tags |
|---|---|---|
| Level 1 (Minimal) | Key modules | @graph, @similar, @agent-guidance |
| Level 2 (Standard) | Significant classes | Add @pattern, @collaborators, @anti-patterns, @sensitivity |
| Level 3 (Full) | Complete system | Extraction + CI validation + MCP querying |
Before creating new code, agents MUST:
- Read relevant
@graphblocks - Check
@similarfor existing alternatives - Respect sealed internals (
@sealed,@extends.sealed) - Follow DI/lifecycle (
@collaborators) - Avoid documented
@anti-patterns - Prefer canonical construction paths (
@factory-for,@canonical-home)
SAGE defines validation rules at ERROR, WARN, and INFO levels:
| Rule | Level | Description |
|---|---|---|
| V001 | ERROR | Non-trivial modules MUST have @graph |
| V002 | ERROR | Significant class docstrings MUST include @pattern |
| V003 | ERROR | Classes with injected deps MUST include @collaborators |
| V004 | ERROR | Attribute docstrings MUST include @sensitivity |
| C001 | ERROR | Sealed items MUST NOT be subclassed/called externally |
SAGE can be paired with a knowledge-graph MCP server that:
- Queries
.sage/extracted metadata - Enriches with AST symbol tables and import graphs
- Proposes doc updates (with human approval for non-mechanical changes)
The complete specification is available in spec.md, including:
- Detailed tag syntax and parsing rules
- Complete templates for modules, classes, methods, and attributes
- JSON schema for extraction outputs
- Validation rule definitions
| Version | Date | Status |
|---|---|---|
| 1.3.6 | 2026-01-25 | Release Candidate (Implementable) |
| 1.3.5 | 2026-01-25 | Pre-release draft |
- Fixed tag grammar to support
@custom:<name>without contradicting base grammar - Enforced "two value forms" (scalar or block, no hybrid)
- Standardized multi-line
@notice/@devvia YAML block scalars - Added
@concurrencyas clearer replacement for@thread-safety - Aligned JSON extraction examples with schema
MIT License. (c) 2025-2026 SAGE Contributors