agents-md-mastery

AGENTS.md Mastery

Overview

AGENTS.md is pseudo-memory loaded at session start. Every line shapes agent behavior for the entire session. Quality beats quantity. Write for agents, not humans.

Unlike code comments or READMEs, AGENTS.md entries persist across all agent sessions. A bad entry misleads agents hundreds of times. A missing entry causes the same mistake repeatedly.

Core principle: Optimize for agent comprehension and behavioral change, not human readability.

The Iron Law

EVERY ENTRY MUST CHANGE AGENT BEHAVIOR

If an entry doesn't:

• Prevent a specific mistake
• Enable a capability the agent would otherwise miss
• Override a default assumption that breaks in this codebase

...then it doesn't belong in AGENTS.md.

Test: Would a fresh agent session make a mistake without this entry? If no → noise.

When to Use

Trigger	Action
New project bootstrap	Write initial AGENTS.md with build/test/style basics
Feature completion	Sync new learnings by editing AGENTS.md directly after reviewing the diff
Periodic review	Audit for stale/redundant entries (quarterly)
Quality issues	Agent repeating mistakes? Check if AGENTS.md has the fix

What Makes Good Agent Memory

Signal Entries (Keep)

✅ Project-specific conventions:

• "We use Zustand, not Redux — never add Redux"
• "Auth lives in /lib/auth — never create auth elsewhere"
• "Run bun test not npm test (we don't use npm)"

✅ Non-obvious patterns:

• "Use .js extension for local imports (ESM requirement)"
• "Use Copilot memory for durable notes; don't invent extra workflow files"
• "SandboxConfig is in dockerSandboxService.ts, NOT types.ts"

✅ Gotchas that break builds:

• "Never use ensureDirSync — doesn't exist. Use ensureDir (sync despite name)"
• "Import from ../utils/paths.js not ./paths (ESM strict)"

Noise Entries (Remove)

❌ Agent already knows:

• "This project uses TypeScript" (agent detects from files)
• "We follow semantic versioning" (universal convention)
• "Use descriptive variable names" (generic advice)

❌ Irrelevant metadata:

• "Created on January 2024"
• "Originally written by X"
• "License: MIT" (in LICENSE file already)

❌ Describes what code does:

• "FeatureService manages features" (agent can read code)
• "The system uses git worktrees" (observable from commands)

Rule of Thumb

Signal: Changes how agent acts
Noise: Documents what agent observes

Section Structure for Fast Comprehension

Agents read AGENTS.md top-to-bottom once at session start. Put high-value info first:

# Project Name

## Build & Test Commands
# ← Agents need this IMMEDIATELY
bun run build
bun run test
bun run release:check

## Code Style
# ← Prevents syntax/import errors
- Semicolons: Yes
- Quotes: Single
- Imports: Use `.js` extension

## Architecture
# ← Key directories, where things live
packages/
├── hive-core/      # Shared logic
├── opencode-hive/  # Plugin
└── vscode-hive/    # Extension

## Important Patterns
# ← How to do common tasks correctly
Use `readText` from paths.ts, not fs.readFileSync

## Gotchas & Anti-Patterns
# ← Things that break or mislead
NEVER use `ensureDirSync` — doesn't exist

Keep total under 500 lines. Beyond that, agents lose focus and miss critical entries.

The Sync Workflow

After completing a feature, sync learnings to AGENTS.md:

1. Draft the proposed additions:

• Use Copilot memory or temporary notes if you need a staging area
• Keep each proposal to one behavior-changing point

2. Review each proposal:

   • Read the proposed change
   • Ask: "Does this change agent behavior?"
   • Check: Is this already obvious from code/files?

3. Accept signal, reject noise:

   • ❌ "TypeScript is used" → Agent detects this
   • ✅ "Use .js extension for imports" → Prevents build failures

4. Apply approved changes directly:

• Edit AGENTS.md with the approved additions and removals
• Review the diff before finalizing

Warning: Don't auto-approve all proposals. One bad entry pollutes all future sessions.

When to Prune

Remove entries when they become:

Outdated:

• "We use Redux" → Project migrated to Zustand
• "Node 16 compatibility required" → Now on Node 22

Redundant:

• "Use single quotes" + "Strings use single quotes" → Keep one
• Near-duplicates in different sections

Too generic:

• "Write clear code" → Applies to any project
• "Test your changes" → Universal advice

Describing code:

• "TaskService manages tasks" → Agent can read TaskService class
• "Worktrees are in .hive/.worktrees/" → Observable from filesystem

Proven unnecessary:

• Entry added 6 months ago, but agents haven't hit that issue since

Red Flags

Warning Sign	Why It's Bad	Fix
AGENTS.md > 800 lines	Agents lose focus, miss critical info	Prune aggressively
Describes what code does	Agent can read code	Remove descriptions
Missing build/test commands	First thing agents need	Add at top
No gotchas section	Agents repeat past mistakes	Document failure modes
Generic best practices	Doesn't change behavior	Remove or make specific
Outdated patterns	Misleads agents	Prune during sync

Anti-Patterns

Anti-Pattern	Better Approach
"Document everything"	Document only what changes behavior
"Keep for historical record"	Version control is history
"Might be useful someday"	Add when proven necessary
"Explains the system"	Agents read code for that
"Comprehensive reference"	AGENTS.md is a filter, not docs

Good Examples

Build Commands (High value, agents need immediately):

## Build & Test Commands
bun run build              # Build all packages
bun run test               # Run all tests
bun run release:check      # Full CI check

Project-Specific Convention (Prevents mistakes):

## Code Style
- Imports: Use `.js` extension for local imports (ESM requirement)
- Paths: Import from `../utils/paths.js` never `./paths`

Non-Obvious Gotcha (Prevents build failure):

## Important Patterns
Use `ensureDir` from paths.ts — sync despite name
NEVER use `ensureDirSync` (doesn't exist)

Bad Examples

Generic advice (agent already knows):

## Best Practices
- Use meaningful variable names
- Write unit tests
- Follow DRY principle

Describes code (agent can read it):

## Architecture
The FeatureService class manages features. It has methods
for create, read, update, and delete operations.

Irrelevant metadata:

## Project History
Created in January 2024 by the platform team.
Originally built for internal use.

Verification

Before finalizing AGENTS.md updates:

• Every entry answers: "What mistake does this prevent?"
• No generic advice that applies to all projects
• Build/test commands are first
• Gotchas section exists and is populated
• Total length under 500 lines (800 absolute max)
• No entries describing what code does
• Fresh agent session would benefit from each entry

Summary

AGENTS.md is behavioral memory, not documentation:

• Write for agents, optimize for behavior change
• Signal = prevents mistakes, Noise = describes observables
• Sync after features, prune quarterly
• Test: Would agent make a mistake without this entry?

Quality > quantity. Every line counts.