microsoft
Standardized Rules Format
A number of us (VSC included) need some kind of context ("rules") defined per-codebase. This is often used to indicate the ways you should write code, the technologies you use.. generally speaking its a mix of preference and knowledge.
Today these rules exist in various fashion, but here are some known patterns:
- a rules directory (e.g. .cursor/rules/)
- settings dialog (e.g. Sentry's solution uses this)
- llms.txt or similar (agents.md is another example)
Formats I've seen:
- markdown + headers, where headers usually indicate how the rule might be applied
- undefined text
Its important that the core of this is reusable so developers dont need to reimplement these context providers in multiple formats, let alone in formats outside of the version control system. I do believe a single file is the wrong solution, as we shouldnt require these context files be only functional with RAG or large context windows. Having basic indicators in the format (e.g. this applies to this glob) is extremely helpful.
I'm going to leave it up to others to provide feedback who have more knowledge in the space, but I'm representing Sentry's concerns here. One point of inspiration Sentry has talked about is the OWNERS file constructs, and how its become a bit of a standard over time (albeit with a GitHub flavored addition).
I’d propose using a convention like:
.ai-rules/**/*.md (markdowns + headers just like Cursor supports)
This enables better categorization by topic or feature area (e.g., .ai-rules/frontend/linting.md, .ai-rules/backend/security.md) while keeping it consistent.
This keeps things modular, versioned, and LLM-friendly and still very human-readable.
.ai-rules/
├── frontend/
│ ├── styling.md
│ └── components.md
├── backend/
│ └── api-guidelines.md
├── common/
│ └── naming.md
I like the way Copilots *.prompt.md and *.instruction.md (and Cursor rules files) work in terms of:
- markdown + front matter header (MDC)
- specifically the
applyTo: "*.py"/glob: *.pyglob pattern header in instruction files
I'm not a fan of the idea of having rule files littered through a code bade. I think will make it harder to understand, reason, and troubleshoot rules. Having none app code related files next to code is also distracting.
It's probably worth considering if these rules should live in a folder name with room for scope beyond rules similar to the .github folder.
So may be
.ai/
|--rules/
|. |-- some-global.rule.md
|. |-- some-sub-folder/
|. |-- another.rule.md
| -- prompts/ |
|---|
Seems like the *.mdc file extension isn't a broad standard.
ref: https://code.visualstudio.com/docs/copilot/copilot-customization#_custom-instructions-example https://docs.cursor.com/context/rules
A humble suggestion: These rules aren't meant solely for AI. Thus, I propose that we refrain from overusing AI - related keywords in the naming process？
A humble suggestion: These rules aren't meant solely for AI. Thus, I propose that we refrain from overusing AI - related keywords in the naming process？
While I understand the sentiment I disagree. They are actually optimized for constrained context windows vs maximizing readability. You will often take shortcuts on brevity where an LLM can grok what’s going on while a human would think it’s not clear enough.
Trying to solve too many problems is a good way to not solve any problems. Rules are effectively context machines and/or playbooks designed for model consumption first and foremost. The tech is not cheap enough - nor do we have something akin to a RAG here - to take liberties with the use of them.
Just a heads up and ask for feedback/contribution. We're starting an open context standards initiative over here with major agent providers as well as infrastructure companies around surfacing emerging opportunities for context and delivery. Bringing this up here because the first spec for grounding this initiative is solving this challenge of fragmentation of client-hosted context. Here is the initial spec which would benefit from community review as well https://github.com/opencontextstandards/ocs/pull/1
A humble suggestion: These rules aren't meant solely for AI. Thus, I propose that we refrain from overusing AI - related keywords in the naming process？
@yuanyan what are some key none AI use cases?
As far as scope is concerned, I agree with @dcramer that trying to do too much means it's hard to do anything. Protocols that succeed (like. MCP) do so because of their conceptual simplicity.
If we started by tackling the core problem and building up, it seems to me that we need to answer a few key questions thinking about rules specifically at a project level.
- Name
- Location
- Front Matter
From there we can abstract to answer more abstract questions.
Love the idea of standardizing. By chance I also had related conversations at Build and Anthropic's conference this week. Also related past ideas on solving this with tools https://ainativedev.io/news/vibe-rules
I'll gather some more thoughts from other collaborators, but top of mind:
- Not all agents will run in workspace root, some workflows will be folder-based; requires recursive instruction discovery.
- Clarify suport for both user and workspace-level file-based instructions.
Started commenting in https://github.com/opencontextstandards/ocs/pull/1 to see where its going.
Not all agents will run in workspace root, some workflows will be folder-based; requires recursive instruction discovery.
@digitarald can you elaborate on that ^ pls
Not all agents will run in workspace root, some workflows will be folder-based; requires recursive instruction discovery.
The challenge of running AI in large mono repos; or even shared repo for frontend/backend. Some work needs to be aware of all-up workspace, while other work is better done scoped to a specific folder.
Quick ecosystem update: OpenAI bought the domain AGENTS.md (as many mentions of the file become links and they can't link to random websites), which could unblock Google's Gemini and SourceGraph's Amp team to adopt AGENTS.md as folder-based cascading custom instructions.
Feel free to reach out if you work on related problems.
+1 on this proposal—standardizing rules formats for AI coding agents is crucial to reduce fragmentation and improve developer workflows across tools like GitHub Copilot, Cursor, and others.
I fully support starting with a simple, unified file like AGENTS.md in the project root for natural language guidelines (e.g., coding styles, security practices, workflows). This minimalist approach, inspired by patterns like Codex CLI's use of AGENTS.md, allows rules to be defined once and reused interoperably, avoiding the need for tool-specific files (e.g., .github/copilot-instructions.md or CLAUDE.md). Benefits include:
- Interoperability: Seamless sharing across agents, enabling teams to mix tools without redundant configs.
- Efficiency: Simplifies maintenance, version control integration, and onboarding, while supporting extensions like globs or hierarchies if needed later.
- Community Momentum: Builds on successful standards like EditorConfig or SemVer, fostering ecosystem-wide adoption.
For a concrete implementation in Copilot Chat/VS Code, see my detailed feature request here: #256828, which outlines backend changes to support AGENTS.md alongside existing files.
More on the spec and supporting tools at https://agent-rules.org/.
Disclaimer: I am the maintainer of https://agent-rules.org/.
While I agree that a folder based approach might be the better technical solution (allowing multiple files) there is a lot of possible variations, e.g. just multiple files, vs opt-in/opt-out per file, vs passing in arguments (Claude), vs mode per file (Roo Code), vs metadata (cursor), vs file glob parameters (continue.dev).
Right now it simply isn't the lowest common denominator.
Adding standard support for a single AGENTS.md file is something that could be done right now, in just a few lines of code, by pretty much every tool in the market. i.e. is trivial to do.
I think that makes a good version 1.0 of a standard, that is already natively supported by at least 3 tools (ChatCPT Codex, OpenCode, Factory AI), and 2 that support it via configuration (Google Gemini and Aider). AMP, who are also pushing standardisation, have also said they will change to use it.
Version 2.0 can then hash out having a whole folder, and how or what metadata should be mandatory ... and then there would be varying amount of effort by different tools required to support directly handling, metadata parsing, etc. That's if you can agree on what the best complicated approach is.
https://agents.md/ is live; unblocking this work.
@digitarald is it going to be supported on both copilot agent in vs code and copilot coding agent in github.com?
@digitarald once this feature will go live, copilot-instructions.md will be optional?
https://github.blog/changelog/2025-08-28-copilot-coding-agent-now-supports-agents-md-custom-instructions/
Copilot coding agent now supports AGENTS.md custom instructions
https://github.blog/changelog/2025-08-28-copilot-coding-agent-now-supports-agents-md-custom-instructions/
Copilot coding agent now supports AGENTS.md custom instructions
It seems to be only for the web-version of the Copilot (github.com), is it known when this is coming to the VS Code Copilot plugin?
Roughly 2 weeks per @digitarald. Chat and agent. I imagine it will fallback to copilot-instructions.md at that point, but wait and see I guess.
https://github.com/openai/agents.md/issues/8#issuecomment-3235006464
Closed by https://github.com/microsoft/vscode/pull/263620 which landed a new setting in Insiders. 1.104 release is next week.
@aeschli trying to verify with a simple test case, but right now none of my agents in any workspace load ANY custom instructions or agents files.
Both AGENTS.md and .github/copilot-instructions.md work for me.
Even both:
I actually have the same problem. Before .github/copilot-instructions.md was working, now its not. Only .github/instructions/* are working. This is despite having:
"github.copilot.chat.codeGeneration.useInstructionFiles": true, "chat.useAgentsMdFile": true,
@digitarald please reopen the issue until bugs will be fixed. This will help people to track this feature and reliable manner. Thanks
There was a fix yesterday, so you need the latest insiders:
Version: 1.104.0-insider Commit: 8bdbcf0e32b1b6e4b328dd86656279860f24123a Date: 2025-09-04T05:03:21.822Z
@aeschli - GHCP picks up only the agents.md file at the repo root. What if we have multiple agents.md files in a large mono repo?
https://agents.md says this:
- Large monorepo? Use nested AGENTS.md files for subprojects Place another AGENTS.md inside each package. Agents automatically read the nearest file in the directory tree, so the closest one takes precedence and every subproject can ship tailored instructions. For example, at time of writing the main OpenAI repo has 88 AGENTS.md files.
It looks like GH copilot web adopted AGENTS.md earlier than in VSCode, yet I just got this message in my PR after a copilot review, after renaming copilot-instructions to AGENTS.
Sorry, I know this probably isn't the right place to report this, though I couldn't find a repo for copilot web. Could someone redirect me to the right repo?
