AGENTS.md guide

AGENTS.md is a repo-level instruction file aimed at autonomous coding agents—complementing human README docs with enforceable habits. The community format is described at agents.md. This guide pairs with the Cursor rules guide when teammates split between IDE and CLI agents.

Why AGENTS.md exists

README files explain the product to humans. Agents need machine-actionable boundaries: which command proves green, which folders are toxic to touch, and when to ask before committing. Without that file, every session reinvents assumptions about branch policy and test filters.

Claude Code’s quickstart assumes you start in a repository with a clear layout. AGENTS.md makes that layout legible to any vendor agent—not only Anthropic’s.

What to include

Setup. Document install steps, package manager choice, and environment variable names without values. Note default app entrypoints (SITE_ID, pnpm dev filters) so agents do not guess.

Verification. List exact commands agents must run before claiming completion—the same commands your CI enforces. Example pattern from PunkSolid monorepos: content validation and tests before a docs PR merges.

Scope rules. Directories that are off-limits without human approval: infra/, payment modules, production Terraform, or client-specific secrets paths. State no force-push and no credential commits explicitly.

Commit norms. When must the agent ask the user before git commit? PunkSolid often requires explicit user approval for commits unless the user rule says otherwise.

Architecture. One short paragraph on how packages relate (apps/, packages/, deploy scripts). Link to deeper ADRs instead of pasting entire diagrams.

Worktrees and branches. If your team uses branch worktrees (common on large monorepos), name the convention so agents do not commit from the wrong checkout.

What to avoid

Never paste credentials, webhook tokens, or production URLs with embedded secrets. Replace “be careful” with named commands and paths. Do not duplicate entire style guides—point at ESLint, Prettier, or Ruff configs.

Avoid contradictions with Cursor rules: if AGENTS.md says pnpm test and rules say npm test, agents will flip-flop.

AGENTS.md in apps/ai-network

Our monorepo’s apps/ai-network/AGENTS.md documents validate commands, deploy cautions, and first-hand experience boundaries. Trim per-app copies as the network grows; child packages should not inherit irrelevant deploy steps.

The file references the reviewed quality gate (quality.ts word minimums, FAQ counts) so content agents know when a page can graduate from draft.

Pairing with specs and methodology

AGENTS.md sets repo habits; a task spec sets deliverable acceptance. Read spec-driven development for per-task contracts and methodology for how PunkSolid combines human review with automated gates.

On migrations, AGENTS.md should name redirect verification scripts or CMS export commands—linking editorial workflow to engineering checks.

Terminal vs IDE agents

CLI agents (Claude Code and similar) read AGENTS.md at session start. Cursor also benefits from the same verify list even when .cursor/rules/ handle tone and globs.

When both tools edit one repo, keep one verify section authoritative. Document mixed-agent conventions in Claude Code vs Cursor.

Security and compliance

Regulated clients should list PII paths and audit expectations in AGENTS.md: agents must not log patient identifiers; human review is required for public copy changes.

For repos rescued after unmanaged agent sessions, start with AI code review before you trust inherited AGENTS.md content.

Maintaining the file

Treat AGENTS.md like a runbook: update it when CI commands change, when new packages land, or when deploy targets move. Stale verify commands are worse than none—they train agents to skip real gates.

Review AGENTS.md in onboarding the same day you grant repository access.

Template starter

Minimal skeleton:

1. Setup — install, env var names, default dev command
2. Verify — test, lint, typecheck, domain-specific validate
3. Scope — forbidden dirs, git policy, secret policy
4. Commits — when to ask the user
5. Architecture — one paragraph + links

Expand only when agents repeatedly fail the same way.

Delivery and coaching

PunkSolid adds or refreshes AGENTS.md during website development and Claude Code development handoffs. Optional coaching walks your team through updates when frameworks change.

Related learning

• Claude Code tutorial — first session habits
• Cursor rules guide — IDE-specific scope
• Website migration SEO checklist — when URLs must not break

PunkSolid is not affiliated with Anthropic or Anysphere; Claude Code and Cursor are mentioned only to explain how agents read your repository instructions.

Multi-package monorepos

In repositories with apps/ and packages/, AGENTS.md at the root should name which filters apply to which tasks (pnpm --filter @scope/pkg test). If only one deployable app exists, say so—agents otherwise touch shared libraries with incomplete context.

When worktrees or sparse checkouts are common, document the expected directory layout so CLI agents do not assume missing folders are bugs.

CI parity

The verify section should mirror .github/workflows or your CI provider line for line. Drift between “what AGENTS.md says” and “what CI enforces” trains agents to argue about green builds.

Add a note when local-only steps exist (Docker compose for integration tests, VPN requirements). Agents should stop and ask rather than fake success.

Versioning AGENTS.md changes

Tag significant updates in changelog or release notes when verify commands change. Teams onboarding mid-project should not run stale instructions from a wiki export.

For client handoffs, include AGENTS.md in the definition of done alongside README and runbooks.

International and accessibility expectations

If your product serves multiple locales, AGENTS.md should state whether agents may create untranslated strings or must update message catalogs together. Accessibility requirements (focus order, labels) belong here when agents frequently edit UI—not buried in a design PDF.

Open source and fork etiquette

Contributing upstream while using agents? Note issue tracker links, CLA requirements, and commit message conventions. Some foundations reject bulk AI refactors—AGENTS.md should warn maintainers.

PunkSolid delivery checklist

When we author AGENTS.md on engagement kickoff we include: install, verify, scope, commits, architecture, and explicit PunkSolid non-goals (no invented client metrics, no affiliate URLs on owned sites). Cross-link to claude-code-development when clients license Anthropic tooling.

After launch, tie AGENTS.md updates to retrospectives—especially when redirects or analytics parity exposed gaps during website migration programs.