Project context (AGENTS.md)

AGENTS.md is a plain Markdown file you put at the root of your project (and optionally in subdirectories) that gives Magic Coder persistent context about your codebase: the build commands, the test command, the lint command, the architecture, the conventions, the things that would otherwise get re-discovered every session.

It’s the closest thing to a “memory” for the agent in your repo. If your team uses Magic Coder regularly, an AGENTS.md is the highest-value piece of documentation you can write for it.

Where files live

Location	When it’s loaded
`<workspace>/AGENTS.md`	At session start, automatically, for every trusted workspace root.
`<workspace>/<subdir>/AGENTS.md`	On demand — when the agent reads a file, lists, or edits anything in `<subdir>`, the nearest `AGENTS.md` files above it are picked up.

This means a monorepo can have a top-level AGENTS.md plus per-package files: apps/web/AGENTS.md, services/api/AGENTS.md, etc. Magic Coder will load the right ones based on what it’s working on.

The discovery rules:

Only files inside trusted workspace roots are loaded. Nested AGENTS.md files outside the configured roots are ignored.
Symlinks that point outside the workspace are not followed.
Updates to AGENTS.md take effect at the start of the next session — they’re not hot-reloaded inside a running session.

What to put in an AGENTS.md

Aim for a punchy, factual document the agent can act on. The closer it reads to a runbook, the better.

A solid template:

Brief description of this project: what it is, who uses it, what the goals are.

## Commands
- `make build` — build everything
- `make test` — run the test suite
- `make lint` — lint
- `make dev` — run the dev server
- `make migrate` — apply database migrations

## Architecture
```text
src/
├── api/          HTTP handlers and routing
├── domain/       core business logic, no I/O
├── infra/        database, external clients
└── tests/        integration tests

Conventions

All HTTP responses go through api/response.go. Don’t write w.Write directly.
Database access lives in infra/db/. Never import database packages from domain/.
Tests use testify; keep table-driven tests grouped by behavior, not by function.
Errors propagate up; only the top-level handler logs.

Boundaries

NEVER:

Edit protos/ directly. Re-run make protos from a .proto change.
Commit .env or any file under secrets/.

ASK FIRST:

Adding a new dependency to go.mod.
Changing the database schema.

ALWAYS:

Run make lint before declaring a task done.
Update CHANGELOG.md for user-facing changes.

That's it. No magic format — Markdown, headings, bullets, occasional code blocks.

## What works well in practice

- **Concrete commands.** `make test` is more useful than "run the tests."
- **Architecture in 5 lines.** A directory tree with one-line annotations beats a 50-line essay.
- **Boundaries.** "Never edit X, ask before doing Y, always do Z" is high-signal for the agent.
- **Failure modes.** "If the agent tries to write SQL by hand, redirect it to the query builder in `infra/db/queries`" — calling out specific anti-patterns saves time.
- **Linked files.** "See `docs/architecture.md` for details" — Magic Coder will read it if the task warrants it.

## What doesn't work

- **Stale info.** An `AGENTS.md` that says `make test` when the command is now `npm test` will mislead the agent. Update it as the project changes.
- **Aspirational rules.** "We always write integration tests" is fiction if the codebase has none. The agent will trust the file; if it's wrong, it'll waste time.
- **Generic prose.** "We value clean code and good engineering practices" tells the agent nothing actionable.

## Generating an AGENTS.md

Magic Coder can generate an `AGENTS.md` for a repo from scratch. Inside a session, ask:

> "Generate a high-quality AGENTS.md for this repository. Inspect the build files, test setup, and source layout. Keep it punchy and factual."

The agent will read the repo and produce a draft. Edit before you commit — you'll know things about the project the agent doesn't.

## Per-package files

A nested `AGENTS.md` complements (doesn't replace) the root one. Use the package-level file for things that only apply to that package:

- The package's specific build/test commands
- The package's local conventions
- Pointers to related packages

When Magic Coder is working in a subdirectory, both the root and the nearest nested `AGENTS.md` are in scope.

## What about `MAGIC.md`?

`AGENTS.md` is the file Magic Coder reads. There's no separate `MAGIC.md` today — using `AGENTS.md` keeps your project compatible with other coding agents that follow the same emerging convention.