Context File Best Practices

+15 Mana ✨
AGENTS.md authoring guidance(DOCUMENTATION)

Introduction

A good context file makes the agent better; a bad one makes it slower and more confused. The rules for writing a good AGENTS.md are concrete and worth internalizing once. They apply equally to .hermes.md, CLAUDE.md, and any other auto-discovered file.

Key Concepts

  • Conciseness: Read on every turn the file is loaded for. Tight wording pays back constantly.
  • Structure: Use ## headers so the model can scan, not just read.
  • Concrete examples: Show, do not only tell.
  • Explicit prohibitions: "Never do X" is more useful than "Be careful with X".
  • Freshness: Stale context degrades behavior; outdated rules confuse the agent.

Real World Context

A team's AGENTS.md has grown to 18,000 characters over a year. Half the entries describe an architecture that has since been refactored away. The agent dutifully follows the stale rules and the team spends weeks correcting it. A two-hour pruning session restores quality. Maintenance is the unglamorous half of context engineering.

Deep Dive

A template that holds up well in practice:

markdown
# Project Context
One-paragraph description of what this codebase is.

## Architecture
- Top-level structure (apps, services, key boundaries).
- Primary technology choices and versions.

## Conventions
- Code style rules that matter (naming, formatting, imports).
- Testing conventions: where tests live, how to run them.
- Commit / PR conventions.

## Important Notes
- Explicit prohibitions: "never modify migrations directly".
- Gotchas the agent will not infer from the code ("docker exposes postgres on 5435, not 5432").
- Trust boundaries: which directories should never be read or edited automatically.

## Commands
- The handful of commands the agent should know to run: dev server, tests, build, format.

Five design choices baked in:

  1. Headers are signposts: The model can use them to locate relevant sections quickly. A wall of unstructured prose forces it to re-read on every turn.
  2. Architecture before conventions: The agent reasons more carefully about code style if it first understands the structure.
  3. Prohibitions are louder than preferences: "Never modify migrations directly" is a hard line. "Try not to" gets ignored.
  4. Commands belong in the file: Hard-coding the test command in AGENTS.md lets the agent run it without trial and error.
  5. Trust boundaries are explicit: For a security-sensitive directory, say so in the file rather than relying on the agent's defaults.

Finally, treat the file like code. Date the major updates. Remove rules that no longer apply. If the rate of corrections from you to the agent stops dropping, the context file probably needs an audit.

Common Pitfalls

  1. Letting it bloat past 20K characters: Hermes truncates oversized files. The middle 10% of your nuance will vanish silently.
  2. Mixing project context with personal preferences: "I prefer terse responses" is USER.md content, not AGENTS.md.

Best Practices

  1. Audit quarterly: Stale rules are a tax on every session that loads the file.
  2. Prefer prohibitions over preferences for the things that matter: "Never" beats "prefer".

Summary

  • Good context files are concise, structured, concrete, and explicit about prohibitions.
  • Stay well under the 20K-character cap so the agent gets the whole file every turn.
  • Mixing identity content into project context dilutes both.
  • Treat context files as code: maintain them, prune them, and date your updates.

Code Examples

markdown
# Project Context
A Next.js 16 web app and a NestJS backend, sharing Zod schemas from libs/shared.

## Architecture
- apps/web: Next.js 16, App Router, Tailwind 4.
- apps/backend: NestJS 11, Prisma, PostgreSQL.
- libs/shared: Zod schemas, three layers (base, internal, public).

## Conventions
- Internal types never leave the backend; expose Public DTOs only.
- Run `pnpm nx build shared` after editing libs/shared.
- Tests live next to source under __tests__/ directories.

## Important Notes
- Never modify Prisma migration files directly; use `pnpm prisma migrate dev`.
- Local postgres listens on 5435 via docker-compose, not 5432.
- Never commit anything under .env (real credentials).

## Commands
- Dev: `pnpm dev:all`
- Tests: `pnpm nx test backend|web|shared`
- Typecheck: `pnpm nx typecheck backend|web|shared`
✓ Completed