DEV Community

Paulo Victor Leite Lima Gomes
Paulo Victor Leite Lima Gomes

Posted on

instructions as code: AGENTS.md, CLAUDE.md, and copilot-instructions.md

#agents #ai #productivity #softwareengineering

This is part 2 of a 5-post series on professional agentic coding for senior engineers.

Agent instruction files are becoming part of the engineering system.

Codex has AGENTS.md.

Claude Code has CLAUDE.md.

GitHub Copilot supports repository instructions such as .github/copilot-instructions.md, path-specific instruction files, and cloud-agent instruction surfaces.

This is good.

It is also a new place to create technical debt.

instructions should be short and operational

The agent does not need a philosophy essay.

It needs the facts that change what it should do in this repository.

Good instruction files include:

  • install commands
  • focused test commands
  • typecheck and lint commands
  • repo layout
  • naming conventions
  • important boundaries
  • dependency rules
  • how to verify work
  • project-specific gotchas
  • PR expectations

Bad instruction files include:

  • stale onboarding docs
  • generic rules like "write clean code"
  • huge architecture histories
  • every preference someone has ever had
  • commands nobody has run in six months

The point is not to make the agent read more.

The point is to make it read the right things.

a useful AGENTS.md 

# AGENTS.md

## Commands

- Install: pnpm install
- Test API: pnpm --filter @app/api test
- Test web: pnpm --filter @app/web test
- Typecheck: pnpm typecheck

## Repo Layout

- apps/api: backend HTTP API
- apps/web: React frontend
- packages/db: migrations and query helpers
- packages/shared: shared types and utilities

## Rules

- Prefer existing patterns over new abstractions.
- Do not add production dependencies without explicit approval.
- For bug fixes, add regression tests when practical.
- Do not edit generated files directly.

## Done Means

- Relevant tests pass.
- Typecheck passes for changed packages.
- Final response lists commands run and checks skipped.
Enter fullscreen mode Exit fullscreen mode

That is not glamorous.

It is useful.

Codex loads AGENTS.md from global, project, and nested scopes, with closer files applying more specifically. That means you can keep root instructions broad and put package-specific rules closer to the code.

Root:

Prefer existing repo patterns. Run relevant tests. Do not add dependencies without approval.
Enter fullscreen mode Exit fullscreen mode

apps/api/AGENTS.md:

Use Fastify plugin patterns already in this package.
Run pnpm --filter @app/api test for API changes.
Database migrations must be reversible.
Enter fullscreen mode Exit fullscreen mode

This is better than one giant instruction file trying to govern everything.

a useful CLAUDE.md

Claude Code's memory guidance has the same shape. CLAUDE.md should contain recurring project knowledge, commands, conventions, and workflow notes.

Good:

## Common Commands

- pnpm typecheck
- pnpm --filter @app/api test
- pnpm --filter @app/web test

## Project Notes

- Auth sessions live in apps/api/src/auth.
- Payment ledger code is append-only; do not update historical rows.
- Prefer repository query helpers over raw SQL in application services.

## Verification

- Bug fixes should include regression tests when practical.
- UI changes need a screenshot or Playwright check.
Enter fullscreen mode Exit fullscreen mode

Bad:

Be smart.
Write clean code.
Do not make mistakes.
Use best practices.
Enter fullscreen mode Exit fullscreen mode

That feels nice and changes almost nothing.

Copilot instructions need the same discipline

GitHub Copilot's cloud agent works from issues and repository context. That makes durable instructions especially important, because the task often starts in GitHub rather than your local terminal.

Use .github/copilot-instructions.md for repository-wide guidance.

Use path-specific instructions when the rules differ.

Use custom agents when a role needs a narrow prompt and constrained tools.

The mistake is to assume "Copilot knows our repo." It knows what it can read and what you tell it to prioritize. If your issue is vague and your instructions are stale, you get a vague PR with stale assumptions.

what belongs in the prompt instead

Do not put task-specific details in durable instructions.

Bad AGENTS.md:

For the current auth bug, inspect ticket AUTH-123 and fix refresh tokens.
Enter fullscreen mode Exit fullscreen mode

That belongs in the task prompt.

Durable instructions should be true next week.

One-off prompts should describe today's outcome.

This separation matters because instruction files survive. A stale one-off note inside a durable file becomes a hidden source of bad behavior.

bad practice: instruction dumping

Instruction dumping is when the team responds to one agent mistake by adding five more rules.

The file grows.

The model follows less of it.

The commands drift.

Nobody reviews it.

Then people say "agents do not follow instructions."

Sometimes true.

But often the instructions are unmaintainable.

Treat these files like code:

  • review changes
  • delete stale rules
  • keep commands executable
  • prefer specific rules over generic advice
  • keep path-specific context near the path
  • add rules only when they prevent repeated mistakes

checklist

A good instruction file answers:

  • How do I install and test this repo?
  • Where are the important packages?
  • What conventions are non-obvious?
  • What should I never do?
  • What does done mean here?
  • Which checks should I run for common changes?

If it does not affect the next action, cut it.

sources

To test my projects, I use Railway. If you want $20 USD to get started, use this link.

Top comments (0)