AGENTS.md · AstroAGENTS.md and CLAUDE.md examples for Astro
Of 94 actively developed open-source products built with Astro, 59 (63%) keep instruction files for coding agents: AGENTS.md in 47, CLAUDE.md in 34. The typical file is 1,073 words, and most cover commands to build, run and test (87%) and testing (80%).
Real files to read
From the best-known open-source Astro products whose file is a real one (not a pointer to another), 200 to 4,000 words, covering at least three of the usual topics and naming Astro. Each opens on GitHub.
| Project | File | Stars | Words | Covers |
|---|---|---|---|---|
| kriasoft/react-starter-kit | AGENTS.md | 23,687 | 845 | CommandsTestingDoc pointersStructureCode style |
| emdash-cms/emdash | AGENTS.md | 13,579 | 3,990 | CommandsTestingDoc pointersStructureCode style |
| cocoindex-io/cocoindex | AGENTS.md | 11,672 | 2,737 | CommandsTestingDoc pointersStructureCode style |
| dmno-dev/varlock | AGENTS.md | 4,693 | 1,111 | CommandsTestingStructureCode styleGit |
| zerx-lab/FluxDown | AGENTS.md | 4,317 | 2,232 | CommandsTestingDoc pointersGit |
| haydenbleasel/blume | AGENTS.md | 1,774 | 1,375 | CommandsTestingStructureCode styleGit |
| golemcloud/golem | AGENTS.md | 1,508 | 2,671 | CommandsTestingDoc pointersStructureCode styleGit |
| inkline/inkline | AGENTS.md | 1,469 | 858 | CommandsTestingDoc pointersCode styleGit |
| mattogodoy/nametag | CLAUDE.md | 1,089 | 3,576 | CommandsTestingDoc pointersStructureCode styleGit |
| di-sukharev/vibe | AGENTS.md | 747 | 1,492 | CommandsTestingDoc pointersStructureGit |
What Astro projects put in them
Share of the 54 files that cover each topic, against all 641 files we read.
How they talk to the agent: 93% say “never” or “do not” somewhere (all files: 80%), 19% shout a rule in capitals like IMPORTANT or MUST (24%), and 19% tell it to ask before some changes (20%).
The tools they name
Package managersbun (15 files), pnpm (14 files), npm (10 files)
Tests and lintersVitest (14), Playwright (10), ESLint (8), pytest (3), Prettier (3), Jest (2)
Named more than in files generallyGitHub (28), Vite (17), PostgreSQL (14), Astro (ASO) (12), SQLite (12), Rust (11), Bun (10), GitHub Actions (10)
What they tell the agent
Instructions that recur across files, in our words; open one for the Astro projects whose file says it.
About Astro
Astro builds the docs or marketing website, kept in its own subdirectory apart from the main app.7 files
About Vite
Vite is the frontend bundler and dev server, typically behind a React or Vue single-page app.3 files
Run the Vite dev server for hot-reload UI work.2 files
Where the project uses Vite+, run everything through the vp CLI instead of calling pnpm, npm, or vite directly.4 files
Environment variables exposed to client code use the VITE_ prefix and are baked in at build time.2 files
About PostgreSQL
Named as the project's main relational database, often alongside Redis.2 files
Pair PostgreSQL with Drizzle as the ORM and schema layer.1 files
Keep code portable across PostgreSQL and the other supported engines such as SQLite or MySQL.3 files
Run database tests against a real PostgreSQL instance rather than mocks or SQLite stand-ins.1 files
About SQLite
Serves as the default or embedded local database, often with PostgreSQL as an optional alternative.2 files
Reach SQLite through an ORM or query builder such as Drizzle, Kysely or SeaORM, not scattered raw SQL.1 files
Tests use in-memory or real SQLite instead of external database services.1 files
Change the SQLite schema through versioned migration files rather than ad hoc edits.2 files
About Rust
Rust provides the native backend or core, often a Tauri desktop shell or crates beside a TypeScript frontend.2 files
Rust crates live in a Cargo workspace under crates/, separate from app code.1 files
Format and lint Rust with cargo fmt and clippy before opening a PR.2 files
Run Rust tests with cargo test, workspace-wide or via nextest.2 files
About Bun
Use Bun for installs and scripts (bun install, bun run, bunx); don't use npm, pnpm, or yarn.3 files
Tests run on Bun's built-in runner (bun:test), with caveats about module mocks, timeouts, and per-package runs.1 files
Repo is a Bun workspaces monorepo, often orchestrated with Turborepo.2 files
Use the pinned Bun version from the repo.1 files
About GitHub Actions
Releases, publishing and deploys run through GitHub Actions workflows; do not publish or deploy manually.1 files
Pin third-party actions to a full commit SHA with a version comment, never a floating tag.1 files
A starting AGENTS.md for Astro
The sections these files cover most, the package manager and checks Astro projects name most, and the stack Astro makers' products chose most often. Fill in the <placeholders>.
# AGENTS.md <What this product does and who it is for, in a sentence or two.> ## Stack - Frontend Framework: Astro - Hosting: Vercel - Transactional Email: Resend - Web Analytics: Cloudflare Web Analytics - Payments: Stripe - Database: Supabase - LLM API: OpenAI API - Product Analytics: PostHog ## Commands - Install: `bun install` - Run locally: `<command>` - Test: `bunx vitest run` - End-to-end tests: `bunx playwright test` - Lint: `bunx eslint .` ## Testing Run `bunx vitest run` and `bunx playwright test` before calling a change done, and add a test with each fix or feature. ## Project structure - `<folder>/`: <what lives there> - More in <docs/…> ## Conventions - <Naming, patterns and style the code does not show> - Commits and pull requests: <your rules> ## Boundaries - Ask before: <changes you want to approve first> - Never: <files or actions that are off-limits> <!-- Started from https://howmakersbuild.com/agents-md/astro — point CLAUDE.md here with a line: @AGENTS.md -->
- bun: named in 15 of 54 instruction files from open-source projects built with Astro.
- Vitest: named in 14 of 54 instruction files from open-source projects built with Astro.
- Playwright: named in 10 of 54 instruction files from open-source projects built with Astro.
- ESLint: named in 8 of 54 instruction files from open-source projects built with Astro.
Questions
What should an AGENTS.md for a Astro project include?
In 54 files from open-source Astro products: commands to build, run and test (87%), testing (80%), pointers to other docs (72%), git, commits and pull requests (63%), project structure (61%), code style (59%). The package manager they name most is bun (15 files).
AGENTS.md or CLAUDE.md?
Among these Astro products, 47 keep an AGENTS.md and 34 a CLAUDE.md. Across every product we checked, 320 keep both, and in 170 of those the CLAUDE.md only points to the AGENTS.md (a symlink or a line like @AGENTS.md), so there's one file to maintain. Codex, Cursor, Copilot and others read AGENTS.md; Claude Code reads CLAUDE.md.
How long is a typical Astro AGENTS.md?
The median is 1,073 words in these 54 files; across all 641 files we read, half are between 425 and 1,665 words.
How this is counted: the GitHub repos of open-source products built with Astro, pushed to in the 180 days before 2026-10-12. We read each repo's AGENTS.md, CLAUDE.md and other agent files; what's published here is counts and links, not their text. All files, by the numbers.