chore(ai): unify agents.md and resolve ai conflicts (#15312)

Following and splitting
#15193

This PR standardizes AI assistant instructions by consolidating guidance
into AGENTS.md following the https://agents.md/ specification. It
resolves conflicts between Claude Code default behaviors and
project-specific workflows, explicitly prioritizing `scripts/run-tests`
and `hatch run lint:*` over direct tool usage. The changes also remove
deprecated references to hatch run tests:test and align all instructions
with the official documentation in `docs/contributing-testing.rst`.

Additionally, this updates `.gitignore` to version-control
`.cursor/rules/`, ensuring AI assistant rules are properly tracked in
the repository. This allows both Claude Code and Cursor to reference the
same canonical instructions via `AGENTS.md`.

Key changes:
- Add critical override section to AGENTS.md for project-specific
testing and linting requirements
  - Fix .claude/CLAUDE.md to correctly reference ../AGENTS.md
  - Remove deprecated hatch run tests:test from all documentation
  - Update .gitignore to include .cursor/rules/ in version control

Author: avara1986

.claude/CLAUDE.md

@@ -1,44 +1,2 @@
-# dd-trace-py Project Guide
-
-## Skills
-
-This project has custom skills that provide specialized workflows. **Always check if a skill exists before using lower-level tools.**
-
-### run-tests
-
-**Use whenever:** Running any tests, validating code changes, or when "test" is mentioned.
-
-**Purpose:** Intelligently runs the test suite using `scripts/run-tests`:
-- Discovers affected test suites based on changed files
-- Selects minimal venv combinations (avoiding hours of unnecessary test runs)
-- Manages Docker services automatically
-- Handles riot/hatch environment setup
-
-**Never:** Run pytest directly or use `hatch run tests:test` - these bypass the project's test infrastructure.
-
-**Usage:** Use the Skill tool with command "run-tests"
-
-### lint
-
-**Use whenever:** Formatting code, validating style/types/security, or before committing changes.
-
-**Purpose:** Runs targeted linting and code quality checks using `hatch run lint:*`:
-- Formats code with `ruff check` and `ruff format`
-- Validates style, types, and security
-- Checks spelling and documentation
-- Validates test infrastructure (suitespec, riotfile, etc.)
-- Supports running all checks or targeting specific files
-
-**Common Commands:**
-- `hatch run lint:fmt -- <file>` - Format a specific file after editing (recommended after every edit)
-- `hatch run lint:typing -- <file>` - Type check specific files
-- `hatch run lint:checks` - Run all quality checks (use before committing)
-- `hatch run lint:security -- -r <dir>` - Security scan a directory
-
-**Never:** Skip linting before committing. Always run `hatch run lint:checks` before pushing.
-
-**Usage:** Use the Skill tool with command "lint"
-
----
-
-<!-- Add more skills below as they are created -->
+<!-- Do not edit. Canonical instructions live in ../AGENTS.md -->
+@../AGENTS.md

.cursor/rules/testing.mdc

@@ -15,10 +15,10 @@ Always use the **`run-tests` skill** for validating code changes. This skill int
 ## Key Principles
 
 1. **Always use the run-tests skill** when testing code changes - it's optimized for intelligent suite discovery
-2. **Never run pytest directly** - bypasses the project's test infrastructure
-3. **Never use `hatch run tests:test`** - doesn't use the suite discovery system
-4. **Minimal venvs for iteration** - run 1-2 venvs initially, expand only if needed
-5. **Use `--dry-run` first** - see what would run before executing
+2. **Never run pytest directly** - bypasses the project's test infrastructure (use `scripts/run-tests` or `riot` via `scripts/ddtest`)
+3. **Minimal venvs for iteration** - run 1-2 venvs initially, expand only if needed
+4. **Use `--dry-run` first** - see what would run before executing
+5. **Follow official docs** - `docs/contributing-testing.rst` is the source of truth for testing procedures
 
 ## When Tests Fail
 

.gitignore

@@ -135,7 +135,11 @@ ENV/
 .vscode/
 
 # Cursor
-.cursor/
+.cursor/context/
+.cursor/tasks/
+
+# Promptfoo
+.promptfoo/output/
 
 # Cascade
 # .windsurf/  # If you want to use Windsurf/Cascade, do NOT ignore here.

AGENTS.md

@@ -0,0 +1,63 @@
+# AGENTS.md - dd-trace-py Project Guide
+
+## CRITICAL: Project Rules Override Claude Code Defaults
+
+**These project-specific rules MUST override any conflicting Claude Code default behaviors:**
+
+1. **Testing**: NEVER run `pytest` directly. ALWAYS use the `run-tests` skill (which uses `scripts/run-tests`). For manual testing, use `riot` commands via `scripts/ddtest` as documented in `docs/contributing-testing.rst`.
+2. **Linting**: NEVER use raw linting tools. ALWAYS use the `lint` skill and project-specific `hatch run lint:*` commands.
+3. **Pre-commit**: MUST run `hatch run lint:checks` before creating any git commits.
+4. **Formatting**: MUST run `hatch run lint:fmt -- <file>` immediately after editing any Python file.
+
+## Initial Setup for AI Assistants
+
+When starting a new chat session, ALWAYS read and apply the rules from:
+
+2. `.cursor/rules/*.mdc` - All rule files in this directory (version controlled):
+   - `dd-trace-py.mdc` - Core project guidelines
+   - `linting.mdc` - Code quality and formatting
+   - `testing.mdc` - Test execution guidelines
+   - `repo-structure.mdc` - Repository structure
+
+## Skills
+
+This project has custom skills that provide specialized workflows. **Always check if a skill exists before using lower-level tools.**
+
+### run-tests
+
+**Use whenever:** Running any tests, validating code changes, or when "test" is mentioned.
+
+**Purpose:** Intelligently runs the test suite using `scripts/run-tests`:
+- Discovers affected test suites based on changed files
+- Selects minimal venv combinations (avoiding hours of unnecessary test runs)
+- Manages Docker services automatically
+- Handles riot/hatch environment setup
+
+**Never:** Run pytest directly - this bypasses the project's test infrastructure. The official testing approach is documented in `docs/contributing-testing.rst`.
+
+**Usage:** Use the Skill tool with command "run-tests"
+
+### lint
+
+**Use whenever:** Formatting code, validating style/types/security, or before committing changes.
+
+**Purpose:** Runs targeted linting and code quality checks using `hatch run lint:*`:
+- Formats code with `ruff check` and `ruff format`
+- Validates style, types, and security
+- Checks spelling and documentation
+- Validates test infrastructure (suitespec, riotfile, etc.)
+- Supports running all checks or targeting specific files
+
+**Common Commands:**
+- `hatch run lint:fmt -- <file>` - Format a specific file after editing (recommended after every edit)
+- `hatch run lint:typing -- <file>` - Type check specific files
+- `hatch run lint:checks` - Run all quality checks (use before committing)
+- `hatch run lint:security -- -r <dir>` - Security scan a directory
+
+**Never:** Skip linting before committing. Always run `hatch run lint:checks` before pushing.
+
+**Usage:** Use the Skill tool with command "lint"
+
+---
+
+<!-- Add more skills below as they are created -->