bevyengine / bevyengine/bevy

Improve agentic coding for Bevy projects with versioned Agents.md

Open
#23,867 0 comments 10 reactions 0 assignees View on GitHub
A-Cross-Cutting C-Feature S-Needs-Goal X-Needs-SME
Dominant language
Rust
Stars
48.2k
Forks
4.8k
Avg merge
3d 16h
Merged PRs (30d)
171

Description

## What problem does this solve or what need does it fill?

AI coding assistants (Claude Code, Cursor, GitHub Copilot, etc.) are of course increasingly popular tools, but I've found they struggle to build games with Bevy games because their training data goes stale quickly given the pace of API change between Bevy's releases. This leads to generated code that references removed APIs, nonexistent crates, or outdated patterns, significantly reducing these tools' value.

## What solution would you like?

The Next.js project recently addressed this same problem (new versions outpacing training data) by shipping version-matched documentation alongside their framework and providing a standard `AGENTS.md` file that directs AI agents to read those local docs to supplement their training data. They report dramatically improved accuracy in agent-generated code as a result ([blog post](https://vercel.com/blog/agents-md-outperforms-skills-in-our-agent-evals), [docs](https://nextjs.org/docs/app/guides/ai-agents)).

**I'd like to build something similar for Bevy developers.**

To be clear: I understand the Bevy project's [AI policy](https://bevy.org/learn/contribute/policies/ai/) prohibits LLM contributions to Bevy itself. This proposal is about helping **users of Bevy** who choose to use AI coding tools in their own projects, not about using AI to contribute to Bevy itself.

I'm proposing a tool -- likely a CLI command or cargo subcommand -- that generates an `AGENTS.md` file within a Bevy project, containing:

1. **A compact index of version-matched Bevy documentation** — pointing agents to local doc files rather than relying on training data. This could reference docs bundled in the crate, docs downloaded to a local directory, or docs.rs content for the installed version.

2. **Bevy-specific guidance for AI agents** — key architectural concepts (ECS, systems, components, resources, queries, schedules), common patterns, and pitfalls that agents frequently get wrong.

3. **Migration-aware context** — for projects upgrading between versions, pointing agents to the relevant migration guide so they suggest updated APIs rather than deprecated ones.

The output would be a standard `Agents.md` markdown file that most AI coding tools already know to read automatically when present in a project root.

This would be an optional quality-of-life tool for Bevy's user-developers. Because of its nature, I'd love for this to become an officially blessed/supported project, with updates for each new Bevy release.

## What alternative(s) have you considered?

- **Status quo (do nothing):** Developers individually maintain personal context files for their AI tools. This works but duplicates effort across the community and tends to go stale.
- **Community-maintained prompt/skill:** A few community efforts exist (e.g., Bevy skills on Smithery, individual developers' `bevy.md` files), but they aren't version-specific and aren't maintained alongside the engine itself.
- **llms.txt on bevy.org:** The [llms.txt standard](https://llmstxt.org/) would provide LLM-friendly documentation at the website level, but wouldn't provide version-matched, project-local context the way a bundled solution would.
- **Docs only (no tooling):** Simply publishing an `AGENTS.md` template in the repo or docs that users copy manually. Simpler but less useful without version-matched doc indexing.

## Additional context

I'm volunteering to do the implementation work if the core team is interested in this direction. Before investing that effort, I wanted to gauge whether this is something the project would welcome, and ask whether there are any preferences for scope or approach.

Some open questions I'd appreciate input on:

- **Scope:** Should this live in the Bevy repo, in a separate community tool, or somewhere in between (e.g., a Bevy CLI plugin)?
- **Doc source:** Bevy's documentation landscape is distributed across docs.rs API docs, bevy.org guides, in-repo examples, and migration guides. Which of these would be most valuable to index for agents?
- **Relationship to AI policy:** I want to make sure this kind of contribution — tooling that helps Bevy *users* who happen to use AI assistants — is welcome and doesn't conflict with the project's stance on AI-generated contributions.

Thanks for your time considering this!

Contributor guide

Open the contributing guide

Research direction

No files, tests, or implementation entry point are identified. First resolve whether this belongs in the Bevy repository or a separate tool, then agree on documentation sources, version matching, and AI-policy scope; done means an approved approach for generating a project-local AGENTS.md.

Written by the indexing model from the issue text.

Assessment

Tech stack
rust
Domain
documentation, game-dev, tooling
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Needs clarification
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.