Setup that survives a real codebase

• Ball of mud growth. The agent does X wrong → you add a rule → repeat 100 times. Different contributors add conflicting opinions. Nobody ever does a style pass. The file becomes unmaintainable, and it actively confuses the agent.
• Stale docs poison context. File paths especially. If AGENTS.md says src/auth/handlers.ts and the file moves, the agent confidently looks in the wrong place. Domain concepts age slower than paths — prefer them when documenting.

Be ruthless. Matt Pocock's minimum is three things:

1. A one-sentence description of the project (this acts like a role prompt).
2. The package manager, if non-standard.
3. Build / typecheck commands, if non-standard.

# AGENTS.md

Companion site for the Navigators of Code talk. Astro + Tailwind + Vercel.

- `npm run dev` — dev server on :4321
- `npm run build` — production build

For deeper guidance see docs/ARCHITECTURE.md and docs/CONVENTIONS.md.

For a small project, the docs/ tree is overkill. Inline sections beat a maze of files. The judgement call is: does this rule apply to every task in the repo? If yes, inline. If domain-specific, move it out.

# AGENTS.md

Companion site for the Navigators of Code talk at rindus.
Astro 6 + React islands + Tailwind v4, deployed to Vercel.

## Build & run
- `npm run dev` — dev server on :4321
- `npm run build` — production build

## Architecture
Pages in `src/pages/`. Content in `src/content/{prompts,transcripts,prds}`
as markdown, Zod-typed in `src/content.config.ts`.

## Conventions
- React for islands only. Default to .astro.
- No comments unless the WHY is non-obvious.

Claude Code reads CLAUDE.md; other tools read AGENTS.md. Make CLAUDE.md a one-line import. One source of truth, every tool stays in sync.

@AGENTS.md

Every slash command on this site comes from mattpocock/skills. One install, then /grill-me, /to-prd, /to-issues, /tdd are available globally.

npx skills@latest add mattpocock/skills

For the full theory behind a sharp AGENTS.md, read Matt Pocock's A Complete Guide To AGENTS.md — most of this page distills it.