Maintaining AGENTS.md

AGENTS.md is the canonical agent-facing documentation. Keep it minimal—agents are capable and don't need hand-holding. Target under 60 lines; never exceed 100. Instruction-following quality degrades as document length increases.

File Setup

• Create AGENTS.md at project root

• Create symlink: ln -s AGENTS.md CLAUDE.md

Before Writing

Analyze the project to understand what belongs in the file:

• Package manager — Check for lock files (pnpm-lock.yaml , yarn.lock , package-lock.json , uv.lock , poetry.lock )

• Linter/formatter configs — Look for .eslintrc , biome.json , ruff.toml , .prettierrc , etc. (don't duplicate these in AGENTS.md)

• CI/build commands — Check Makefile , package.json scripts, CI configs for canonical commands

• Monorepo indicators — Check for pnpm-workspace.yaml , nx.json , Cargo workspace, or subdirectory package.json files

• Existing conventions — Check for existing CONTRIBUTING.md, docs/, or README patterns

Writing Rules

• Headers + bullets — No paragraphs

• Code blocks — For commands and templates

• Reference, don't embed — Point to existing docs: "See CONTRIBUTING.md for setup" or "Follow patterns in src/api/routes/ "

• No filler — No intros, conclusions, or pleasantries

• Trust capabilities — Omit obvious context

• Prefer file-scoped commands — Per-file test/lint/typecheck commands over project-wide builds

• Don't duplicate linters — Code style lives in linter configs, not AGENTS.md

Required Sections

Package Manager

Which tool and key commands only:

Package Manager

Use pnpm: pnpm install, pnpm dev, pnpm test

File-Scoped Commands

Per-file commands are faster and cheaper than full project builds. Always include when available:

File-Scoped Commands

Commit Attribution

Always include this section. Agents should use their own identity:

Commit Attribution

AI commits MUST include:

Co-Authored-By: (the agent's name and attribution byline)

Example: Co-Authored-By: Claude Sonnet 4 <noreply@example.com>

Key Conventions

Project-specific patterns agents must follow. Keep brief.

Optional Sections

Add only if truly needed:

• API route patterns (show template, not explanation)

• CLI commands (table format)

• File naming conventions

• Project structure hints (point to critical files, flag legacy code to avoid)

• Monorepo overrides (subdirectory AGENTS.md files override root)

Anti-Patterns

Omit these:

• "Welcome to..." or "This document explains..."

• "You should..." or "Remember to..."

• Linter/formatter rules already in config files (.eslintrc , biome.json , ruff.toml )

• Listing installed skills or plugins (agents discover these automatically)

• Full project-wide build commands when file-scoped alternatives exist

• Obvious instructions ("run tests", "write clean code")

• Explanations of why (just say what)

• Long prose paragraphs

Example Structure

Agent Instructions

Package Manager

Use pnpm: pnpm install, pnpm dev

Commit Attribution

AI commits MUST include:

Co-Authored-By: (the agent's name and attribution byline)

File-Scoped Commands

API Routes

[Template code block]

CLI