Agent.md Is the New Code Review Memory: How Teams Can Turn Repeated Feedback Into Better AI Coding

Fabien Sanglard’s August 2026 post about using an agent.md file landed because it names a problem every AI-assisted engineering team now recognizes: the model keeps forgetting the codebase. Developers repeatedly tell coding agents the same things — avoid this abstraction, follow this error-handling pattern, do not introduce this dependency, keep this file layout, write tests this way — and then repeat the same feedback in the next session.

The practical shift is simple but important: instead of treating AI coding as a fresh prompt every time, teams can store high-signal review feedback inside the repository as persistent agent context. An agent.md file becomes a human-written operating manual for LLMs working on the repo. It is not a generic “be a senior engineer” prompt. It is a compact, opinionated, version-controlled memory layer that turns repeated review comments into instructions the coding agent and reviewer can reuse on every task.

This matters because AI coding is moving from novelty to production workflow. Founders and engineering teams are no longer asking whether an LLM can write a function. They are asking whether it can make changes that survive review, match local conventions, avoid subtle regressions, and cost less than a senior engineer cleaning up the same mistakes every day. This article shows how to use agent.md with an LLM reviewer loop to get cleaner code, fewer style regressions, and cheaper review cycles — including implementation steps, model choices, and cost estimates using current API pricing.

---

What changed: AI coding now needs repo memory, not longer prompts

The early AI coding pattern was session-based. A developer opened a chat, pasted files, described the task, corrected the model, accepted part of the output, and moved on. That worked for isolated functions. It breaks down when teams use LLMs for real pull requests.

A production repository has conventions that rarely fit inside a one-off task prompt:

• Which abstractions are encouraged or banned
• How errors should be handled
• Which modules own which responsibilities
• How tests should be structured
• How much mocking is acceptable
• Which database access pattern is safe
• How naming, logging, configuration, and migrations work
• What prior AI-generated mistakes reviewers keep rejecting

Fabien Sanglard’s agent.md idea is timely because teams are discovering that LLM code quality improves when repo-specific instructions are short, explicit, and maintained by humans who understand the codebase. The file acts like a README for machines, but unlike a broad contributor guide, it is written to prevent the model’s most common failure modes.

The market cares because AI coding cost is no longer only API cost. The expensive part is review friction. If an AI-generated pull request saves 30 minutes on implementation but costs 45 minutes in cleanup, the team loses. If agent.md removes five repeated comments from every AI-assisted PR, the same model becomes far more useful.

Why human-written agent context beats generic prompting

Generic coding prompts are weak because they optimize for plausible software engineering, not your repo. “Write clean, idiomatic TypeScript” means different things in a Next.js app, a backend service, a CLI tool, and a game engine. “Add tests” is too vague when your team has strong preferences about integration tests versus mocks. “Keep the code simple” does not tell the model which abstraction the team rejected last week.

A good agent.md is different in four ways.

First, it is local. It describes the codebase in front of the agent, not universal best practices. “All API routes must use withAuth() before reading request bodies” is better than “consider security.”

Second, it is corrective. The best entries come from review comments, failed builds, and prior AI mistakes. If reviewers keep writing “do not add a new service class for this,” that sentence belongs in agent.md.

Third, it is short enough to stay in context. A 600-1,500 word file is more likely to be read and followed than a sprawling internal wiki. The goal is to give the model the rules that change its output, not document the company.

Fourth, it is version-controlled. When the architecture changes, the instructions change in the same pull request. The agent’s memory evolves with the repo.

---

What teams can build with agent.md now

The agent.md pattern unlocks more than slightly better code generation. It lets small teams design repeatable AI engineering workflows where the model has stable expectations before it writes or reviews code.

Here are seven practical workflows teams can implement immediately.

1. Repo-aware coding agent instructions

Put the repository’s core engineering rules in agent.md, then configure your coding assistant to read it before every task. This is the baseline workflow. It reduces repeated prompting and gives the model a stable source of truth.

Useful entries include:

• “Prefer editing existing modules over creating new abstraction layers.”
• “Use existing validation helpers in src/lib/validation.”
• “Do not add runtime dependencies without explicit approval.”
• “Every bug fix needs a regression test.”
• “Use repository error types instead of throwing raw strings.”

This works especially well for founders who delegate implementation tasks to AI but still want the repo to retain a consistent style.

2. LLM pull request reviewer

Use one model to generate code and a second model to review the diff against agent.md. The reviewer does not need to understand the entire product. It needs to compare the patch to the repo rules and flag violations.

A good reviewer prompt includes:

