DEV Community: AgentBrief Studio

7 reasons coding agents ignore your AGENTS.md (and how to fix them)

AgentBrief Studio — Tue, 11 Aug 2026 02:05:09 +0000

An AGENTS.md file should make a coding agent safer and faster. But many instruction files become background noise: long, generic, contradictory, or impossible to verify.

Here are seven common failure modes—and the smallest fix for each one.

1. The instructions describe aspirations, not commands

Weak:

Write clean, production-ready code.

Better:

Before finishing:
- run npm test
- run npm run lint
- do not modify generated files in src/generated/

Agents act more reliably on observable rules than on adjectives.

2. The file ignores repository boundaries

A root-level instruction file is useful, but a monorepo often needs narrower rules. Put specialized guidance closer to the code it governs:

/
├── AGENTS.md
├── apps/
│   └── web/
│       └── AGENTS.md
└── packages/
    └── database/
        └── AGENTS.md

The root file should define shared policy. Nested files should only add or override rules that genuinely differ.

3. The commands are not copy-pasteable

"Run the tests" creates ambiguity. Which tests? From which directory? With which runtime?

Prefer exact commands:

Validation from repository root:
1. npm ci
2. npm run typecheck
3. npm test -- --runInBand
4. npm run build

If a command is slow or optional, say so explicitly.

4. There is no definition of done

A coding agent needs an exit condition. A useful acceptance checklist might be:

requested behavior is implemented
existing public APIs remain compatible
relevant tests cover the change
lint, typecheck, and build pass
no secrets, generated artifacts, or unrelated refactors are included
the final response lists changed files and verification results

That turns a vague request into a checkable delivery.

5. The file mixes permanent policy with task-specific context

AGENTS.md should contain durable repository guidance: architecture, commands, boundaries, conventions, and validation.

The current task should live in the prompt or a separate brief:

## Objective
Add rate limiting to the public API.

## In scope
- middleware
- configuration
- tests

## Out of scope
- auth redesign
- database migration

## Acceptance criteria
- returns 429 after the configured threshold
- includes Retry-After
- existing API tests still pass

Keeping the two layers separate makes both easier to maintain.

6. Failure recovery is missing

Agents need to know what to do when the happy path breaks.

Add a compact recovery rule:

If validation fails:
1. determine whether the failure predates your change
2. fix failures caused by your change
3. do not weaken or delete tests to make them pass
4. report any verified pre-existing failure with the exact command and error

This prevents silent test deletion and vague "could not verify" handoffs.

7. The file is too long to scan

An instruction file is an operational interface, not a company handbook. Put the highest-value rules first:

repository map
exact commands
scope boundaries
coding conventions that are unique to the repo
validation checklist
recovery rules

Link to deeper documentation instead of duplicating it.

A compact starter template

# AGENTS.md

## Repository map
- src/: application code
- tests/: automated tests
- docs/: user-facing documentation
- generated/: do not edit manually

## Working rules
- keep changes scoped to the request
- preserve public API compatibility unless explicitly requested
- follow the nearest existing pattern before adding a new abstraction
- never commit credentials or local environment files

## Validation
Run from the repository root:
- npm run lint
- npm run typecheck
- npm test
- npm run build

## Definition of done
- acceptance criteria are met
- relevant tests are added or updated
- validation passes
- final response summarizes changes and commands run

## Failure recovery
Do not bypass failing checks. Fix failures introduced by the change and clearly report verified pre-existing failures.

The template is intentionally small. The value comes from adapting it to the repository's real commands, architecture, risks, and release process.

I published a free AgentBrief starter with reusable examples.

If you want the complete reusable library, AgentBrief Pro is available for US$25 on itch.io. It includes 18 AGENTS.md patterns, 12 task briefs, 8 recovery playbooks, and 5 quality gates as editable Markdown.

If you want a repo-specific audit and custom AGENTS.md delivered in one day, the US$25 Fiverr package is the hands-on option.

What instruction has made the biggest difference in your coding-agent workflow?

How to Write an AGENTS.md for Codex, Claude Code, and Cursor

AgentBrief Studio — Tue, 11 Aug 2026 01:12:24 +0000

