Astro + Tailwind rules for AI coding agents
Full stack: Astro + Tailwind CSS v4
Ready-to-commit rules for Astro + Tailwind CSS v4 in every major format: AGENTS.md (Codex, Cursor, Copilot), CLAUDE.md (Claude Code), Cursor .mdc project rules, legacy .cursorrules, Copilot instructions, Windsurf rules and GEMINI.md. Content sites, blogs and landing pages with Astro and Tailwind.
Last reviewed 2026-10-21 · Customise in the generator · Raw: AGENTS.md, CLAUDE.md
The mistake agents make most on this stack
Agents hydrate everything with `client:load` and turn a fast static site into a heavy SPA.
Generated files
AGENTS.md
# AGENTS.md - this project
Instructions for AI coding agents working in this repository.
## Project
A Astro + Tailwind CSS v4 project.
Stack: Astro, Tailwind CSS v4.
## Commands
- Dev server: `npm run dev`
- Build: `npm run build`
- Type and template check: `npx astro check`
## Project structure
- Routes in `src/pages/`, layouts in `src/layouts/`, components in `src/components/`.
- Markdown/MDX content lives in content collections with a schema in `src/content.config.ts`.
## How to work in this repo
- Read the relevant files before editing. Follow the patterns already in the codebase over these generic rules.
- Make the smallest change that solves the task. Do not refactor or reformat unrelated code.
- Before saying a task is done, run the type-check, lint and tests listed under Commands and fix what you broke.
- If requirements are ambiguous, ask one clear question instead of guessing.
- Never commit secrets, API keys or `.env` files. Use env vars and keep `.env.example` up to date.
- Do not add a new dependency when the standard library or an existing dependency already covers it.
- Ask before adding, removing or upgrading any dependency.
- Ask before changing database schemas, auth, payments or CI configuration.
- Never delete files, drop data or run destructive commands (`rm -rf`, `git push --force`, `DROP TABLE`) without explicit approval.
- Keep each change under ~200 changed lines where possible; split larger work into steps.
## Astro
- `.astro` components ship zero JavaScript by default. Keep it that way unless interactivity is needed.
- Add interactivity with framework islands and the lightest directive that works: prefer `client:visible` or `client:idle` over `client:load`.
- Define a Zod schema for every content collection and query it with `getCollection()`.
- Use `astro:assets` `<Image />` for local images.
- Generate dynamic routes with `getStaticPaths()` in static mode.
- Set a unique `<title>` and meta description per page through the shared layout.
## Tailwind CSS v4
- Tailwind v4 is configured in CSS: `@import "tailwindcss";` plus `@theme { ... }` for design tokens. Do not create a `tailwind.config.js` unless the project already has one.
- Use theme tokens (colors, spacing) instead of arbitrary values like `w-[37px]`.
- Build responsive layouts mobile-first with `sm:`, `md:`, `lg:` prefixes.
- Extract repeated class lists into components, not `@apply` chains.
- Support dark mode with the `dark:` variant when the project uses it.
## Reference docs
- [Astro docs](https://docs.astro.build)
- [Tailwind CSS docs](https://tailwindcss.com/docs)
CLAUDE.md
# CLAUDE.md - this project
Project instructions for Claude Code.
## Project
A Astro + Tailwind CSS v4 project.
Stack: Astro, Tailwind CSS v4.
## Commands
- Dev server: `npm run dev`
- Build: `npm run build`
- Type and template check: `npx astro check`
## Project structure
- Routes in `src/pages/`, layouts in `src/layouts/`, components in `src/components/`.
- Markdown/MDX content lives in content collections with a schema in `src/content.config.ts`.
## How to work in this repo
- Read the relevant files before editing. Follow the patterns already in the codebase over these generic rules.
- Make the smallest change that solves the task. Do not refactor or reformat unrelated code.
- Before saying a task is done, run the type-check, lint and tests listed under Commands and fix what you broke.
- If requirements are ambiguous, ask one clear question instead of guessing.
- Never commit secrets, API keys or `.env` files. Use env vars and keep `.env.example` up to date.
- Do not add a new dependency when the standard library or an existing dependency already covers it.
- Ask before adding, removing or upgrading any dependency.
- Ask before changing database schemas, auth, payments or CI configuration.
- Never delete files, drop data or run destructive commands (`rm -rf`, `git push --force`, `DROP TABLE`) without explicit approval.
- Keep each change under ~200 changed lines where possible; split larger work into steps.
## Astro
- `.astro` components ship zero JavaScript by default. Keep it that way unless interactivity is needed.
- Add interactivity with framework islands and the lightest directive that works: prefer `client:visible` or `client:idle` over `client:load`.
- Define a Zod schema for every content collection and query it with `getCollection()`.
- Use `astro:assets` `<Image />` for local images.
- Generate dynamic routes with `getStaticPaths()` in static mode.
- Set a unique `<title>` and meta description per page through the shared layout.
## Tailwind CSS v4
- Tailwind v4 is configured in CSS: `@import "tailwindcss";` plus `@theme { ... }` for design tokens. Do not create a `tailwind.config.js` unless the project already has one.
- Use theme tokens (colors, spacing) instead of arbitrary values like `w-[37px]`.
- Build responsive layouts mobile-first with `sm:`, `md:`, `lg:` prefixes.
- Extract repeated class lists into components, not `@apply` chains.
- Support dark mode with the `dark:` variant when the project uses it.
## Reference docs
- [Astro docs](https://docs.astro.build)
- [Tailwind CSS docs](https://tailwindcss.com/docs)
.cursor/rules/project.mdc
---
description: "Core rules for this project"
alwaysApply: true
---
# this project
A Astro + Tailwind CSS v4 project.
Stack: Astro, Tailwind CSS v4.
## Commands
- Dev server: `npm run dev`
- Build: `npm run build`
- Type and template check: `npx astro check`
## How to work in this repo
- Read the relevant files before editing. Follow the patterns already in the codebase over these generic rules.
- Make the smallest change that solves the task. Do not refactor or reformat unrelated code.
- Before saying a task is done, run the type-check, lint and tests listed under Commands and fix what you broke.
- If requirements are ambiguous, ask one clear question instead of guessing.
- Never commit secrets, API keys or `.env` files. Use env vars and keep `.env.example` up to date.
- Do not add a new dependency when the standard library or an existing dependency already covers it.
- Ask before adding, removing or upgrading any dependency.
- Ask before changing database schemas, auth, payments or CI configuration.
- Never delete files, drop data or run destructive commands (`rm -rf`, `git push --force`, `DROP TABLE`) without explicit approval.
- Keep each change under ~200 changed lines where possible; split larger work into steps.
.cursor/rules/astro.mdc
---
description: "Astro conventions: Content-first static or hybrid sites with Astro islands."
globs: src/**/*.astro, src/**/*.ts, src/content/**
alwaysApply: false
---
# Astro
- `.astro` components ship zero JavaScript by default. Keep it that way unless interactivity is needed.
- Add interactivity with framework islands and the lightest directive that works: prefer `client:visible` or `client:idle` over `client:load`.
- Define a Zod schema for every content collection and query it with `getCollection()`.
- Use `astro:assets` `<Image />` for local images.
- Generate dynamic routes with `getStaticPaths()` in static mode.
- Set a unique `<title>` and meta description per page through the shared layout.
Docs: https://docs.astro.build
.cursor/rules/tailwind.mdc
---
description: "Tailwind CSS v4 conventions: Utility-first styling with Tailwind CSS v4."
globs: **/*.css, **/*.tsx, **/*.vue, **/*.svelte, **/*.astro, **/*.html, **/*.blade.php, **/*.erb
alwaysApply: false
---
# Tailwind CSS v4
- Tailwind v4 is configured in CSS: `@import "tailwindcss";` plus `@theme { ... }` for design tokens. Do not create a `tailwind.config.js` unless the project already has one.
- Use theme tokens (colors, spacing) instead of arbitrary values like `w-[37px]`.
- Build responsive layouts mobile-first with `sm:`, `md:`, `lg:` prefixes.
- Extract repeated class lists into components, not `@apply` chains.
- Support dark mode with the `dark:` variant when the project uses it.
Docs: https://tailwindcss.com/docs
.cursorrules
# Cursor rules - this project
You are an expert Astro, Tailwind CSS v4 engineer working on this codebase. Follow these rules.
## Project
A Astro + Tailwind CSS v4 project.
Stack: Astro, Tailwind CSS v4.
## Commands
- Dev server: `npm run dev`
- Build: `npm run build`
- Type and template check: `npx astro check`
## Project structure
- Routes in `src/pages/`, layouts in `src/layouts/`, components in `src/components/`.
- Markdown/MDX content lives in content collections with a schema in `src/content.config.ts`.
## How to work in this repo
- Read the relevant files before editing. Follow the patterns already in the codebase over these generic rules.
- Make the smallest change that solves the task. Do not refactor or reformat unrelated code.
- Before saying a task is done, run the type-check, lint and tests listed under Commands and fix what you broke.
- If requirements are ambiguous, ask one clear question instead of guessing.
- Never commit secrets, API keys or `.env` files. Use env vars and keep `.env.example` up to date.
- Do not add a new dependency when the standard library or an existing dependency already covers it.
- Ask before adding, removing or upgrading any dependency.
- Ask before changing database schemas, auth, payments or CI configuration.
- Never delete files, drop data or run destructive commands (`rm -rf`, `git push --force`, `DROP TABLE`) without explicit approval.
- Keep each change under ~200 changed lines where possible; split larger work into steps.
## Astro
- `.astro` components ship zero JavaScript by default. Keep it that way unless interactivity is needed.
- Add interactivity with framework islands and the lightest directive that works: prefer `client:visible` or `client:idle` over `client:load`.
- Define a Zod schema for every content collection and query it with `getCollection()`.
- Use `astro:assets` `<Image />` for local images.
- Generate dynamic routes with `getStaticPaths()` in static mode.
- Set a unique `<title>` and meta description per page through the shared layout.
## Tailwind CSS v4
- Tailwind v4 is configured in CSS: `@import "tailwindcss";` plus `@theme { ... }` for design tokens. Do not create a `tailwind.config.js` unless the project already has one.
- Use theme tokens (colors, spacing) instead of arbitrary values like `w-[37px]`.
- Build responsive layouts mobile-first with `sm:`, `md:`, `lg:` prefixes.
- Extract repeated class lists into components, not `@apply` chains.
- Support dark mode with the `dark:` variant when the project uses it.
## Reference docs
- [Astro docs](https://docs.astro.build)
- [Tailwind CSS docs](https://tailwindcss.com/docs)
.github/copilot-instructions.md
# Copilot instructions - this project
A Astro + Tailwind CSS v4 project.
Stack: Astro, Tailwind CSS v4.
## Commands
- Dev server: `npm run dev`
- Build: `npm run build`
- Type and template check: `npx astro check`
## How to work in this repo
- Read the relevant files before editing. Follow the patterns already in the codebase over these generic rules.
- Make the smallest change that solves the task. Do not refactor or reformat unrelated code.
- Before saying a task is done, run the type-check, lint and tests listed under Commands and fix what you broke.
- If requirements are ambiguous, ask one clear question instead of guessing.
- Never commit secrets, API keys or `.env` files. Use env vars and keep `.env.example` up to date.
- Do not add a new dependency when the standard library or an existing dependency already covers it.
- Ask before adding, removing or upgrading any dependency.
- Ask before changing database schemas, auth, payments or CI configuration.
- Never delete files, drop data or run destructive commands (`rm -rf`, `git push --force`, `DROP TABLE`) without explicit approval.
- Keep each change under ~200 changed lines where possible; split larger work into steps.
.github/instructions/astro.instructions.md
---
applyTo: "src/**/*.astro,src/**/*.ts,src/content/**"
---
# Astro
- `.astro` components ship zero JavaScript by default. Keep it that way unless interactivity is needed.
- Add interactivity with framework islands and the lightest directive that works: prefer `client:visible` or `client:idle` over `client:load`.
- Define a Zod schema for every content collection and query it with `getCollection()`.
- Use `astro:assets` `<Image />` for local images.
- Generate dynamic routes with `getStaticPaths()` in static mode.
- Set a unique `<title>` and meta description per page through the shared layout.
.github/instructions/tailwind.instructions.md
---
applyTo: "**/*.css,**/*.tsx,**/*.vue,**/*.svelte,**/*.astro,**/*.html,**/*.blade.php,**/*.erb"
---
# Tailwind CSS v4
- Tailwind v4 is configured in CSS: `@import "tailwindcss";` plus `@theme { ... }` for design tokens. Do not create a `tailwind.config.js` unless the project already has one.
- Use theme tokens (colors, spacing) instead of arbitrary values like `w-[37px]`.
- Build responsive layouts mobile-first with `sm:`, `md:`, `lg:` prefixes.
- Extract repeated class lists into components, not `@apply` chains.
- Support dark mode with the `dark:` variant when the project uses it.
.windsurf/rules/project.md
---
trigger: always_on
---
# this project
A Astro + Tailwind CSS v4 project.
Stack: Astro, Tailwind CSS v4.
## Commands
- Dev server: `npm run dev`
- Build: `npm run build`
- Type and template check: `npx astro check`
## How to work in this repo
- Read the relevant files before editing. Follow the patterns already in the codebase over these generic rules.
- Make the smallest change that solves the task. Do not refactor or reformat unrelated code.
- Before saying a task is done, run the type-check, lint and tests listed under Commands and fix what you broke.
- If requirements are ambiguous, ask one clear question instead of guessing.
- Never commit secrets, API keys or `.env` files. Use env vars and keep `.env.example` up to date.
- Do not add a new dependency when the standard library or an existing dependency already covers it.
- Ask before adding, removing or upgrading any dependency.
- Ask before changing database schemas, auth, payments or CI configuration.
- Never delete files, drop data or run destructive commands (`rm -rf`, `git push --force`, `DROP TABLE`) without explicit approval.
- Keep each change under ~200 changed lines where possible; split larger work into steps.
.windsurf/rules/astro.md
---
trigger: glob
globs: src/**/*.astro, src/**/*.ts, src/content/**
---
# Astro
- `.astro` components ship zero JavaScript by default. Keep it that way unless interactivity is needed.
- Add interactivity with framework islands and the lightest directive that works: prefer `client:visible` or `client:idle` over `client:load`.
- Define a Zod schema for every content collection and query it with `getCollection()`.
- Use `astro:assets` `<Image />` for local images.
- Generate dynamic routes with `getStaticPaths()` in static mode.
- Set a unique `<title>` and meta description per page through the shared layout.
.windsurf/rules/tailwind.md
---
trigger: glob
globs: **/*.css, **/*.tsx, **/*.vue, **/*.svelte, **/*.astro, **/*.html, **/*.blade.php, **/*.erb
---
# Tailwind CSS v4
- Tailwind v4 is configured in CSS: `@import "tailwindcss";` plus `@theme { ... }` for design tokens. Do not create a `tailwind.config.js` unless the project already has one.
- Use theme tokens (colors, spacing) instead of arbitrary values like `w-[37px]`.
- Build responsive layouts mobile-first with `sm:`, `md:`, `lg:` prefixes.
- Extract repeated class lists into components, not `@apply` chains.
- Support dark mode with the `dark:` variant when the project uses it.
GEMINI.md
# GEMINI.md - this project
Project context for Gemini CLI.
## Project
A Astro + Tailwind CSS v4 project.
Stack: Astro, Tailwind CSS v4.
## Commands
- Dev server: `npm run dev`
- Build: `npm run build`
- Type and template check: `npx astro check`
## Project structure
- Routes in `src/pages/`, layouts in `src/layouts/`, components in `src/components/`.
- Markdown/MDX content lives in content collections with a schema in `src/content.config.ts`.
## How to work in this repo
- Read the relevant files before editing. Follow the patterns already in the codebase over these generic rules.
- Make the smallest change that solves the task. Do not refactor or reformat unrelated code.
- Before saying a task is done, run the type-check, lint and tests listed under Commands and fix what you broke.
- If requirements are ambiguous, ask one clear question instead of guessing.
- Never commit secrets, API keys or `.env` files. Use env vars and keep `.env.example` up to date.
- Do not add a new dependency when the standard library or an existing dependency already covers it.
- Ask before adding, removing or upgrading any dependency.
- Ask before changing database schemas, auth, payments or CI configuration.
- Never delete files, drop data or run destructive commands (`rm -rf`, `git push --force`, `DROP TABLE`) without explicit approval.
- Keep each change under ~200 changed lines where possible; split larger work into steps.
## Astro
- `.astro` components ship zero JavaScript by default. Keep it that way unless interactivity is needed.
- Add interactivity with framework islands and the lightest directive that works: prefer `client:visible` or `client:idle` over `client:load`.
- Define a Zod schema for every content collection and query it with `getCollection()`.
- Use `astro:assets` `<Image />` for local images.
- Generate dynamic routes with `getStaticPaths()` in static mode.
- Set a unique `<title>` and meta description per page through the shared layout.
## Tailwind CSS v4
- Tailwind v4 is configured in CSS: `@import "tailwindcss";` plus `@theme { ... }` for design tokens. Do not create a `tailwind.config.js` unless the project already has one.
- Use theme tokens (colors, spacing) instead of arbitrary values like `w-[37px]`.
- Build responsive layouts mobile-first with `sm:`, `md:`, `lg:` prefixes.
- Extract repeated class lists into components, not `@apply` chains.
- Support dark mode with the `dark:` variant when the project uses it.
## Reference docs
- [Astro docs](https://docs.astro.build)
- [Tailwind CSS docs](https://tailwindcss.com/docs)
Commands your agent should run
| Task | Command |
|---|---|
| Dev server | npm run dev |
| Build | npm run build |
| Type and template check | npx astro check |
What the rules cover
Astro
Content-first static or hybrid sites with Astro islands. Scoped to src/**/*.astro, src/**/*.ts, src/content/** in Cursor, Copilot and Windsurf.
.astrocomponents ship zero JavaScript by default. Keep it that way unless interactivity is needed.- Add interactivity with framework islands and the lightest directive that works: prefer
client:visibleorclient:idleoverclient:load. - Define a Zod schema for every content collection and query it with
getCollection(). - Use
astro:assets<Image />for local images. - Generate dynamic routes with
getStaticPaths()in static mode. - Set a unique
<title>and meta description per page through the shared layout.
Source docs: Astro docs
Tailwind CSS v4
Utility-first styling with Tailwind CSS v4. Scoped to **/*.css, **/*.tsx, **/*.vue, **/*.svelte, **/*.astro, **/*.html, **/*.blade.php, **/*.erb in Cursor, Copilot and Windsurf.
- Tailwind v4 is configured in CSS:
@import "tailwindcss";plus@theme { ... }for design tokens. Do not create atailwind.config.jsunless the project already has one. - Use theme tokens (colors, spacing) instead of arbitrary values like
w-[37px]. - Build responsive layouts mobile-first with
sm:,md:,lg:prefixes. - Extract repeated class lists into components, not
@applychains. - Support dark mode with the
dark:variant when the project uses it.
Source docs: Tailwind CSS docs
How to install
- Copy
AGENTS.mdto your repo root. That covers Codex, Cursor, GitHub Copilot and most other agents. - Using Claude Code? Add a
CLAUDE.mdwith the single line@AGENTS.md, or use the standalone CLAUDE.md tab above. - Want rules that only load for certain files in Cursor? Add the
.cursor/rules/*.mdcfiles. - Commit the files so your whole team (and every agent) shares them.
FAQ
Where do I put the AGENTS.md for Astro + Tailwind CSS v4?
Save it as AGENTS.md in the root of your repository, next to your main config file. Codex, Cursor and GitHub Copilot pick it up automatically. For Claude Code, add a CLAUDE.md containing @AGENTS.md (or use the standalone CLAUDE.md on this page).
What is the most common mistake AI agents make with Astro?
Agents hydrate everything with client:load and turn a fast static site into a heavy SPA.
Which commands should the agent run to check its work?
For this stack: npm run dev, npm run build, npx astro check. They are listed in the generated files so the agent runs them before finishing a task.
Do these Astro + Tailwind CSS v4 rules work with Cursor and Claude Code?
Yes. This page includes the same rules as AGENTS.md, CLAUDE.md, Cursor .mdc project rules, a legacy .cursorrules file, GitHub Copilot instructions, Windsurf rules and GEMINI.md.
Can I customise these rules?
Yes. Open this stack in the generator to add or remove libraries, set your project name and package manager, switch beginner explanations on, and download everything as a zip.
Related stacks
Next.js (App Router) + Tailwind CSS v4 + shadcn/ui + Supabase + Zod validation
The default vibe-coding SaaS stack: Next.js App Router, Supabase for auth and Postgres, Tailwind and shadcn/ui for the interface.
Next.js (App Router) + Tailwind CSS v4
A plain Next.js + TypeScript + Tailwind v4 starter, the most common front-end setup in 2026.
Next.js (App Router) + Tailwind CSS v4 + Prisma + Stripe payments + Zod validation
A paid SaaS on Next.js with Prisma and Stripe subscriptions.
Next.js (App Router) + Tailwind CSS v4 + Drizzle ORM + Clerk auth + Zod validation
Next.js with Clerk for auth and Drizzle ORM on Postgres: fast to build, type-safe end to end.
Next.js (App Router) + Tailwind CSS v4 + shadcn/ui + Vercel AI SDK + Zod validation
Build an AI chat app or agent UI with Next.js and the Vercel AI SDK.
Next.js (App Router) + Tailwind CSS v4 + Supabase + Stripe payments + Zod validation + Vitest
The full indie-hacker SaaS kit: auth, database, payments and tests.