• The diff
• The relevant files or summaries
• agent.md
• Test output
• A checklist: correctness, repo conventions, unnecessary abstractions, missing tests, dependency changes

This gives teams a cheap pre-review pass before a human sees the PR.

3. Review feedback capture loop

After human review, add repeated feedback back into agent.md. If the same comment appears twice, promote it into a rule. If a reviewer rejects an AI pattern once because it is dangerous, add a warning.

This makes the system better every week. The point is not to write perfect instructions up front. The point is to convert actual review pain into durable guidance.

4. Founder-friendly coding delegation

Non-technical or semi-technical founders can use agent.md to constrain AI coding work before hiring a larger engineering team. The file can encode simple product rules, architectural boundaries, and deployment constraints.

For example:

• “Do not change billing code without adding tests.”
• “All user-visible copy lives in content/messages.ts.”
• “Never bypass feature flags for new dashboard features.”
• “Prefer server-side validation even when client validation exists.”

This turns AI coding from “make this feature” into “make this feature inside these guardrails.”

5. Style regression prevention

Teams can run a low-cost model on every pull request to detect drift from known style decisions. This is not a full security audit. It is a convention checker that catches repeated annoyances before they reach reviewers.

Examples:

• New files with inconsistent naming
• Tests that use the wrong fixture style
• Duplicate helper functions
• New environment variables not documented
• Logging patterns that leak sensitive fields

6. Architecture boundary enforcement

agent.md can describe boundaries the model must not cross. This is valuable in monorepos and growing SaaS codebases where AI often takes the shortest path by importing from the wrong layer.

Example rules:

• “UI components cannot import from server/db.”
• “Background jobs must not call HTTP route handlers.”
• “Shared packages cannot depend on app-specific modules.”
• “Database migrations must be reversible unless explicitly marked otherwise.”

An LLM reviewer can check diffs for these violations before CI or human review.

7. Cheaper multi-model coding pipelines

Teams can reserve premium coding models for hard generation tasks, then use cheaper models for diff review, rule extraction, and test suggestion. This is where agent.md becomes a cost control tool. The model doing review gets a compact rule file instead of a full transcript of past mistakes.

[stat] 16.8x The output-token price gap between GPT-5.2 pro at $168/1M output tokens and GPT-5.2 at $14/1M output tokens

---

What to put in agent.md

A useful agent.md should be opinionated, concrete, and easy for a model to obey. Avoid motivational language. Avoid generic coding advice. Write rules that change code.

A strong starting structure:

# Agent instructions

## Project overview
One-paragraph description of what this repo does and the main runtime.

## Non-negotiable rules
- Do not add new dependencies without explicit approval.
- Prefer modifying existing modules over adding new layers.
- Every bug fix must include a regression test.

## Architecture boundaries
- API routes call services; services call repositories.
- UI components cannot import server-only modules.
- Shared utilities must not depend on app-specific code.

## Testing expectations
- Use integration tests for API behavior.
- Use unit tests only for pure utility logic.
- Do not mock database repositories in service tests unless requested.

## Common mistakes to avoid
- Do not create a new abstraction for one caller.
- Do not duplicate validation schemas.
- Do not change public API response shapes without updating tests.

## Review checklist
Before finishing, verify:
- Existing tests pass or explain failures.
- New behavior has tests.
- No unrelated formatting churn.
- No secrets, keys, or personal data in logs.

The “common mistakes” section is the highest-leverage part. It should be populated from actual review comments. If the team keeps seeing AI-generated code that is too broad, too abstract, or too clever, say so directly.

Do not make agent.md a duplicate of every README. The model does not need your company history. It needs instructions that prevent bad diffs.

Step-by-step workflow 1: Small-team AI coding loop

This workflow is for a founder or small engineering team using an AI coding agent for feature work. The goal is to reduce human cleanup while keeping the human in control.

Step 1: Create the first agent.md

Start with 20-40 rules, not a full handbook. Pull from recent pull request comments, architecture decisions, and production incidents. Keep each rule short.

Recommended sections:

1. Project overview
2. Hard rules
3. Architecture boundaries
4. Testing expectations
5. Common AI mistakes
6. Final checklist

Commit the file at the repo root as agent.md.

Step 2: Configure the coding agent to read it

In your task prompt, require the model to read agent.md before planning. If your coding tool supports persistent instructions, point it to the file. If not, paste the file or use a wrapper script that injects it into the prompt.

Use this task pattern:

Read agent.md first. Then inspect the relevant files.
Before editing, produce a short plan that references the repo rules you will follow.
Make the smallest safe change.
After editing, summarize how the diff complies with agent.md.

This forces the model to connect the task to the rules before it writes code.

Step 3: Ask for a plan before code

Do not let the agent immediately modify files on complex tasks. Require a plan with file names, test strategy, and risk points. Reject plans that violate agent.md.

A good plan should say:

• Which files will change
• Which existing patterns it will reuse
• What tests will be added or updated
• What it will not change

Step 4: Generate the patch

Use a premium or strong mid-tier coding model for the patch when the task touches core logic. Good choices include GPT-5.3 Codex, Claude Sonnet 5, GPT-5.2, or Claude Opus 5 for harder architecture work.

For small edits, use cheaper models like GPT-5 mini, Gemini 3 Flash, or DeepSeek V4 Pro.

Step 5: Run tests and capture failures

Feed test output back to the agent, but keep the instruction narrow:

Fix only the failing tests caused by this diff.
Do not refactor unrelated code.
Follow agent.md.
Explain any test behavior you changed.

This prevents the model from turning a simple failure into a broad rewrite.

Step 6: Run an LLM reviewer

Before human review, run a separate model over the diff. The reviewer should not rewrite the code. It should flag violations and classify them by severity.

Reviewer categories:

• Must fix: correctness, security, broken tests, architecture boundary violation
• Should fix: missing test, duplicated logic, inconsistent pattern
• Optional: naming, minor simplification

Step 7: Promote repeated feedback into agent.md

After the PR is merged, update agent.md only when feedback is likely to recur. Good candidates are comments reviewers have made more than once.

---

Step-by-step workflow 2: Low-cost LLM diff reviewer for every PR

This workflow is designed for teams that want a cheap automated review pass on every pull request. It pairs well with GitHub Actions, GitLab CI, or any internal review bot.

Step 1: Build the review input

For each PR, collect:

• agent.md
• The unified diff
• List of changed files
• Test output or CI status
• Optional file summaries for large changes

Do not send the entire repository by default. For most review passes, the diff plus agent.md is enough.

Step 2: Use a reviewer-specific prompt

The reviewer prompt should be strict and structured:

You are reviewing a pull request against this repository's agent.md rules.
Do not suggest broad refactors.
Do not comment on unchanged code.
Return only actionable findings.

For each finding:
- severity: must_fix | should_fix | optional
- file and line if available
- violated agent.md rule
- concise explanation
- suggested fix

This produces review comments that are easier to consume and cheaper to process.

Step 3: Route by risk

Use model routing based on the diff type:

Diff type	Recommended reviewer	Why
Docs, copy, config	GPT-5 nano or Gemini 2.5 Flash-Lite	Cheapest adequate review
Small frontend change	GPT-5 mini or Gemini 3 Flash	Good convention checking
Backend business logic	GPT-5.2 or Claude Sonnet 5	Stronger reasoning on behavior
Auth, billing, security	GPT-5.2 pro, GPT-5.6 Cyber, or Claude Opus 5	Premium review justified
Large refactor	Claude Opus 5 or GPT-5.2 pro	Better long-context synthesis

Step 4: Enforce output limits

Ask for a maximum of 10 findings and require severity. This keeps output cost predictable and prevents noisy reviews.

Step 5: Add a human approval gate

Do not auto-merge based on the LLM reviewer. The bot should reduce reviewer workload, not replace ownership. Require a human for must-fix decisions, architecture changes, billing, security, and data model changes.

Step 6: Track review yield

Measure:

• LLM comments accepted
• LLM comments dismissed
• Repeated human comments after LLM review
• Average human review time
• Number of PRs requiring second review

If the LLM misses the same issue twice, add it to agent.md.

---

Model Choice and Cost

The best agent.md workflow uses multiple models. Use strong models for code generation when mistakes are expensive. Use cheaper models for diff review, rule extraction, and style checks.

Current pricing varies widely. Here are relevant models from the AI Cost Check model database.

Model	Input / 1M tokens	Output / 1M tokens	Context	Best use in agent.md workflow
GPT-5.3 Codex	$1.75	$14	256K	Coding patches and codebase edits
Claude Sonnet 5	$2	$10	1M	Strong coding and review balance
GPT-5.2	$1.75	$14	1M	General coding, long-context review
Claude Opus 5	$5	$25	1M	Hard refactors and architecture review
GPT-5.2 pro	$21	$168	1M	Premium review for high-risk changes
GPT-5 mini	$0.25	$2	500K	Cheap PR review and simple edits
Gemini 3 Flash	$0.50	$3	1M	Low-cost diff review
DeepSeek V4 Pro	$0.435	$0.87	1M	Very cheap reviewer and patch assistant
GPT-5 nano	$0.05	$0.40	128K	Tiny rule checks and docs changes

