replace old .cursorrules with AGENTS.md (#4451)

* chore: remove .cursorrules file
feat: add AGENTS.md file to any newly created file

* move the copy of the tests

docs/docs.json

@@ -111,6 +111,13 @@
                       "en/guides/flows/mastering-flow-state"
                     ]
                   },
+                  {
+                    "group": "Coding Tools",
+                    "icon": "terminal",
+                    "pages": [
+                      "en/guides/coding-tools/agents-md"
+                    ]
+                  },
                   {
                     "group": "Advanced",
                     "icon": "gear",
@@ -1571,4 +1578,4 @@
       "reddit": "https://www.reddit.com/r/crewAIInc/"
     }
   }
-}
+}

docs/en/guides/coding-tools/agents-md.mdx

@@ -0,0 +1,61 @@
+---
+title: Coding Tools
+description: Use AGENTS.md to guide coding agents and IDEs across your CrewAI projects.
+icon: terminal
+mode: "wide"
+---
+
+## Why AGENTS.md
+
+`AGENTS.md` is a lightweight, repo-local instruction file that gives coding agents consistent, project-specific guidance. Keep it in the project root and treat it as the source of truth for how you want assistants to work: conventions, commands, architecture notes, and guardrails.
+
+## Create a Project with the CLI
+
+Use the CrewAI CLI to scaffold a project, then `AGENTS.md` will be automatically added at the root.
+
+```bash
+# Crew
+crewai create crew my_crew
+
+# Flow
+crewai create flow my_flow
+
+# Tool repository
+crewai tool create my_tool
+```
+
+## Tool Setup: Point Assistants to AGENTS.md
+
+### Codex
+
+Codex can be guided by `AGENTS.md` files placed in your repository. Use them to supply persistent project context such as conventions, commands, and workflow expectations.
+
+### Claude Code
+
+Claude Code stores project memory in `CLAUDE.md`. You can bootstrap it with `/init` and edit it using `/memory`. Claude Code also supports imports inside `CLAUDE.md`, so you can add a single line like `@AGENTS.md` to pull in the shared instructions without duplicating them.
+
+You can simply use:
+
+```bash
+mv AGENTS.md CLAUDE.md
+```
+
+### Gemini CLI and Google Antigravity
+
+Gemini CLI and Antigravity load a project context file (default: `GEMINI.md`) from the repo root and parent directories. You can configure it to read `AGENTS.md` instead (or in addition) by setting `context.fileName` in your Gemini CLI settings. For example, set it to `AGENTS.md` only, or include both `AGENTS.md` and `GEMINI.md` if you want to keep each tool’s format.
+
+You can simply use:
+
+```bash
+mv AGENTS.md GEMINI.md
+```
+
+### Cursor
+
+Cursor supports `AGENTS.md` as a project instruction file. Place it at the project root to provide guidance for Cursor’s coding assistant.
+
+### Windsurf
+
+Claude Code provides an official integration with Windsurf. If you use Claude Code inside Windsurf, follow the Claude Code guidance above and import `AGENTS.md` from `CLAUDE.md`.
+
+If you are using Windsurf’s native assistant, configure its project rules or instructions feature (if available) to read from `AGENTS.md` or paste the contents directly.

lib/crewai/src/crewai/cli/create_crew.py

@@ -143,6 +143,12 @@ def create_folder_structure(
         (folder_path / "src" / folder_name).mkdir(parents=True)
         (folder_path / "src" / folder_name / "tools").mkdir(parents=True)
         (folder_path / "src" / folder_name / "config").mkdir(parents=True)
+        
+        # Copy AGENTS.md to project root (top-level projects only)
+        package_dir = Path(__file__).parent
+        agents_md_src = package_dir / "templates" / "AGENTS.md"
+        if agents_md_src.exists():
+            shutil.copy2(agents_md_src, folder_path / "AGENTS.md")
 
     return folder_path, folder_name, class_name
 

lib/crewai/src/crewai/cli/create_flow.py

@@ -1,3 +1,4 @@
+import shutil
 from pathlib import Path
 
 import click
@@ -34,6 +35,11 @@ def create_flow(name):
     package_dir = Path(__file__).parent
     templates_dir = package_dir / "templates" / "flow"
 
+    # Copy AGENTS.md to project root
+    agents_md_src = package_dir / "templates" / "AGENTS.md"
+    if agents_md_src.exists():
+        shutil.copy2(agents_md_src, project_root / "AGENTS.md")
+
     # List of template files to copy
     root_template_files = [".gitignore", "pyproject.toml", "README.md"]
     src_template_files = ["__init__.py", "main.py"]

lib/crewai/src/crewai/cli/tools/main.py

@@ -2,6 +2,7 @@ import base64
 from json import JSONDecodeError
 import os
 from pathlib import Path
+import shutil
 import subprocess
 import tempfile
 from typing import Any
@@ -55,6 +56,11 @@ class ToolCommand(BaseCommand, PlusAPIMixin):
         tree_find_and_replace(project_root, "{{folder_name}}", folder_name)
         tree_find_and_replace(project_root, "{{class_name}}", class_name)
 
+        # Copy AGENTS.md to project root
+        agents_md_src = Path(__file__).parent.parent / "templates" / "AGENTS.md"
+        if agents_md_src.exists():
+            shutil.copy2(agents_md_src, project_root / "AGENTS.md")
+
         old_directory = os.getcwd()
         os.chdir(project_root)
         try: