ClaudeArchitectCertification.com
Methodology - Agent Conventions

AGENTS.md + CLAUDE.md: how this repo steers coding agents.

A convention emerging across the agentic-coding ecosystem: two markdown files at the repo root that tell agents (Claude Code, Codex, Cursor, and any others that read them) what this project is, how it builds, what conventions to follow, and what NOT to do. This page explains the convention with short examples you can adapt for your own project.

ConventionRepo rootCoding agents

What AGENTS.md is

AGENTS.md is a short, repo-root markdown file that announces project-wide ground rules every coding agent should respect on every turn. The audience is agents, not humans - think of it as the file you would hand a brand-new contractor on day one if that contractor was a language model. The convention is intentionally tool-neutral: Claude Code reads it, Codex CLI reads it, and any agent that has been taught to look for it reads it.

The most common content is a single sentence per rule: breaking changes in your stack, version-pinned APIs to avoid, files to never edit, conventions that are non-obvious from code. This site's AGENTS.md focuses on the "this is NOT the Next.js you know" warning - because Next 16 has breaking changes from the training data most models were exposed to.

What CLAUDE.md is

CLAUDE.md is the Claude-specific companion to AGENTS.md. It expands the AGENTS.md ground rules with Claude-specific guidance: the file convention @AGENTS.md at the top of CLAUDE.md tells Claude Code to load AGENTS.md first, then layer the Claude-specific rules on top. The pattern lets generic rules live in AGENTS.md (any agent reads them) and Claude-specific guidance live in CLAUDE.md (only Claude reads it).

This site's CLAUDE.md documents the full Next 16 + Convex + Clerk + Resend + OpenRouter stack, the secrets-boundary rule (browser never holds a secret), MCP rules, and the auth-gating contract. None of this is derivable from code alone, which is why it must live in CLAUDE.md.

Why both files live at the repo root

Both files live at the repo root because coding agents start their context-window walk at the working directory and look up the tree. A file at the repo root is the first thing read on every cold start, and it stays in context for the rest of the turn. Putting these files anywhere else (a docs subdirectory, a wiki) breaks the convention: the agent never sees them.

If you want to scope rules to a specific subdirectory, drop another CLAUDE.md inside that subdirectory. The agent layers the deeper file on top of the root file - the deeper rules win on conflicts.

An example AGENTS.md

This illustrative AGENTS.md shows project context, boundaries and verification rules. Replace these examples with instructions that fit your repository:

# AGENTS.md

## Project
A certification study site built with Next.js, React and TypeScript.

## Working rules
- Read the package scripts and framework documentation before editing.
- Reuse the shared header, footer and design tokens.
- Keep API keys and other secrets on the server.
- Preserve page titles, canonical URLs and internal links during visual edits.
- Run relevant tests and the production build before reporting completion.
- Report which checks ran and what remains unverified.

An example CLAUDE.md

This illustrative CLAUDE.md imports the shared instructions and adds a concise implementation checklist:

@AGENTS.md

# Claude-specific guidance

## Before editing
Read the components and data contracts used by the page you are changing.

## Implementation
Reuse the existing components and keep changes focused on the requested behavior.
Verify authentication and authorization on the server for protected operations.

## Review
Check desktop and mobile layouts, keyboard navigation and empty states.
Summarize the change and its validation evidence.

How to copy the pattern for your repo

  1. Create AGENTS.md at the repo root. List the framework version, the top 3 breaking-change traps, and any files agents must never edit.
  2. Create CLAUDE.md at the repo root. Open with@AGENTS.md on the first line so Claude Code inherits the general rules.
  3. Layer in your Claude-specific guidance: stack overview, key commands, file conventions, secrets boundary, anti-patterns to avoid.
  4. For subdirectory-scoped rules, drop another CLAUDE.md inside that subdirectory. Deeper rules override root rules on conflict.

Last updated

Up next: the broader methodology hub that explains the evidence tiers, refresh cadence, and corrections protocol behind every claim on this site.