For a typical diff review, assume:

• agent.md: 2,000 input tokens
• Diff and metadata: 10,000 input tokens
• Review output: 1,500 output tokens
• Total: 12,000 input tokens + 1,500 output tokens

Estimated cost per PR review:

Reviewer model	Cost per review	Cost per 1,000 PR reviews	Recommended use
GPT-5 nano	$0.0012	$1.20	Docs, copy, small config
DeepSeek V4 Pro	$0.0065	$6.53	Cheap default diff review
Gemini 3 Flash	$0.0105	$10.50	General PR convention review
GPT-5 mini	$0.0060	$6.00	Low-cost reliable reviewer
Claude Sonnet 5	$0.0390	$39.00	Strong default for code review
GPT-5.2	$0.0420	$42.00	Long-context review and mixed tasks
Claude Opus 5	$0.0975	$97.50	High-risk logic and architecture
GPT-5.2 pro	$0.5040	$504.00	Security, billing, critical systems

The premium reviewer is 77x more expensive than the DeepSeek V4 Pro reviewer for this review shape. That does not mean the premium model is bad. It means it should be routed to risky changes, not every CSS tweak.

Recommended model stack

For most startups and small engineering teams, use this stack:

Workflow step	Primary model	Cheaper fallback	Premium upgrade
Feature implementation	GPT-5.3 Codex	GPT-5 mini	Claude Opus 5
Bug fix with tests	Claude Sonnet 5	DeepSeek V4 Pro	GPT-5.2
Diff review	GPT-5 mini or DeepSeek V4 Pro	GPT-5 nano	Claude Sonnet 5
Security-sensitive review	GPT-5.6 Cyber	GPT-5.2	GPT-5.2 pro
Large refactor planning	Claude Opus 5	Claude Sonnet 5	GPT-5.2 pro
Rule extraction from review comments	Gemini 3 Flash	GPT-5 nano	GPT-5.2

Use AI Cost Check to plug in your actual token counts. If your diffs average 40,000 input tokens instead of 12,000, your monthly cost changes quickly. You can also compare model tradeoffs directly, such as GPT-5 vs GPT-5 mini or GPT-5 vs DeepSeek V3.2.

When premium models are overkill

Do not use a premium coding model for:

• Formatting-only diffs
• Copy changes
• Simple test snapshot updates
• Dependency-free utility functions
• Review comments that only check naming or file placement
• Re-running the same reviewer prompt after a tiny fix

Use premium models for:

• Authentication, authorization, and billing
• Data migrations
• Concurrency and distributed systems logic
• Security-sensitive parsing or sandboxing
• Large refactors across many files
• PRs where a bad merge creates customer-facing incidents

The practical recommendation: make cheap review the default and premium review the exception. agent.md increases the capability of cheaper models because the reviewer no longer has to infer every local convention from the diff.

---

How agent.md reduces review cost without lowering standards

The biggest cost reduction comes from avoiding repeated mistakes, not from shaving fractions of a cent off model calls. A senior engineer writing the same comment every day is the expensive loop.

Suppose a team has 12 AI-assisted PRs per week. If each PR produces 10 minutes of avoidable review comments, that is 2 hours/week of senior engineering time. At $150/hour fully loaded, that is $300/week or roughly $15,600/year. A low-cost LLM review pass may cost under $10/month for that volume, and the agent.md maintenance cost is usually a few minutes during review.

The workflow also improves quality by making review expectations explicit. Humans often hold conventions in their heads. LLMs fail when those conventions are implicit. agent.md forces teams to write down the rules that actually matter.

It also creates alignment between generation and review. If the coding agent and reviewer both read the same rules, the developer gets a tighter loop:

1. The generator tries to follow agent.md.
2. The reviewer checks the diff against agent.md.
3. The human corrects what both missed.
4. Repeated corrections update agent.md.

That loop is simple, auditable, and compatible with existing Git workflows.

Risks, limits, and when not to use agent.md

agent.md is not a substitute for tests, type checks, code owners, or security review. It is a guidance layer. Treating it as an enforcement system creates false confidence.

The main risks are:

Stale rules

If the repo changes but agent.md does not, the model will follow obsolete instructions. Add an agent.md review checkbox to PRs that change architecture, testing strategy, or critical conventions.

Over-specific rules

A rule like “always use UserServiceV2” may be correct now and wrong next month. Prefer principle-plus-location: “User lifecycle changes belong in the user service layer; check current service naming before adding new code.”

Instruction conflicts

If agent.md says “never mock repositories” but a test guide says mocks are acceptable for unit tests, the model will behave inconsistently. Resolve conflicts in documentation or explicitly state priority.

