What agents should know before contributing
withastro/astro
The web framework for content-driven websites. ⭐️ Star to support our work!
Read by Bluet from 2 files written for agents and 300 merged pull requests on 2026-09-24. Not reviewed by the maintainers.
Rules its files tell agents (14)
- CONTRIBUTING.md
mustpnpm replaces "exports" with this at publish time, so _internal/* entries never ship.
"publishConfig.exports" — the npm view. pnpm replaces "exports" with this at publish time, so _internal/* entries never ship.
- AGENTS.md
mustWhen your change alters documented behavior, extend or correct the existing prose — never replace specific doc…
When your change alters documented behavior, extend or correct the existing prose — never replace specific docs with generic text.
- AGENTS.md
mustNever narrate change history ("now", "previously", "no longer") and never address the reviewer ("this correctl…
Never narrate change history ("now", "previously", "no longer") and never address the reviewer ("this correctly handles..."). State how the code works, not how it came to be or why the change is right.
- CONTRIBUTING.md
shouldNon-packages (examples/*) do not need changesets.
When making a pull request, be sure to add a changeset when something has changed with Astro. Non-packages (examples/*) do not need changesets.
- AGENTS.md
shouldException: @docs-tagged JSDoc in types/public/config.ts and core/errors/errors-data.ts is end-user documentati…
Exception: @docs-tagged JSDoc in types/public/config.ts and core/errors/errors-data.ts is end-user documentation generated to the website; these rules don't apply there.
- AGENTS.md
shouldDo not manually start detached servers with &.
Use astro dev --background to start and manage long-running dev servers in the background. Do not manually start detached servers with &.
- AGENTS.md
shouldDo not use other web servers (python -m http.server, etc.).
Use astro dev to start the local dev server with HMR. Do not use other web servers (python -m http.server, etc.).
- AGENTS.md
shouldDon't remove pre-existing dead code unless asked.
- AGENTS.md
shouldDeletion test: a comment must state something the reader cannot recover from the code. If names or types alrea…
Deletion test: a comment must state something the reader cannot recover from the code. If names or types already carry it, don't write it.
- AGENTS.md
shouldIf you notice unrelated dead code, mention it - don't delete it.
- AGENTS.md
shouldDon't refactor things that aren't broken.
- AGENTS.md
shouldDon't "improve" adjacent code, comments, or formatting.
- AGENTS.md
shouldIf multiple interpretations exist, present them - don't pick silently.
- AGENTS.md
shouldDon't assume.
Don't assume. Don't hide confusion. Surface tradeoffs.
Decisions its pull requests settled (16)
- #17612preserve CSS HMR across ClientRouter navigations
- #17611apply the dev CSS plugin to the fallback Astro environment
- #17618restore auto-import code actions for Astro components
- #17687run edge middleware when isr is enabled
- #17671Detect stale dev server lock files after PID reuse
- #17696Fix incremental build cache invalidation caused by Shiki mutating the `langAlias` config object
- #17743respect implicit and zero Accept-Language quality values in preferredLocale
- #17700Fix `preferredLocaleList` dropping object-form locale codes that differ in case
- #17769Fix vite.environments.ssr user config causing SSR entry to emit as index.mjs instead of entry.mjs
- #17774Add `.apng` to supported image formats and TypeScript declarations
- #17772Normalize request paths before route matching
- #17776Fix glob loader dropping content files with colons in their names
- #17942Return client errors for invalid image paths
- #17964Fix trailing-slash redirect truncating query strings that contain a second `?`
- #18007stop the head-metadata plugin invalidating its own virtual module
- #18036Tighten @astrojs/mdx peer dependency on astro and improve version mismatch error message