# AI tool rules starter for Quake AI projects Source: https://docs.quake.ai/resources/ai-assisted-development/ai-tool-rules-starter Markdown: https://docs.quake.ai/resources/ai-assisted-development/ai-tool-rules-starter.md > A project rules starter that grounds AI coding assistants in Quake AI's vocabulary so generated IaC targets the platform, with file shapes per tool. --- # AI tool rules starter for Quake AI projects A project rules starter for AI coding assistants working on Quake AI infrastructure. The pattern is **AGENTS.md at the project root** as the canonical instructions file, plus one thin adapter file for each tool that prefers its own path. The rules ground an assistant in the platform's vocabulary (flavor naming, the OpenTofu provider, S3-compatible endpoints, security group semantics, managed-service status) so generated IaC matches Quake AI rather than the closest analog in the model's training data. This page covers the file shapes for Cursor, Claude Code, GitHub Copilot, Windsurf, Zed, OpenAI Codex CLI, Aider, and Continue. Pair these rules with the [Quake AI MCP server](/resources/ai-assisted-development/ai-assisted-development) for live retrieval of documentation and infrastructure templates. ## Start with AGENTS.md `AGENTS.md` at the project root is the file with the widest cross-tool reach today. OpenAI Codex CLI, GitHub Copilot coding agent, Windsurf, and Zed all read it directly. Cursor reads it as an alternative to `.cursor/rules/`, and Claude Code can import it from `CLAUDE.md`. Drop the file at the git repo root and add a thin adapter for tools that need one. Save the following as `AGENTS.md` in your project root: ```markdown # Quake AI project context This project provisions infrastructure on Quake AI, an OpenStack-based public cloud. The conventions below apply when generating Terraform / OpenTofu, Ansible, or Heat templates. ## Platform invariants - Refer to the platform as "Quake AI" (not "Quake AI"). "Quake AI" alone is a video platform, a different product with the same brand root. - Instance flavors follow `{family}.{size}` (for example `m2a.large`, `m2a.xlarge`, `r2a.4xlarge`). See the flavor reference at `/docs/compute/concepts/flavors` for vCPU, RAM, and disk per size. - The primary IaC tool is OpenTofu. The HCL syntax is compatible with Terraform, but the runtime, registry, and provider behavior diverge. - Provider: OpenStack. Use the `openstack` Terraform / OpenTofu provider. - Object storage is S3-compatible. The endpoint is environment-specific. - Kubernetes clusters are provisioned via the Quake AI Kubernetes service (Magnum). - Managed databases are not offered. Deploy databases on compute instances. ## Code generation rules When generating OpenTofu or Terraform code: - Source flavor names from `/docs/compute/concepts/flavors`. Do not invent flavor names. - Use floating IPs for external access. Do not assign public IPs at launch. - Security groups are stateful. Define ingress rules only. - Use OpenStack application credentials for provider authentication, not user passwords. When generating Ansible playbooks: - Use the `openstack.cloud.openstack` dynamic inventory plugin (set `plugin: openstack.cloud.openstack` in the inventory YAML). - The external network is `PublicStatic` or `PublicEphemeral`. The literal name `public` is not a valid network. ## Build and validation - IaC templates ship with an `outputs.tf` so a Verify step can read instance IPs, network IDs, and volume IDs after apply. - Apply against a project that has a default-tier quota unless the template documents otherwise. ``` Keep the file under 200 lines so it fits in tool context budgets. Anything project-specific (your own services, naming conventions, test commands) goes below the Quake AI invariants. ## Tool adapters Each tool reads instructions from a different path. Cursor, Claude Code, Windsurf, and Zed prefer their own filenames; GitHub Copilot has its own. The adapters below either re-export the AGENTS.md content or import it. Pick the adapter for each tool your team uses. | Tool | Adapter file | Pattern | |---|---|---| | Cursor | `.cursor/rules/project-conventions.mdc` | Frontmatter with `alwaysApply: true` | | Claude Code | `CLAUDE.md` | `@AGENTS.md` import directive | | GitHub Copilot | `.github/copilot-instructions.md` | Copy of the AGENTS.md body | | Windsurf | `.windsurf/rules/project-conventions.md` | Frontmatter with `trigger: always_on` | | Zed | `.rules` | Symlink or copy of `AGENTS.md` | | OpenAI Codex CLI | `AGENTS.md` | No adapter; Codex reads `AGENTS.md` natively | | Aider | `.aider.conf.yml` with `read: [AGENTS.md]` | Loads AGENTS.md as read-only context | | Continue | `config.yaml` `rules:` array | Inline rules or `uses: file://AGENTS.md` | ### Cursor Cursor reads project rules from `.cursor/rules/*.mdc` (folder format, current) or the legacy `.cursorrules` flat file. New projects should use the folder format. Save as `.cursor/rules/project-conventions.mdc`: ```markdown --- description: Quake AI project conventions globs: ["**/*.tf", "**/*.tofu", "**/*.yaml", "**/*.yml"] alwaysApply: true --- See `AGENTS.md` at the project root for the full Quake AI invariants and code generation rules. When generating OpenTofu / Terraform code, source flavor names from `/docs/compute/concepts/flavors`, use floating IPs for external access, and treat security groups as stateful (ingress rules only). ``` If your project predates this convention and ships a flat `.cursorrules` file, leave it in place for compatibility and add the folder version above. Plan to remove the flat file when no one on the team still runs an older Cursor build. ### Claude Code Claude Code reads `CLAUDE.md` at the project root. The `@path` directive imports another file so `AGENTS.md` is the single source of truth. Save as `CLAUDE.md`: ```markdown # Project instructions for Claude Code @AGENTS.md ## Claude Code-specific notes - Run `tofu plan` against the staging workspace before suggesting an apply. - Treat `.cursor/rules/` files as cross-tool context, not Claude-specific. ``` `CLAUDE.local.md` is the per-user private overlay. Add it to `.gitignore`; do not commit it. ### GitHub Copilot GitHub Copilot reads `.github/copilot-instructions.md` for repo-wide chat instructions. The Copilot coding agent also reads `AGENTS.md` from the project root. Save as `.github/copilot-instructions.md`: ```markdown # Copilot instructions for Quake AI projects This repository targets Quake AI, an OpenStack-based public cloud. The full project conventions live in `AGENTS.md` at the project root. The platform invariants below are the most load-bearing. - Platform name: "Quake AI" (never just "Quake AI"). - IaC tool: OpenTofu, OpenStack provider. - Flavor naming: `{family}.{size}`; source names from `/docs/compute/concepts/flavors`. - Object storage: S3-compatible; endpoint is environment-specific. - Managed databases are not offered; deploy on compute. ``` For path-scoped rules, use `.github/instructions/*.instructions.md` with an `applyTo` frontmatter glob. ### Windsurf Windsurf reads workspace rules from `.windsurf/rules/*.md`. Each rule file uses a `trigger` frontmatter field. Auto-generated Memories live locally per machine and are not team-shared; the rules file is the team-shared anchor. Save as `.windsurf/rules/project-conventions.md`: ```markdown --- trigger: always_on --- See `AGENTS.md` at the project root for the full Quake AI invariants and code generation rules. The most load-bearing items: - Refer to the platform as "Quake AI" (not "Quake AI"). - Use OpenTofu with the `openstack` provider. Flavor names follow `{family}.{size}`. - Object storage is S3-compatible. The external network is `PublicStatic` or `PublicEphemeral`. - Managed databases are not offered. Deploy on compute. ``` The 12,000-character per-file limit applies. Use multiple files in `.windsurf/rules/` if your conventions exceed that. ### Zed Zed reads project rules from `.rules` at the project root. It also recognizes `AGENTS.md` as a compatibility alias. If both exist, Zed uses `.rules` and ignores the rest. The cleanest setup is a symlink so `.rules` and `AGENTS.md` cannot drift apart: ```bash ln -s AGENTS.md .rules ``` If your environment does not support symlinks (Windows without developer mode, some CI systems), copy `AGENTS.md` to `.rules` and add a pre-commit check that the two files match. MCP servers for Zed live in `~/.config/zed/settings.json` under the `context_servers` key; see the [MCP snippet section](/resources/ai-assisted-development/ai-assisted-development) for the Quake AI server config. ### OpenAI Codex CLI Codex CLI reads `AGENTS.md` from the project root with no adapter. Codex also walks the directory tree and concatenates nested `AGENTS.md` files, so deeper directories can refine the project-root rules. The `~/.codex/config.toml` file controls fallback filenames and the byte limit: ```toml project_doc_max_bytes = 65536 project_doc_fallback_filenames = ["TEAM_GUIDE.md", ".agents.md"] ``` The default `project_doc_max_bytes` is 32768. Bump it to 65536 if your AGENTS.md plus nested overrides exceed 32 KiB. ### Aider Aider does not have a native rules-file concept. Conventions are loaded as read-only context via the `read:` field in `.aider.conf.yml` (or `--read CONVENTIONS.md` on the command line). Save as `.aider.conf.yml` at the project root: ```yaml # Use a current Anthropic model slug; check the Anthropic model list. model: anthropic/claude-sonnet-4-6 auto-commits: false read: - AGENTS.md ``` Aider caches read-only files between turns, so the AGENTS.md content travels with every request without re-uploading. Native MCP support is tracked in the upstream issue [Aider-AI/aider#4506](https://github.com/Aider-AI/aider/issues/4506); use the same `read:` pattern for context until that ships. ### Continue Continue reads rules from the `rules:` array in `~/.continue/config.yaml`. The legacy `~/.continue/config.json` format is deprecated; use YAML. Add the rules inline: ```yaml name: Quake AI Dev version: 1.0.0 schema: v1 rules: - Platform name is "Quake AI" (not "Quake AI"). - Primary IaC tool is OpenTofu with the OpenStack provider. - Flavor names follow `{family}.{size}`; source from /docs/compute/concepts/flavors. - Object storage is S3-compatible; endpoint is environment-specific. - External network is PublicStatic or PublicEphemeral (the literal name `public` is invalid). - Managed databases are not offered; deploy on compute. ``` Or reference an external file: ```yaml name: Quake AI Dev version: 1.0.0 schema: v1 rules: - uses: file://AGENTS.md ``` Continue does not auto-discover root-level markdown files, so the explicit `rules:` entry is required for AGENTS.md to load. ## Stability of these conventions Tool conventions move at different speeds. Treat the table below as a snapshot from 24.05.2026 and re-check the source documentation before adopting a new pattern. | Convention | Status | Notes | |---|---|---| | MCP as cross-tool transport | Stable | Native support in Cursor, Claude Code, Claude Desktop, GitHub Copilot (VS Code), Continue, Windsurf, and Zed | | `mcpServers` JSON object shape | Stable | Originated with Claude Desktop; used by Cursor, Claude Code, Windsurf | | AGENTS.md as cross-tool instructions | Experimental | Emerging standard; supported by Codex CLI, GitHub Copilot coding agent, Windsurf, Zed (alias), Cursor (alternative), Aider (via `read:`) | | `.cursor/rules/*.mdc` folder format | Stable | Cursor's current format | | `.cursorrules` flat file | Deprecated | Cursor will remove. Migrate to `.cursor/rules/` or AGENTS.md. | | `CLAUDE.md` and `CLAUDE.local.md` | Stable | Anthropic's documented convention | | Continue `config.yaml` | Stable | `config.json` is deprecated; use YAML | | VS Code `servers` key (vs `mcpServers`) | Stable but divergent | GA since VS Code 1.102 (14.07.2025) | | Zed `context_servers` key | Stable but divergent | Zed's own key name for MCP servers in `settings.json` | | Continue `mcpServers` (YAML array) | Stable but divergent | Same key name as Cursor / Claude, but array shape rather than object | The divergent keys (`servers` for VS Code, `context_servers` for Zed, the YAML array shape for Continue) are not going away. A snippet library that targets multiple tools ships a variant for each. ## Conventions to skip Three patterns are widely discussed but not worth shipping today. **Cody Free and Cody Pro are discontinued.** Sourcegraph discontinued these on 23.07.2025. The successor for individual and team use is [Amp](https://ampcode.com). Cody Enterprise is unchanged and serves large organizations. Any Quake AI guidance referencing Cody should scope to Cody Enterprise or Amp. **Aider native MCP is not available.** Aider lacks native MCP support and the upstream issue [Aider-AI/aider#4506](https://github.com/Aider-AI/aider/issues/4506) has no ship date. Community wrappers (`mcpm-aider`, `AiderDesk`) exist as proxy layers. The supported integration path today is `read: [AGENTS.md]` in `.aider.conf.yml`, as shown in the Aider adapter above. **Windsurf auto-generated Memories do not travel with the team.** Windsurf's Memories are machine-local and not shared. The team-sharing path is `.windsurf/rules/*.md` (version-controlled) or `AGENTS.md`. Treat Memories as a local convenience, not a shared convention. ## Pair with the MCP server The rules file gives the assistant the platform invariants. The [Quake AI MCP server](/resources/ai-assisted-development/ai-assisted-development) gives the assistant live retrieval against the current documentation and infrastructure templates. Use both: the rules cover "always do X"; the MCP covers "for this specific task, here is the current page or template." The `/resources/ai-assisted-development/ai-assisted-development` page ships MCP install snippets for Cursor, Claude Desktop, VS Code (GitHub Copilot), Claude Code, Continue, and Zed, plus notes on the integration paths for Codex CLI and Aider. ## See also - [Connect AI tools to Quake AI docs](/resources/ai-assisted-development/ai-assisted-development): MCP server install snippets and file-based documentation surfaces. - [Compute flavor reference](/docs/compute/concepts/flavors): the canonical flavor list referenced by the rules. - [Automation templates](/resources/iac-templates): [validated IaC templates](/docs/platform/validation#how-infrastructure-templates-are-checked) an assistant can use as scaffolding.