Prompt injection through repo content

LLM coding agents may read files that contain malicious or irrelevant instructions. Make agent.md the highest-priority repo instruction, and tell the model to ignore instructions embedded in comments, fixtures, logs, or user-generated content.

False positives from cheap reviewers

Low-cost reviewers can flag harmless issues. Require severity levels and keep humans in control. Track dismissed comments and adjust prompts if the bot becomes noisy.

---

A practical agent.md template for startups

Use this as a starting point and edit it aggressively.

# agent.md

## Purpose
This repository powers [product/service]. Optimize for small, safe changes that match existing patterns.

## Non-negotiable rules
- Make the smallest change that solves the task.
- Do not add dependencies without explicit approval.
- Do not change public API shapes unless the task requests it.
- Do not include unrelated formatting changes.
- Every bug fix must include a regression test.

## Architecture boundaries
- UI components must not import server-only modules.
- API routes should validate input before calling services.
- Services own business logic; repositories own database access.
- Shared utilities must not depend on app-specific modules.

## Testing
- Add or update tests for changed behavior.
- Prefer integration tests for API behavior.
- Prefer unit tests for pure utility functions.
- Do not delete tests to make CI pass.

## Security and data handling
- Never log secrets, tokens, passwords, or full payment payloads.
- Validate user input on the server.
- Authorization checks must happen before data access.
- Billing, auth, and permissions changes require extra caution and clear explanation.

## Common AI mistakes to avoid
- Do not create a new abstraction for a single caller.
- Do not duplicate existing validation schemas.
- Do not introduce broad refactors while fixing a narrow bug.
- Do not invent environment variables without documenting them.
- Do not silently swallow errors.

## Before final response
- Summarize files changed.
- Explain tests run.
- List any risks or follow-up work.
- Confirm how the change follows this file.

This template is intentionally plain. The value comes from replacing generic lines with your team’s specific rules over time.

Metrics to prove the workflow is working

Track the impact like an engineering process change, not a prompt experiment. Useful metrics:

Metric	Target after 4-6 weeks	Why it matters
Repeated human review comments	Down 30-50%	Shows agent.md is capturing real feedback
PRs needing second AI fix pass	Down 20-40%	Measures generation quality
LLM reviewer accepted comments	Above 50%	Indicates useful automated review
Dismissed bot comments	Below 30%	Prevents review noise
Average human review time	Down 15-30%	Converts quality into business value
Post-merge regressions from AI PRs	Down, not flat	Confirms standards are preserved

If these metrics do not improve, the issue is usually one of three things: agent.md is too generic, the reviewer prompt is too broad, or the team is using cheap models for changes that need premium reasoning.

For teams already comparing coding models, use model pages like GPT-5.3 Codex, Claude Sonnet 5, and DeepSeek V4 Pro to choose the right generation and review mix.

---

Frequently asked questions

What is agent.md for AI coding?

agent.md is a repository-level instruction file for AI coding agents. It stores project-specific rules, architecture boundaries, testing expectations, and repeated review feedback so the model does not need the same guidance re-prompted every session.

How much does an LLM code review workflow cost?

A typical diff review with 12,000 input tokens and 1,500 output tokens costs about $0.0065 with DeepSeek V4 Pro, $0.0060 with GPT-5 mini, $0.0390 with Claude Sonnet 5, and $0.5040 with GPT-5.2 pro. Use the AI Cost Check calculator with your average diff size for an exact estimate.

Which model should I use with agent.md?

Use GPT-5.3 Codex or Claude Sonnet 5 for most code generation, GPT-5 mini or DeepSeek V4 Pro for cheap diff review, and Claude Opus 5 or GPT-5.2 pro for high-risk architecture, billing, auth, or security changes.

Should agent.md replace human code review?

No. agent.md and LLM reviewers should reduce repeated comments before human review, not replace accountability. Keep human approval mandatory for security, billing, data migrations, permissions, public APIs, and large refactors.

How long should agent.md be?

Keep agent.md around 600-1,500 words for most repositories. If it grows beyond that, split background documentation into separate files and keep agent.md focused on rules that directly change AI-generated code.

---

Try the workflow on your next PR

Start with one repository, one agent.md, and one low-cost diff reviewer. Add rules only when they prevent repeated human feedback. Route premium models to high-risk changes, and use cheap reviewers for convention checks.

To estimate your own review loop cost, enter your average diff size and model mix in AI Cost Check. For model selection, compare options like GPT-5 vs GPT-5 mini, review GPT-5.3 Codex for coding tasks, and use DeepSeek V4 Pro when you need a low-cost reviewer that can run on every pull request.