An AI coding agent can only work safely with the context it receives. A good AGENTS.md gives that context once, close to the code, so every task starts with the same commands, boundaries, and definition of done.

This guide shows a practical structure you can use with Codex, Claude Code, Cursor, GitHub Copilot, and other repository-aware coding agents.

What an AGENTS.md file should do

An AGENTS.md is not a long prompt or generic advice. It should answer the questions an experienced contributor would ask before editing:

What does this repository contain?
Which commands install, test, lint, type-check, and build it?
Which files are generated or protected?
Where should new code go?
What evidence is required before a task is complete?
Which changes need extra review because they affect security, data, payments, or public APIs?

The best file is short enough to scan and specific enough to execute.

1. Start with a repository map

Name the important directories and what owns them. Avoid listing every folder. Focus on the paths that determine where an agent should inspect or edit.

app/     product routes and UI
db/      schema and database access
worker/  deployment entry point
tests/   focused regression coverage
public/  static assets only

Add a sentence about where business logic belongs and where it does not. This prevents an agent from placing a quick fix in the wrong layer.

2. Write commands that can actually run

Never say “run the tests” when the repository has several test modes. Provide exact commands and explain when each one applies.

npm install
npm run lint
npm test -- path/to/relevant.test.ts
npm run build

If a command requires credentials, external services, or a long-running environment, say so. Agents should not guess at missing access or silently skip validation.

3. Define boundaries and protected areas

Make risky surfaces explicit. Common examples include authentication, payment flows, migrations, deployment files, generated code, lockfiles, analytics contracts, and public APIs.

A useful rule is concrete:

Do not edit generated migrations by hand. Create a new migration and include a rollback note.

A weak rule is vague:

Be careful with the database.

Specific boundaries reduce accidental scope expansion and make review faster.

4. State the workflow

Describe the smallest reliable sequence for a task:

Inspect the relevant files and existing tests.
State material assumptions before editing.
Make the smallest complete change.
Add or update focused regression coverage.
Run the narrow checks first, then broader validation.
Report what changed, what passed, and what remains uncertain.

This workflow matters because coding agents often optimize for producing code quickly. Your repository instructions should optimize for producing verified results.

5. Make “done” testable

A definition of done should describe evidence, not confidence:

The requested behavior works on the primary path.
Relevant failure states are covered.
Type checks, focused tests, and the production build pass.
Unrelated behavior and existing user changes are preserved.
The final handoff names residual risk and checks that could not run.

If a validation step is impossible, require the agent to say why. An honest limitation is more useful than a false green check.

6. Put specific instructions close to the code

Large repositories may need more than one instruction file. Keep repository-wide rules at the root, then add narrower instructions inside high-risk or specialized areas such as payments, infrastructure, or mobile apps.

The closer file can refine commands and guardrails without repeating the entire root document. Avoid contradictions: more specific rules should clarify the general workflow, not replace its safety standards.

Common mistakes

Copying a generic template without checking the actual repository.
Listing commands that do not exist.
Writing philosophy instead of executable rules.
Omitting generated files and protected areas.
Requiring every possible test for every tiny change.
Forgetting to define what the final handoff must contain.
Letting task instructions conflict with repository constraints.

A practical AGENTS.md should reduce decisions the agent must invent while preserving the decisions that belong to the developer.

A compact starter structure

Use these sections as a first draft:

Repository map
Setup and commands
Editing rules
Protected areas
Testing and quality gates
Definition of done
Handoff requirements

Then replace every generic sentence with evidence from the repository itself.

Verify the method or skip the setup work

You can inspect the free AgentBrief starter and public release before buying anything.

If you want a larger reusable library, AgentBrief Pro includes 18 AGENTS.md templates, 12 task briefs, 8 recovery playbooks, and 5 quality gates. It is an editable Markdown kit with instant delivery for $25.

If you prefer a repository-specific result, the AgentBrief site links to a fixed-scope custom AGENTS.md service delivered in 24 hours.

The 4-part brief that keeps coding agents from drifting

AgentBrief Studio — Sat, 01 Aug 2026 06:14:39 +0000

Coding agents usually do not drift because they are incapable. They drift because the task leaves too much room for interpretation.

