Instructions for llms on how to create directory-level AGENTS.md/CLAUDE.md files

AGENTS_SEED.md

What are AGENTS.md files?

AGENTS.md files are short, directory-scoped “orientation docs” intended for an LLM (or a new human contributor) to quickly understand:

• What’s in this directory
• How this directory fits into the codebase (data flow, feature flow, boundaries)

The goal is to reduce repeated repo-wide exploration by making architecture and responsibilities discoverable from the filesystem.

Guidelines for creating and updating AGENTS.md

• Write them as descriptions of what exists

  • Prefer stable truths (responsibilities, boundaries, contracts) over progress status or future plans.

• Suggested structure (default sections)

  • Use these headings by default, omitting anything that doesn’t apply:
    • Contents (what files/subdirectories are here)
    • Codebase Context (what calls into this directory, what it calls out to)
    • Key flows (1-3 diagrams of the main control/data paths)
    • Contracts / Interfaces (events, APIs, message shapes, public exports)
    • State & invariants (where state lives, what must remain true)

• Use diagrams to show flows, not style

  • ASCII diagrams should highlight the control/data flow through the modules in that directory.
  • Avoid copying implementation details that are easy to read directly from code.

• Prioritize high-signal details

  • Prefer describing:
    • entry points (where execution starts in this directory)
    • authoritative modules (where the “source of truth” lives)
    • boundaries (what this directory owns vs. delegates)
    • invariants (assumptions other code relies on)

• Only mention config files when they’re notable

  • Standard tooling/config generally doesn’t belong in AGENTS.md unless it meaningfully affects architecture, runtime behavior, or developer workflow.

• Create a new AGENTS.md when a folder becomes a boundary

  • Add one when a directory starts to have a clear role (layer, feature area, service boundary, page/screen, etc.).
  • Prefer fewer, higher-signal docs over adding one to every folder by default.

• Avoid progress framing and TODO lists

  • Don’t include “next steps”, “future work”, or task tracking.
  • Keep these docs as orientation/reference material, not a plan.

• Edit them when the mental model changes

  • Update AGENTS.md when you change:
    • where state lives
    • event names/payload shapes
    • which directory owns a feature boundary
    • page/screen routing or navigation structure