docs-for-agents

Docs for Agents

Generate or update a "For Coding Agents" reference page — a compressed, prescriptive reference optimized for AI coding agents working on or integrating with the project.

Principles

• Dense and declarative. Tables and code blocks over prose.
• Action-oriented. Constraint catalogs, decision dispatch, task recipes, change playbooks.
• Consistent terminology. Match the codebase exactly — no synonyms.
• Self-contained. An agent should not need to read other docs to act correctly.
• Cross-referenced. Link to existing docs where agents need deeper context.

Workflow

1. Analyze the codebase

Read all source files to extract:

• File layout and what each file contains
• Class/module hierarchy
• Import dependency graph
• Public API surface (__all__, exports, entry points)
• Constructor constraints and validation rules
• Method signatures, side effects, and state mutations
• Concurrency model and thread-safety rules
• Persistence behavior (what writes to disk, what resets state)
• Key invariants that are not obvious from type signatures

2. Check existing documentation infrastructure

Identify:

• Documentation framework and config (e.g., mkdocs.yml, zensical.toml, docs/ layout)
• Navigation structure — where to add the new page
• LLM doc generation scripts (e.g., gen_llms_full.py, llms.txt generators)
• Existing pages to cross-reference

3. Write the reference page

Create the page with these sections (omit any that don't apply to the project):

Architecture map

• File layout — table: file path → what it contains
• Class/module hierarchy — text tree showing inheritance/composition
• Import dependency flow — A → B → C diagram
• Public API exports — what's in __all__ or equivalent

Decision dispatch

• Tables mapping use-case → class/function/method
• One table per decision axis (e.g., "which class?", "which method?", "which config?")

Constraints and invariants

• Concurrency rules
• Input constraints (types, ranges, alignment, dtypes)
• Key/ID constraints
• State machine semantics (counters, flags, lifecycle)
• Resource management rules

Side effects catalog

• Table: method → disk writes, state mutations, cache updates, counter changes
• Cover all public methods that mutate state

Task recipes

• Step-by-step code examples for common integration tasks
• Patterns for typical workflows

Change playbook

• "If modifying X → also update Y, Z" checklists
• Cover every module/subsystem where a change has non-obvious ripple effects

Common mistakes

• NEVER / ALWAYS format
• Concrete negative examples with corrections
• Each mistake separated by a horizontal rule for scannability

4. Register the page

• Add to documentation navigation config
• Add to LLM doc generation scripts if they exist
• Verify build succeeds

5. Verify

• Build the docs site — confirm the page renders and nav link works
• Run any LLM doc generators — confirm the page is included in output
• Review for accuracy against the source code

Updating an existing page

When updating rather than creating:

1. Read the current for-coding-agents page
2. Read all source files to identify what changed since the page was written
3. Update affected sections — do not rewrite sections that are still accurate
4. Verify the build still passes

File naming

Use for-coding-agents.md as the filename to avoid conflicts with the AGENTS.md convention (which serves a different purpose at the repo root).