Standardized Rules for AI-assisted Software Development and Coding Agents
Software development is changing rapidly, and AI coding agents (Codex, Claude Code, GitHub Copilot, Cursor, Windsurf, Sourcegraph, Augment Code, etc.) are at the forefront of this transformation. Each of these tools has its own approach to defining and managing rules that guide AI behavior. These rules are critical to the success of future software development because of the need to ensure that the AI is behaving in a way that is consistent with the developer's intent and in a secure way. This initiative explores the fragmented landscape of AI coding agent rules and proposes a unified standard to enable interoperability, quality, and security in AI-assisted software engineering.
The AI Coding Agent Rule Fragmentation Problem
The power of AI coding agents is undeniable, but their growth has led to a fractured ecosystem. Each major tool (e.g. Cursor, Codex, Claude Code, Augment Code, Sourcegraph, Windsurf, GitHub Copilot, etc.) uses its own proprietary system for defining the rules that guide AI behavior. This section provides an overview of each tool's approach, highlighting the challenges this fragmentation creates for developers and organizations aiming for consistent, high-quality, and secure code.
We need a vendor-agnostic standard designed to unify the definition, scoping, and application of rules for AI coding agent behavior. The proposed specification synthesizes existing best practices observed in leading tools and introduces a resilient framework to support the future evolution of AI-assisted development.
Examples of Current Rule System Implementations
Each major AI coding agent has developed its own approach to rule definition and management. The chart below provides a high-level visual comparison of key features across a few platforms (not a complete list), while the table offers a detailed breakdown of their current implementations. They are all great in most of the categories; however, this analysis reveals the fragmentation that motivates the need for a unified standard.
| Feature | Cursor | Windsurf | GitHub Copilot | Augment Code |
|---|---|---|---|---|
| File Location | .cursor/rules + User Rules | global_rules.md + .windsurf/rules | .github/copilot-instructions.md | .augment/rules |
| Rule Types | Always, Auto, Agent, Manual | Always On, Model Decision, Glob, Manual | Repository-wide with applyTo scoping | Always, Auto, Manual |
| Scoping Mechanism | Nested dirs + glob patterns | Global vs Workspace + globs | applyTo frontmatter | Directory auto-import |
| File Format | MDC with metadata | Markdown (12K limit) | Markdown | .md or .mdx |
| Manual Activation | @ruleName | @mention | Not supported | @tag |
| AI-Driven Selection | Yes (Agent Requested) | Yes (Model Decision) | No | Yes (Auto) |
Foundational Principles for a Standard
Based on the analysis of existing systems and software engineering best practices, a successful standard must be built on a set of core principles. These tenets ensure the standard is robust, future-proof, and serves the needs of the entire development community.
Declarative & Human-Readable
Define *what* to do using natural language for model-agnostic readability.
Modular & Composable
Build complex behaviors from small, reusable rule components.
Hierarchical & Overridable
Support layers of rules (user, project, org) with clear precedence.
Version-Controlled & Discoverable
Treat rules as code, storing them alongside the project in Git. This is the best distribution mechanism for rules.
Testable & Validatable
Ensure rules can be verified to prevent "AI drift" and errors.
Extensible & Tool-Agnostic
Accommodate future AI capabilities and prevent vendor lock-in. This is the best way to ensure that the rules are not tied to a specific tool.
The AI Coding Agent Rule Spec Proposal
The Open AI Coding Agent Rule standard is a unified framework for defining AI coding agent rules. It combines the precision of a structured format (YAML) with the expressiveness of natural language (Markdown). Explore the core components of the proposed specification below.
Rule Definition Language (RDL)
The spec proposes a hybrid format: YAML for machine-readable structure and metadata, with embedded Markdown for human-readable, natural language guidance. This balances precision for tools with the flexibility needed to convey nuanced intent to an LLM.
id: "unique-rule-id"
name: "Human-Readable Name"
description: "What this rule does."
guidance: |
# Markdown instructions for the AI
- Follow these steps...
- Use this specific library...Scoping & Hierarchy
A formalized hierarchy ensures rules are applied predictably. More specific rules override broader ones, providing both centralized governance and local flexibility. The diagram shows the order of precedence.
Example Rule Anatomy
The following is an example of a rule that is composed of standardized fields to ensure it is discoverable, understandable, and actionable by any compliant AI agent.
- id, name, description: Core identifiers.
- guidance: The Markdown-based instructions for the AI.
- applies_when, triggers: Defines the context for rule activation.
- examples: Concrete good/bad code snippets to guide the AI.
- tools_allowed: Explicitly grants permission to use tools like `run_command` or `web_search`.
- priority: A numeric value for fine-grained conflict resolution.
Illustrative Example: Clean Architecture
This example shows how the spec can enforce a complex architectural pattern, including directory structure and security guidelines for credential security.
- id: "arch-clean-service-template"
name: "Clean Architecture Service Template"
description: "Ensures new services adhere to Clean Architecture principles."
applies_when: Always
guidance: |
# Clean Architecture Service Guidelines
When creating a service, adhere to Clean Architecture.
**1. Directory Structure:**
- `domain/`: Core business logic.
- `application/`: Use cases.
- `infrastructure/`: External details (DB, APIs).
**2. Credential Security:**
- NEVER store credentials in the codebase (i.e., NO hardcoded credentials)
- Use environment variables in examples but suggest the use of a secrets manager.
- Use a tool like `dotenv` to load environment variables from a `.env` file.
- Use a tool like `dotenv-expand` to expand environment variables in the codebase.
- Use a tool like `dotenv-vault` to store and manage environment variables in a secure way.
Help shape the future of AI coding agent rules.