[pull] main from withastro:main

.changeset/eleven-mice-wink.md

@@ -0,0 +1,5 @@
+---
+'create-astro': minor
+---
+
+Adds a default `AGENTS.md` file to new projects with dev server instructions and documentation links. Also creates a `CLAUDE.md` symlink (with hard link fallback) pointing to `AGENTS.md`.

packages/create-astro/src/actions/template.ts

@@ -105,6 +105,32 @@ const FILES_TO_UPDATE = {
 		}),
 };
 
+export function generateAgentsMd(): string {
+	return `## Development
+
+When starting the dev server, use background mode:
+
+\`\`\`
+astro dev --background
+\`\`\`
+
+Manage the background server with \`astro dev stop\`, \`astro dev status\`, and \`astro dev logs\`.
+
+## Documentation
+
+Full documentation: https://docs.astro.build
+
+Consult these guides before working on related tasks:
+
+- [Adding pages, dynamic routes, or middleware](https://docs.astro.build/en/guides/routing/)
+- [Working with Astro components](https://docs.astro.build/en/basics/astro-components/)
+- [Using React, Vue, Svelte, or other framework components](https://docs.astro.build/en/guides/framework-components/)
+- [Adding or managing content](https://docs.astro.build/en/guides/content-collections/)
+- [Adding styles or using Tailwind](https://docs.astro.build/en/guides/styling/)
+- [Supporting multiple languages](https://docs.astro.build/en/guides/internationalization/)
+`;
+}
+
 export function getTemplateTarget(tmpl: string, ref = 'latest') {
 	// Handle Starlight templates
 	if (tmpl === 'starlight' || tmpl.startsWith('starlight/')) {
@@ -185,6 +211,20 @@ async function copyTemplate(tmpl: string, ctx: Context) {
 			throw new Error(`Unable to download template ${color.reset(tmpl)}`);
 		}
 
+		// Generate AGENTS.md for AI coding agents, with a CLAUDE.md link
+		const agentsPath = path.resolve(ctx.cwd, 'AGENTS.md');
+		const claudePath = path.resolve(ctx.cwd, 'CLAUDE.md');
+		fs.writeFileSync(agentsPath, generateAgentsMd());
+		try {
+			fs.symlinkSync('AGENTS.md', claudePath);
+		} catch {
+			try {
+				fs.linkSync(agentsPath, claudePath);
+			} catch {
+				// Link creation failed; AGENTS.md still exists
+			}
+		}
+
 		// Post-process in parallel
 		const removeFiles = FILES_TO_REMOVE.map(async (file) => {
 			const fileLoc = path.resolve(path.join(ctx.cwd, file));

packages/create-astro/src/index.ts

@@ -9,7 +9,11 @@ import { projectName } from './actions/project-name.js';
 import { template } from './actions/template.js';
 import { verify } from './actions/verify.js';
 
-export { processTemplateReadme, removeTemplateMarkerSections } from './actions/template.js';
+export {
+	generateAgentsMd,
+	processTemplateReadme,
+	removeTemplateMarkerSections,
+} from './actions/template.js';
 export { setStdout } from './messages.js';
 
 const exit = () => process.exit(0);

packages/create-astro/test/template-processing.test.ts

@@ -1,6 +1,27 @@
 import assert from 'node:assert/strict';
 import { describe, it } from 'node:test';
-import { processTemplateReadme, removeTemplateMarkerSections } from '../dist/index.js';
+import {
+	generateAgentsMd,
+	processTemplateReadme,
+	removeTemplateMarkerSections,
+} from '../dist/index.js';
+
+describe('generateAgentsMd', async () => {
+	it('includes background dev command', async () => {
+		const result = generateAgentsMd();
+		assert.ok(result.includes('astro dev --background'));
+	});
+
+	it('includes documentation links', async () => {
+		const result = generateAgentsMd();
+		assert.ok(result.includes('https://docs.astro.build/en/guides/routing/'));
+		assert.ok(result.includes('https://docs.astro.build/en/basics/astro-components/'));
+		assert.ok(result.includes('https://docs.astro.build/en/guides/framework-components/'));
+		assert.ok(result.includes('https://docs.astro.build/en/guides/content-collections/'));
+		assert.ok(result.includes('https://docs.astro.build/en/guides/styling/'));
+		assert.ok(result.includes('https://docs.astro.build/en/guides/internationalization/'));
+	});
+});
 
 describe('removeTemplateMarkerSections', async () => {
 	it('removes HTML template marker sections', async () => {