Skip to content

AGENTS.md

Latest commit

 

History

History
124 lines (83 loc) · 5.56 KB

AGENTS.md

File metadata and controls

124 lines (83 loc) · 5.56 KB
Raw

CRITICAL: ALWAYS FOLLOW THESE RULES. DO NOT FORGET, DO NOT DEVIATE. SUBAGENTS MUST ALSO ADHERE.

AGENTS.md - Directory Context System (HIGH PRIORITY)

AGENTS.md files are your first stop when working in or examining any directory. They exist to eliminate grep-heavy exploration and reading full files that may be unnecessary.

Before Working in a Directory OR Investigating an Issue

  1. Check if AGENTS.md exists in that directory (or nearest ancestor)
  2. If exists: Read it first—it tells you where things are, key patterns, gotchas
  3. If missing: Note it, but don't create during work—update after completing your changes

Efficient Navigation (How to Use AGENTS.md)

AGENTS.md is a quick reference to find things - not a replacement for reading source code when it is necessary.

  • Use AGENTS.md to navigate: Find the right files quickly without grepping the whole tree
  • Then read the actual source files you need to work with
  • Update AGENTS.md after completing your changes (not during—see below)

Hierarchical Documentation Pattern

AGENTS.md files form a parent→child reference hierarchy:

  • Leaf directories: Document files, patterns, and gotchas in detail
  • Parent directories: Reference child AGENTS.md files, don't duplicate content

This prevents duplication and keeps documentation maintainable. When reading:

  1. Start at the nearest AGENTS.md
  2. Follow references to child AGENTS.md for more detail
  3. Go up to parent AGENTS.md for broader context

Eligibility Criteria (When a Directory Needs AGENTS.md)

A directory NEEDS an AGENTS.md if:

  • Contains 3+ source files, OR
  • Contains subdirectories with their own AGENTS.md files, OR
  • Represents a logical module, feature, or component group that agents will frequently reference

A directory does NOT need an AGENTS.md if:

  • Build output: dist/, .next/, build/, coverage/
  • Dependencies: node_modules/, vendor/
  • Contains only 1-2 trivial files
  • Contains only config files (unless project root)

When to Update AGENTS.md

Timing: Update AFTER completing your changes, not during. This ensures:

  • You understand the full scope of changes before documenting
  • You don't document work-in-progress that might change
  • Documentation reflects the final state

Workflow exception: If you're a subagent within a multi-step workflow (e.g., ship-story, dev-story, epic-runner, code-review), skip AGENTS.md updates—the orchestrator handles documentation as a final step.

One-off agents (not part of a workflow) should update AGENTS.md directly after completing their work.

Update the nearest AGENTS.md when you:

  • Add new files to a directory (add to Key Files table)
  • Add new modules, endpoints, or major components
  • Discover patterns or gotchas future agents should know
  • Change directory structure or key file locations
  • Fix bugs caused by missing context (add to Gotchas to prevent recurrence)

Propagate upward when the parent's description becomes inaccurate.

Don't let files be forgotten: When adding files to a directory, ensure they're documented in the nearest AGENTS.md's Key Files table or referenced appropriately.

Batch Documentation

Use /document to create or refresh AGENTS.md files across the codebase:

  • /document - Full project documentation
  • /document path/to/subtree/ - Scoped to a subtree

The command uses parallel subagents and bottom-up ordering (children before parents).

Template

Use docs/templates/AGENTS.md.template as a starting point.

Reference Diagrams - Scoped Context Loading (HIGH PRIORITY)

Diagram files in docs/ provide visual, AI-readable reference for specific system aspects. Each file is self-contained — load ONLY the file relevant to your current work.

Loading Rules

  • Load only what you need. Pick the 1-2 docs relevant to your task.
  • Use /understand-context {topic} to load a reference doc by topic name.
  • Or read the file directly (e.g., docs/{topic}.md).

Diagram Maintenance (AFTER completing changes)

Like AGENTS.md, update the relevant diagram file AFTER finishing your work.

Workflow exception: Same as AGENTS.md — if you're a subagent in a multi-step workflow, skip diagram updates; the orchestrator handles them.

Always Load Context Before Changes

  • Project patterns: Root AGENTS.md → "Coding Patterns" section (authoritative)
  • Directory navigation: Nearest AGENTS.md (hierarchical; closest wins for local context)

Dev Rules

Context Efficiency (CRITICAL - Prevents Token Explosion)

Read files LAZILY, not eagerly. The goal is to start implementation with <500 lines of context.

DO NOT do these things:

  • Read every file in Contract > Consumes to "understand dependencies"
  • Read multiple similar files to "follow the pattern"
  • Read large utility files to understand helpers
  • Read AGENTS.md for every directory in the dependency chain

DO these things instead:

  • Use the story's "Reference Patterns" section - patterns are already inlined
  • Read AGENTS.md ONLY for directories where you CREATE/MODIFY files
  • Read ONE representative file if you need to understand a pattern (not all of them)
  • Treat Contract > Consumes as REFERENCES, not a reading list

If you've read >1000 lines before writing code, STOP. Something is wrong - the story should have what you need.

General Dev Rules

  • Default to direct git commands rather than git -C
  • When running tests, spawn an appropriate number of subagents to maximize compute
  • Use {test_command} to run tests, {typecheck_command} to typecheck, {lint_command} to lint