Generate default AGENTS.md in new projects

[matthewp]

Changes

• create-astro now generates an AGENTS.md in new projects with dev server background mode instructions and links to commonly needed Astro docs.
• Creates a CLAUDE.md symlink pointing to AGENTS.md, with a hard link fallback for Windows environments without Developer Mode.

Testing

• Added generateAgentsMd tests verifying the background dev command and documentation links are present.

Docs

• No docs update needed. This is a scaffolding change that generates a file for AI coding agents, not a user-facing API.

[changeset-bot]

🦋 Changeset detected

Latest commit: 152cff7

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
create-astro	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[ArmandPhilippot]

I wonder if we could have this opt-in instead? I mean a CLI option in create-astro to create those files and maybe a CLI flag to automatically approve those files (then, we'll need docs, at least for the CLI flag).

Not everyone use AI, and not everyone use Claude. I think some people might complain about these files and an opt-in option would be more useful to everyone.

To be clear, I don't think this is a bad idea! But, I'm more in favor of letting people choose. As a Linux user, I hate tools that clutters my ~/ instead of following XDG conventions. As a dev, I prefer a minimal clean up when starting a new project. I don't think I'm the only one... but I could be wrong. 😄

[ematipico]

Myself and Matthew discussed this (I was the opt-in faction), and agreed that adding this document doesn't make any harm.

This is an additive document that doesn't make any harm to people that don't use AI or something else.

Also, asking that to the user might cause friction during the installation process (we've been removing questions instead of adding them).

Plus, the file is small on purpose.

[ArmandPhilippot]

Oh, the file size wasn't an issue for me! I wouldn't mind if it contained more instructions (e.g. astro add, check for new features / what we recommend in https://docs.astro.build/en/guides/build-with-ai/#tips-for-ai-powered-astro-development).

I preferred to be cautious as I know some people are already wondering why there is a .astro folder in their project (probably something we should mention in "Project structure"), or "why I have a session log when I haven't enabled it", etc.

But, yeah, more questions during installation can be an issue too... So, no problem!

[ArmandPhilippot]

Honest question: why those references and not others? Is it based on most popular pages on the docs website? Things AI struggle the most?

I mean https://docs.astro.build/en/guides/styling/ (especially for Tailwind users...) or https://docs.astro.build/en/guides/framework-components/ (a lot of users use them) sounds like common needed references too. I know we can't be exhaustive. I was just wondering if it was random or if there was a reason behind it. 😄

[matthewp]

Yeah i was trying to balance between providing some useful links for common and non-obvious things (Content collections being the big one I thought was needed) and not just literally linking to every guide on the site. We can definitely curate this more but think it should stay at <10 at least.

This prompt can use some improvement to more strongly suggest referencing those pages for certain task. I agree that styling would be good, I'll add it.

[matthewp]

Ok, I've updated them to be more task-oriented so the agent knows to read them for those tasks, and added styling as well.

[matthewp]

@ArmandPhilippot The reason for submitting this PR now is because in Astro 7 we have a new --background feature that is very useful for AI tools. When you run just astro dev we detect if it is running within an agent and automatically treat it like --background. However, not all agents are detectable, OpenCode for example is currently not. This means that if you just prompt "start the dev server", it won't know to do it in the background.

So setting up new projects to know to do this was the main motivation for this change.

As far as making it an option, I don't think that's the right call for a few reasons:

• Software development is overwhelming moving towards using AI tools. There are a vocal number of people who do not like them, but they are the minority and becoming more so over time. Here's an article from last year that showed (at the time) that 84% of engineers were using or planning to use AI tools. This is likely growing.
• It just adds a markdown file. If someone isn't using AI tools it doesn't affect them, other than perhaps some people not liking that the file is there. They can just delete the file.
• We have debated for years about every option and have strived to not have too many options. Adding options adds friction. Previously we had an option that asked if the user wanted TypeScript or not. We removed it because very few people didn't want TypeScript. I think we're in a similar situation now. Asking this question adds friction for very little benefit. We're really only talking about some people who might be mad about a file existing because they dislike AI. I don't think we should make decisions for the framework to cater to that.

[ArmandPhilippot]

Software development is overwhelming moving towards using AI tools. There are a vocal number of people who do not like them, but they are the minority and becoming more so over time. Here's an article from last year that showed (at the time) that 84% of engineers were using or planning to use AI tools. This is likely growing.

Yeah, I was thinking more about people who are not software engineers and who create a website for their association or family members. I mean, I think this is also one of our target (that's why we explain in the tutorial they need a code editor, they can use a GitHub repository, etc.).

I wasn't aware that this had already been discussed with Ema, and I appreciate you taking the time to provide the context. Everything is fine here!

[codspeed]

Merging this PR will not alter performance

✅ 18 untouched benchmarks

---

_{Comparing default-agents-md (64d1987) with main (0fd535d)¹}

Footnotes

1. No successful run was found on main (7e7ab87) during the generation of this report, so 0fd535d was used instead as the comparison base. There might be some changes unrelated to this pull request in this report. ↩

[ArmandPhilippot]

Seems good to me, thanks for the update!

[matthewp]

@ArmandPhilippot Appreciate the conversation and review!

[ematipico]

I wasn't aware that this had already been discussed with Ema

We have a regular 1:1 :)