AGENTS.md

1# Think Before Coding
2 
3**Don't assume. Don't hide confusion. Surface tradeoffs.**
4 
5Before implementing:
6 
7- State your assumptions explicitly. If uncertain, ask.
8- If multiple interpretations exist, present them - don't pick silently.
9- If a simpler approach exists, say so. Push back when warranted.
10- If something is unclear, stop. Name what's confusing. Ask.
11 
12# Simplicity First
13 
14**Minimum code that solves the problem. Nothing speculative.**
15 
16- No features beyond what was asked.
17- No abstractions for single-use code.
18- No "flexibility" or "configurability" that wasn't requested.
19- No error handling for impossible scenarios.
20- If you write 200 lines and it could be 50, rewrite it.
21 
22Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify.
23 
24# Surgical Changes
25 
26**Touch only what you must. Clean up only your own mess.**
27 
28When editing existing code:
29 
30- Don't "improve" adjacent code, comments, or formatting.
31- Don't refactor things that aren't broken.
32- Match existing style, even if you'd do it differently.
33- If you notice unrelated dead code, mention it - don't delete it.
34 
35When your changes create orphans:
36 
37- Remove imports/variables/functions that YOUR changes made unused.
38- Don't remove pre-existing dead code unless asked.
39 
40The test: Every changed line should trace directly to the user's request.
41 
42# Goal-Driven Execution
43 
44**Define success criteria. Loop until verified.**
45 
46Transform tasks into verifiable goals:
47 
48- "Add validation" → "Write tests for invalid inputs, then make them pass"
49- "Fix the bug" → "Write a test that reproduces it, then make it pass"
50- "Refactor X" → "Ensure tests pass before and after"
51 
52For multi-step tasks, state a brief plan:
53 
54```
551. [Step] → verify: [check]
562. [Step] → verify: [check]
573. [Step] → verify: [check]
58```
59 
60Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification.
61 
62# Style Guide
63 
64- Not defined here. For now, follow the same conventions and patterns that you detect in the surrounding code.
65- Keep formatting consistent. Our rules are defined in our [biome.jsonc](./biome.jsonc) file, enforced by Biome.
66- Run `pnpm format` to auto-format the entire repo.
67- Run `pnpm lint:ai` to lint the entire repo.
68 
69# Writing Comments
70 
71These rules apply to **every** comment you write, including ones added incidentally while fixing a bug. Full guidance with examples: [`.agents/skills/writing-comments/SKILL.md`](./.agents/skills/writing-comments/SKILL.md).
72 
73- Write for a contributor reading the code at HEAD, months later, with no access to this conversation, the PR, or the diff.
74- 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.
75- 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.
76- `/** */` docs state the contract (behavior, params, returns, throws); `//` comments carry rationale only. Anchor a workaround to the GitHub issue or PR that motivates it.
77- When your change alters documented behavior, extend or correct the existing prose — never replace specific docs with generic text.
78- 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.
79 
80# Environment Guide
81 
82- Use `node -e` for scripting tasks, not `python` or `python3`.
83 
84# Monorepo Structure
85 
86This directory is a Git monorepo containing a `pnpm` workspace:
87 
88- The codebase is primarily TypeScript.
89- All packages live in `packages/`.
90- Integration packages live in `packages/integrations/`.
91- The core Astro package is `packages/astro`.
92 
93In error stack traces, built files from workspace packages in `node_modules/` map to TypeScript source in `packages/`:
94 
95- `node_modules/astro/dist/...` → `packages/astro/src/...`
96- `node_modules/@astrojs/react/...` → `packages/integrations/react/src/...`
97 
98Edits to source files take effect after rebuilding the package via `pnpm build`.
99 
100Use `pnpm -C <dir> <command>` for project-local script commands when working in packages/examples/triage directories (Example: `pnpm -C packages/astro build`, `pnpm -C examples/blog dev`). Only omit `-C` flag when intentionally working in the monorepo root (Example: `pnpm format`, `pnpm lint:ai`, `pnpm test:types`).
101 
102# Running Tests
103 
104- Run `pnpm test` in workspace root or package directory to run full test suite (can be slow!)
105- Integration tests live in special `packages/integrations` folders.
106- Example: `pnpm -C <package-directory> exec astro-scripts test` - Run a single package test suite
107- Example: `pnpm -C <package-directory> exec astro-scripts test "test/actions.test.js"` - Run a single test file
108- Example: `pnpm -C <package-directory> exec astro-scripts test "test/**/*.test.js" --match "CSS"` - Run specific tests matching a string or regex patterns
109- Example: `pnpm -C <package-directory> exec astro-scripts test "test/{actions,css,middleware}.test.js"` - Run multiple test files
110- Key flags:
111  - `--match` / `-m`: Filter tests by name pattern (regex)
112  - `--only` / `-o`: Run only tests marked with `.only`
113  - `--parallel` / `-p`: Run tests in parallel (default is sequential)
114  - `--timeout` / `-t`: Set timeout in milliseconds
115  - `--watch` / `-w`: Watch mode
116 
117# Astro Quick Reference
118 
119- Use `astro dev` to start the local dev server with HMR. Do not use other web servers (`python -m http.server`, etc.).
120- Use `astro build` to create a production build in `dist/`, by default.
121- Use `astro preview` to serve the production build locally. Do not use other web servers (`python -m http.server`, etc.).
122- Use `astro check` to run type checking and diagnostics.
123- Use `astro sync` to generate and update TypeScript types.
124- Use `astro add` to install and configure an official integration.
125- Fetch **Full docs** at https://docs.astro.build/ (primary source for the latest reference).
126 
127# Background Dev Servers
128 
129Use `astro dev --background` to start and manage long-running dev servers in the background. Do not manually start detached servers with `&`.
130 
131Workflow:
132 
1331. `pnpm -C examples/minimal dev --background` - Start the dev server in the background
1342. `pnpm -C examples/minimal dev logs` - View logs from the dev server. Useful for debugging server logs.
1353. `pnpm -C examples/minimal dev status` - Check whether a dev server is running
1364. `pnpm -C examples/minimal dev stop` - Stop the dev server when your work is complete
137 
138Use `pnpm -C examples/minimal dev logs --follow` to stream logs. If a stale dev server is blocking startup, stop it first or use `pnpm -C examples/minimal dev --background --force` to replace it.
139 
140# `agent-browser`
141 
142Use `agent-browser` for web automation or when UI interaction, long-running browsers, or HMR testing is required. Do not use `curl` to test HMR issues.
143 
144Use `agent-browser --help` to see all available commands.
145 
146Workflow:
147 
1481. `agent-browser open <url>` - Navigate to page
1492. `agent-browser snapshot -i` - Get interactive elements with refs (@e1, @e2)
1503. `agent-browser click @e1` / `fill @e2 "text"` - Interact using refs
1514. Re-snapshot after all page changes, navigations, interactions.
152 
153Note: `agent-browser` should be installed globally, and is not a dependency of this monorepo. If `agent-browser` isn't available on this machine, ask the user to run `npm install -g agent-browser && agent-browser install`. If you are running in headless mode with no human operator and need this tool to complete your job, it is best to fail the job vs. trying to work around not having the tool.
154 
155# Deep Dives
156 
157Detailed reference documents on specific subsystems. Read the relevant section before diving into a bug or feature in that area.
158 
159## Unit Testing
160 
161When writing unit tests, read [`reference/unit-testing.md`](./reference/unit-testing.md) for conventions, file placement, and the shared test utilities and mocks available in the repo. Do not duplicate existing helpers.
162 
163## Vite Dep Optimizer (`optimizeDeps`)
164 
165When a bug works in `astro build` but fails in `astro dev` with errors like `require is not defined`, the root cause is almost always Vite's dep optimizer failing to pre-bundle a CJS dependency. `astro build` uses Rollup and handles CJS→ESM reliably; `astro dev` relies on esbuild's optimizer scan, which is intentionally shallow and will miss deps that are only reachable through non-JS files (like `.astro` components in `node_modules`). The key files are `packages/astro/src/vite-plugin-environment/index.ts` (sets `optimizeDeps.entries`) and `packages/astro/src/core/create-vite.ts` (wires up `vitefu`/`crawlFrameworkPkgs`). For a full deep-dive including a debugging playbook and potential fixes, see [`reference/optimize-deps.md`](./reference/optimize-deps.md).
166