[Discussion] Introduce AI-facing documentation #5205
Description
As many of you know with the rapid rise of AI coding assistants like Cursor , Github Copilot , Claude , many new contributors are relying on LLMs to generate PRs. This is great for getting people involved and trying to contribute, but there’s a catch: these AIs don't know our specific project rules.
Right now, when someone points an AI at the repo and says "fix this bug" or "add this feature", the AI will just generate a PR, but it has no idea that:
You need to open an issue first before submitting a PR
PR titles must follow conventional commits (feat:, fix:, docs:, etc.)
One PR should do one thing, not five things at once
There are specific patterns we use in this Next.js/TypeScript/Tailwind codebase
Its basically a waste of time on both side , the PR is technically working but miss all the process stuff that maintainers have to point out in the review.
The idea is simple, these files are read automatically by AI coding tools and tell them the project specific rules upfront, before they start writing code. Instead of the maintainer catching it in review, the AI catches it before it even writes the PR.
What I'm proposing -
Add one or more of the following files to the root of the AsyncAPI website repo
AGENTS.md that read by OpenAI Codex-based tools and several others, becoming something of an informal standard
.cursorrules that read by the Cursor IDE, which a lot of contributors use
CLAUDE.md that picked up by Claude when working in a directory
Please dont consider these as a replacement to CONTRIBUTING.md, they're more like a cheat sheet written specifically for AI tools.