Proposal: Add common instruction files for AI assisted coding tools

[jonathanbossenger]

This is a proposal to add support for the most commonly used AI Coding tools.

• GitHub Copilot
• Cursor
• Claude Code

This will allow developers who use these tools to ramp up when contributing to this project quickly.

[gziolo]

Is there any prior art in existing WordPress repositories that we could use for inspiration?

[jonathanbossenger]

Not that I'm aware of. We might pioneer the space.

[gziolo]

I was using locally GitHub Copilot code agent this week, and it was able to quickly sort out how to run tests, linting and fix issues after some hints I shared. However, it would be great to have that stored in instructions so these tools can discover it automatically 👍🏻

[justlevine]

This makes me very nervous.

I need to delete WPGraphQL's (canonical but not in WordPress/*) files before I contribute because they produce worse results than no files at all.

These files are immediate tech debt, notoriously temperamental, and even if you were to theoretically tweak and test them per model/code-tool release (or unversioned background changes) what's the point? Currently they're not much more effective than pointing the agent to the actual docs. And unlike vibe-coded slop or external plugins, this is a WordPress core project. We have docs, coding standards, tools to enforce, style guides.

If we want to pioneer the space, then perhaps experimenting, ideating and publicly sharing personal instruction files is a better way to start

(Also:

Source: https://x.com/shadcn/status/1955254151807635602
)

[jonathanbossenger]

I need to delete WPGraphQL's (canonical but not in WordPress/*) files before I contribute because they produce worse results than no files at all.

I'd argue that the content of the cursor rules for WPGraphQL are more likely the problem, vs the fact that they exist. Take a look at the cursor rules for the wp-feature-api for example. Way better context for the Cursor AI. Additionally, the rule is set not to be auto-applied, so Cursor users can choose to apply it on a per-request basis.

Source: https://x.com/shadcn/status/1955254151807635602

The same could be said for all the config files sitting in the root of the repository. But they provide value, both to developers who use them in their local development environments and for the checks that run on pull requests, so we've adapted to having them in our codebase.

If we can learn from other repositories who are actively allowing these rules files, I'm sure we could put our collective heads together (we are the WordPress AI team after all) and place ourselves in a position of creating a set of files that set the standards for useful context to AI without burndening developers who choose not to use them.

[justlevine]

I need to delete WPGraphQL's (canonical but not in WordPress/*) files before I contribute because they produce worse results than no files at all.
I'd argue that the content of the cursor rules for WPGraphQL are more likely the problem, vs the fact that they exist.

I agree with you, that's exactly what I meant by "immediate tech debt". Jason's file works great in pre v0.50 versions before tool calls, memory, and agents could navigate a large repo themselves without losing the way.

If you rollback to pre-Cursor 1.3.6 you'll get significant better results for the same wp-feature-api config (since 1.3.6 it prefers fewer direct rules and offlinks to real docs), and my guess based on similarly structured instruction files I've had to work on/against is that they'll also do worse if you're using, GPT 4.1/5/Gemini 2.5 than with Sonnet 3.7 (maybe 4 too).

But they provide value,

To be pedantic, tooling dotfiles provide

• clear, demonstratable, value and purpose (to run the tool)
• established ways to keep maintained (monitor the changelog for a single tool, know what matrix the tool needs to be run against)
• are still usually discussed in terms of cost vs benefit.

All of that's hard to do here - at minimum I'd assume a benchmark of the same task done

1. with no rules
2. vs a rule that only says "Read CONTRIBUTING.md to understand how to navigate and contribute to this project"
3. with the proposed rules.

And even then we need to take take it all w. a grain of salt because different rules work better (or worse) with different User<->LLM coding styles/tasks/goals

If we can learn from other repositories who are actively allowing these rules files, I'm sure we could put our collective heads together (we are the WordPress AI team after all) and place ourselves in a position of creating a set of files that set the standards for useful context to AI without burndening developers who choose not to use them.

Back in agreement 😎

I just probably just less optimistic than you and think this will take more time to sort through and "figure out" best practices and finding codeowner(s) to keep the files actively tested, tuned, and working well for the tools we decide to support , all while the marginal value decreases as coding tools improve their abilities to self-discover, reason, and tool-call with the normal docs and .dist files.

[gziolo]

@felixarntz opened a Trac ticket to discuss adding an AGENTS.md file for the WordPress project. Let's track the progress and act accordingly.

[jonathanbossenger]

I just learned about https://agents.md/, happy to wait till that's merged into Core and then act accordingly.

[karmatosed]

Just going to add that #64 relates to this so we might want to close this as we have specific issues, or pivot this into the issue and have PRs as needed.