Agents and Workspace Rules

What is an AGENTS.md File?

An AGENTS.md file serves as the onboarding handbook for an AI coding assistant entering a repository. It provides the agent with project context, architectural boundaries, coding preferences, and operational rules so that it behaves like an experienced human collaborator. See What Is AGENTS.md? How to Write One in 2026 (Tembo).

[!NOTE] Context Budget Caution: AGENTS.md is automatically loaded into the AI agent’s context window on every turn. Keep it concise, imperative, and focused on essential constraints to avoid filling up the token budget.

Comparing README.md, DEVELOPER.md, and AGENTS.md

Documentation is stratified by audience and purpose:

Document Primary Audience Core Focus Style & Scope
README.md Users & contributors Project overview, installation, and quick start High-level, welcoming
DEVELOPER.md Human developers Architecture, system design, and module boundaries Conceptual, diagram-heavy
AGENTS.md AI coding agents Mandatory constraints, conventions, and test commands Strict, concise, imperative

Cascading Hierarchy: User, Project, and Subfolder

AI instructions operate under a cascading hierarchy where more specific rules override broader baselines:

User-Level Rules (~/.agents/AGENTS.md)

Sets universal developer habits, safety boundaries, and global preferences across all projects on your machine.

  • Single Source of Truth: Use ~/.agents/AGENTS.md (see template in Global AGENTS.md Template).

  • Tool Bridging: Symlink vendor-specific config files back to your canonical standard file:

    mkdir -p ~/.agents ~/.gemini/config ~/.claude
cp prompts/global_agents_template.md ~/.agents/AGENTS.md
ln -sf ~/.agents/AGENTS.md ~/.gemini/config/AGENTS.md
ln -sf ~/.agents/AGENTS.md ~/.claude/CLAUDE.md

Project-Level Rules (./AGENTS.md & .agents/)

  • Root AGENTS.md (Standard): Visible to GitHub browsers and recognized by tools like Antigravity, Claude Code, Cursor, and Copilot.

  • .agents/ Folder (Workspace Root): A hidden configuration directory used by agent harnesses (like Antigravity) for skills (.agents/skills/) and rules. If using both, make .agents/AGENTS.md a simple pointer:

    # Project AI Guidelines
See [AGENTS.md](/Documentation/AGENTS.html) at the repository root.

Subdirectory Rules

Nested AGENTS.md files (e.g., in packages/core/AGENTS.md or quarto/AGENTS.md) apply targeted constraints to specific subdirectories (or monorepos) without cluttering the top-level project rules.

What to Include at Each Level

User-Level (~/.agents/AGENTS.md)

  • Safety Boundaries: No committing secrets/.env, ask before destructive edits.
  • Git Conventions: Commit message format, branch naming, no automated push.
  • Communication Tone: Concise responses, complete drop-in diffs.
  • Coding Style Defaults: Type hinting, docstring conventions.

Project-Level (./AGENTS.md)

  • Project Structure: Key directory layouts and component paths.
  • Verification Commands: Build and test suites (quarto render, pytest, R CMD check).
  • Domain Conventions: Package namespacing, specific data schemas.
  • Version Rules: Handling legacy files or migration patterns.

Structuring Project Rules with the CRAFT Framework

To keep project AGENTS.md files token-efficient (20–35 lines) and structured for small and large language models alike, organize them using the CRAFT framework:

CRAFT Element Purpose in AGENTS.md Focus
C — Context Repo identity & structure Purpose, active URLs, key folders (R/, python/, docs/), config files
R — Role Persona & domain expertise Specific role (e.g. Bioinformatics R Developer, Geospatial Python Engineer)
A — Action & Verification Build, test, & operational workflow Local checks (devtools::check(), pytest, quarto render), boundaries
F — Format & Conventions Repo-specific style rules Explicit namespacing (pkg::func()), roxygen2 tags, type hints, version rules
T — Tone & Collaboration Response constraints Direct, concise, complete drop-in diffs, empirical verification

Repository Archetypes

Ready-to-use CRAFT templates for each archetype are cataloged in Agents CRAFT Templates:

  1. Pure R Package / Shiny App: Context (R/, man/, inst/), Role (R package developer & Shiny architect), Action (devtools::document(), devtools::test(), devtools::check()).
  2. Pure Python / Data Science: Context (src/, tests/, virtualenv), Role (Scientific Python & ML engineer), Action (pytest, ruff check, mypy).
  3. Dual R + Python Polyglot Repos: Context (multi-language layout), Role (Polyglot software engineer), Action (separate test suites for R and Python).
  4. Documentation & Publishing: Context (quarto/, _quarto.yml, Jekyll), Role (Technical documentation architect), Action (quarto render, .nojekyll).
  5. Technical & Discursive Writing: Context (manuscript/, notes/), Role (Academic co-author & research reviewer), Action (structural verification, tracked revision diffs).

Real-World AGENTS.md Examples

This site uses Just the Docs, a documentation theme for Jekyll.