From 7318476d72610dcfa30de8d17c25244d9bf3d762 Mon Sep 17 00:00:00 2001
From: maoling <maoling@apache.org>
Date: Sun, 12 Apr 2026 23:20:00 +0800
Subject: [PATCH] CASSANDRA-21301: add AGENTS.md and CLAUDE.md

---
 .build/build-rat.xml |  3 ++
 AGENTS.md            | 79 ++++++++++++++++++++++++++++++++++++++++++++
 CLAUDE.md            |  1 +
 3 files changed, 83 insertions(+)
 create mode 100644 AGENTS.md
 create mode 100644 CLAUDE.md

diff --git a/.build/build-rat.xml b/.build/build-rat.xml
index 65f79e2c24fc..502eb3e97bc9 100644
--- a/.build/build-rat.xml
+++ b/.build/build-rat.xml
@@ -88,6 +88,9 @@
                  <!-- legal files -->
                  <exclude NAME="NOTICE.txt"/>
                  <exclude NAME="LICENSE.txt"/>
+                 <!-- AI agent instruction files -->
+                 <exclude NAME="AGENTS.md"/>
+                 <exclude NAME="CLAUDE.md"/>
                  <!-- misc -->
                  <exclude NAME="**/*.patch"/>
                  <exclude NAME="**/*.diff"/>
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 000000000000..921901d80c1d
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,79 @@
+# Agent Instructions for Apache Cassandra
+
+> These instructions apply to all AI-assisted contributions to `apache/cassandra`.
+
+## Apache Cassandra
+Apache Cassandra is a NoSQL distributed database. This is the official Git repository
+
+## Environment
+
+- Java 11 (default) or 17.
+- Python 3 for `cqlsh` and dtests.
+- Apache Ant >= 1.10 for all builds. Do NOT attempt to use Maven, Gradle, or any other build tool. Cassandra uses Ant exclusively.
+- Do NOT attempt to install dependencies, you do not have Internet access
+
+## Build
+
+```bash
+ant build                # compile all classes (includes Accord submodule)
+ant jar                  # build the main JAR
+ant clean                # remove locally created artifacts
+ant realclean            # remove entire build directory and downloaded artifacts
+```
+
+Do NOT run `ant build` if you only need to verify a small change compiles.
+
+## Testing
+
+- Do NOT run the entire test suite(`ant test`). Run only the specific test(s) relevant to your change.
+
+    ```bash
+    # Run a single unit test class
+    ant testsome -Dtest.name=org.apache.cassandra.service.StorageServiceServerTest -Dtest.methods=testGetAllRangesEmpty
+    ```
+
+- When fixing a bug, first create a regression test that reproduces the failure, then implement the fix and verify.
+- Provide test(s) coverage for all new or modified code.
+
+## Linting and Code Checks
+
+```bash
+ant check                # runs checkstyle, RAT license check, and builds
+ant checkstyle           # checkstyle only
+```
+
+## Code Style
+Cassandra enforces style via Checkstyle (`ant checkstyle`). Key rules are included in `checkstyle.xml` file.
+General style:
+- 4-space indentation, no tabs.
+- Braces on a new line below control statements (Allman style).
+- Brace-less style for single-line control statements.
+- Match existing code style in the file you are editing.
+- All new files must include the Apache License 2.0 header.
+- Concise English documentation is required for complex classes and methods; trivial ones may not require them.
+
+## Git Workflow
+- Do NOT commit unless explicitly asked.
+- Commit messages should reference the JIRA issue. Disclose that AI assistance was used in the PR description.
+
+    ```
+    CASSANDRA-XXXXX: Brief description of the change
+    Author: Your Name <your.email@example.com>
+   
+    Co-authored-by: GitHub Copilot
+    Co-authored-by: Claude
+    Co-authored-by: gemini-code-assist
+    ```
+
+- Do NOT modify submodule references without understanding the implications. Submodule changes must be committed and pushed before the parent Cassandra commit.
+
+## Boundaries
+
+- 🚫 Never modify generated files in `src/gen-java/` — they are built from `src/antlr/` grammars.
+- 🚫 Never modify files in `lib/` — these are managed dependencies.
+- 🚫 Never commit secrets, credentials, or API keys.
+- 🚫 Never run the full test suite (`ant test`) — it takes hours. Run targeted tests only.
+- 🚫 Never bypass Checkstyle violations without a suppression comment explaining why.
+- 🚫 Never create summary or documentation files unless explicitly asked.
+- ⚠️ Ask before modifying the CQL grammar (`src/antlr/Cql.g`) — changes cascade widely.
+- ⚠️ Ask before modifying `modules/accord/` — it is a separate repository.
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 000000000000..eef4bd20cf97
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1 @@
+@AGENTS.md
\ No newline at end of file