A request like “clean up authentication” sounds clear to a human who already knows the codebase. To an agent, it can mean anything from renaming one helper to replacing the entire authentication stack.

The fix is not a longer prompt. It is a brief with four explicit parts:

Outcome
Context
Guardrails
Definition of Done

Below is the exact structure I use.

1. State the outcome as an observable change

Describe what should be different for the user or system when the work is complete.

Weak:

Fix the login bug.

Better:

When a user submits an expired magic link, show the existing “Link expired” message and offer a button that requests a new link without leaving the page.

The better version gives the agent a destination. It does not prescribe the implementation, but it makes success testable.

2. Give only the context that changes the decision

Context is useful when it removes ambiguity. It becomes noise when it is a tour of the whole repository.

Useful context often includes:

The relevant entry point or route
The existing component or service that should be reused
A similar implementation elsewhere in the codebase
The command used to run the relevant tests
A known constraint, such as backwards compatibility

Example:

The page is implemented in app/auth/verify/page.tsx. Reuse requestMagicLink() from lib/auth/client.ts. The existing error-message styles live in components/auth/AuthNotice.tsx.

That is enough to start investigating without pretending we already know the final patch.

3. Add guardrails that define the change boundary

Guardrails prevent a small task from becoming an accidental rewrite.

A useful set might be:

Do not change the public API.
Do not add dependencies.
Keep the current visual design.
Do not edit generated files.
Limit changes to the authentication flow and its tests.
If a database migration appears necessary, stop and explain why before creating one.

Notice that the last guardrail gives the agent an escalation rule. “Stop and explain” is much safer than letting an uncertain assumption become a migration.

4. Make the Definition of Done evidence-based

“Works correctly” is not a Definition of Done. Ask for evidence that you can inspect.

For the magic-link example:

An expired link shows the existing error message.
Clicking “Request a new link” calls the existing client method once.
The success and failure states are both covered by tests.
The relevant test suite passes.
The final response lists changed files and the verification commands run.

This turns the end of the task into a small acceptance test.

Copyable task-brief template

# Outcome
[Describe the observable behavior that should exist when complete.]

# Context
- Entry point:
- Existing code to reuse:
- Similar implementation:
- Verification command:

# Guardrails
- Do not:
- Preserve:
- Scope limit:
- Stop and ask if:

# Definition of Done
- [ ] Observable behavior is implemented.
- [ ] Important success and failure paths are tested.
- [ ] Relevant checks pass.
- [ ] Final response includes changed files and verification evidence.

A complete bug-fix brief

# Outcome
When an expired magic link is submitted, show the existing “Link expired”
message and let the user request a replacement without leaving the page.

# Context
- Page: app/auth/verify/page.tsx
- Reuse: requestMagicLink() from lib/auth/client.ts
- Reuse styles: components/auth/AuthNotice.tsx
- Tests: npm test -- auth-verify

# Guardrails
- Do not add dependencies.
- Do not change the public auth API.
- Preserve the current layout and copy.
- Limit changes to this flow and its tests.
- If a server/API change seems necessary, stop and explain why first.

# Definition of Done
- [ ] Expired links show the existing message.
- [ ] The replacement-link action is available on the same page.
- [ ] Loading, success, and failure states are covered.
- [ ] npm test -- auth-verify passes.
- [ ] Final response lists files changed and checks run.

Add one quality gate before accepting the patch

A good brief controls the start of the work. A quality gate controls the end.

Before accepting the result, ask:

Did the patch solve the stated outcome?
Did it stay inside the guardrails?
Is there test or command output supporting the claim?
Did the agent disclose assumptions and unverified areas?
Is the diff smaller than a reasonable alternative?

That last question is especially useful. A correct result can still create unnecessary maintenance work.

Free resources and the kit I built

I published a free starter repository with brief templates and a small browser-based builder:

I also packaged the expanded version, AgentBrief Pro, with 43 reusable assets: 18 task briefs, 12 task recipes, 8 recovery playbooks, and 5 quality gates. It is a paid download ($29): view AgentBrief Pro on Payhip.

The important idea is free to use: make the outcome observable, provide decision-changing context, set boundaries, and demand evidence.