From 9ef9172582b4d0323d28d8200e84496d680d675d Mon Sep 17 00:00:00 2001 From: Matthew Phillips Date: Thu, 18 Jun 2026 15:29:11 -0400 Subject: [PATCH 1/5] Generate AGENTS.md and CLAUDE.md in new projects --- .changeset/eleven-mice-wink.md | 5 +++ packages/create-astro/src/actions/template.ts | 38 +++++++++++++++++++ packages/create-astro/src/index.ts | 6 ++- .../test/template-processing.test.ts | 21 +++++++++- 4 files changed, 68 insertions(+), 2 deletions(-) create mode 100644 .changeset/eleven-mice-wink.md diff --git a/.changeset/eleven-mice-wink.md b/.changeset/eleven-mice-wink.md new file mode 100644 index 000000000000..3db290c381d0 --- /dev/null +++ b/.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`. diff --git a/packages/create-astro/src/actions/template.ts b/packages/create-astro/src/actions/template.ts index 94f1a7b48fb9..a2fffbc6fe62 100644 --- a/packages/create-astro/src/actions/template.ts +++ b/packages/create-astro/src/actions/template.ts @@ -105,6 +105,30 @@ const FILES_TO_UPDATE = { }), }; +export function generateAgentsMd(): string { + return `# Development + +Start the dev server in 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 + +Commonly needed references: + +- [Routing](https://docs.astro.build/en/guides/routing/) +- [Astro Components](https://docs.astro.build/en/basics/astro-components/) +- [Content Collections](https://docs.astro.build/en/guides/content-collections/) +- [Internationalization](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 +209,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)); diff --git a/packages/create-astro/src/index.ts b/packages/create-astro/src/index.ts index 6b2148613d9a..ce2c4083cb55 100644 --- a/packages/create-astro/src/index.ts +++ b/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); diff --git a/packages/create-astro/test/template-processing.test.ts b/packages/create-astro/test/template-processing.test.ts index a14a979e7e34..edc5fbf2b03c 100644 --- a/packages/create-astro/test/template-processing.test.ts +++ b/packages/create-astro/test/template-processing.test.ts @@ -1,6 +1,25 @@ 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/content-collections/')); + assert.ok(result.includes('https://docs.astro.build/en/guides/internationalization/')); + }); +}); describe('removeTemplateMarkerSections', async () => { it('removes HTML template marker sections', async () => { From abcf1ff25a5139421d20ae66a5c70c31029b9c08 Mon Sep 17 00:00:00 2001 From: Matthew Phillips Date: Fri, 19 Jun 2026 08:39:38 -0400 Subject: [PATCH 2/5] Update packages/create-astro/src/actions/template.ts Co-authored-by: Armand Philippot --- packages/create-astro/src/actions/template.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/create-astro/src/actions/template.ts b/packages/create-astro/src/actions/template.ts index a2fffbc6fe62..d4e661c47867 100644 --- a/packages/create-astro/src/actions/template.ts +++ b/packages/create-astro/src/actions/template.ts @@ -116,7 +116,7 @@ astro dev --background Manage the background server with \`astro dev stop\`, \`astro dev status\`, and \`astro dev logs\`. -# Documentation +## Documentation Full documentation: https://docs.astro.build From b04447f5752f8e76ccff5960928bdc16a75f7274 Mon Sep 17 00:00:00 2001 From: Matthew Phillips Date: Fri, 19 Jun 2026 08:39:46 -0400 Subject: [PATCH 3/5] Update packages/create-astro/src/actions/template.ts Co-authored-by: Armand Philippot --- packages/create-astro/src/actions/template.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/create-astro/src/actions/template.ts b/packages/create-astro/src/actions/template.ts index d4e661c47867..7f6d12097544 100644 --- a/packages/create-astro/src/actions/template.ts +++ b/packages/create-astro/src/actions/template.ts @@ -106,7 +106,7 @@ const FILES_TO_UPDATE = { }; export function generateAgentsMd(): string { - return `# Development + return `## Development Start the dev server in background mode: From 74215c14227d91fd719c3a8fa7ed03686cd95b71 Mon Sep 17 00:00:00 2001 From: Matthew Phillips Date: Fri, 19 Jun 2026 08:52:07 -0400 Subject: [PATCH 4/5] Improve AGENTS.md with task-oriented links and styling guide --- packages/create-astro/src/actions/template.ts | 14 ++++++++------ .../create-astro/test/template-processing.test.ts | 2 ++ 2 files changed, 10 insertions(+), 6 deletions(-) diff --git a/packages/create-astro/src/actions/template.ts b/packages/create-astro/src/actions/template.ts index 7f6d12097544..5626a139165e 100644 --- a/packages/create-astro/src/actions/template.ts +++ b/packages/create-astro/src/actions/template.ts @@ -120,12 +120,14 @@ Manage the background server with \`astro dev stop\`, \`astro dev status\`, and Full documentation: https://docs.astro.build -Commonly needed references: - -- [Routing](https://docs.astro.build/en/guides/routing/) -- [Astro Components](https://docs.astro.build/en/basics/astro-components/) -- [Content Collections](https://docs.astro.build/en/guides/content-collections/) -- [Internationalization](https://docs.astro.build/en/guides/internationalization/) +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/) `; } diff --git a/packages/create-astro/test/template-processing.test.ts b/packages/create-astro/test/template-processing.test.ts index edc5fbf2b03c..5cce0f8a8e0d 100644 --- a/packages/create-astro/test/template-processing.test.ts +++ b/packages/create-astro/test/template-processing.test.ts @@ -16,7 +16,9 @@ describe('generateAgentsMd', 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/')); }); }); From 152cff76605e06e89e15dd5e5edabeb48f938474 Mon Sep 17 00:00:00 2001 From: Matthew Phillips Date: Fri, 19 Jun 2026 09:42:58 -0400 Subject: [PATCH 5/5] Refine AGENTS.md dev server wording --- packages/create-astro/src/actions/template.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/create-astro/src/actions/template.ts b/packages/create-astro/src/actions/template.ts index 5626a139165e..f7fbf3f42ec7 100644 --- a/packages/create-astro/src/actions/template.ts +++ b/packages/create-astro/src/actions/template.ts @@ -108,7 +108,7 @@ const FILES_TO_UPDATE = { export function generateAgentsMd(): string { return `## Development -Start the dev server in background mode: +When starting the dev server, use background mode: \`\`\` astro dev --background