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 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:

# 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.

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:

---
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:

# 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:

# 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:

---
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:

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 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:

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:

# 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; 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:

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:

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.

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. 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 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 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: MCP server install snippets and file-based documentation surfaces.
• Compute flavor reference: the canonical flavor list referenced by the rules.
• Automation templates: validated IaC templates an assistant can use as scaffolding.