This is an automated email from the ASF dual-hosted git repository.
abhishekrb pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/druid.git
The following commit(s) were added to refs/heads/master by this push:
new 664dd199cf1 Add AGENTS.md (#19084)
664dd199cf1 is described below
commit 664dd199cf1a95081d08089af3d9760b3603b332
Author: Abhishek Radhakrishnan <[email protected]>
AuthorDate: Mon Mar 9 18:01:31 2026 -0700
Add AGENTS.md (#19084)
Add AGENTS.md that AI tools like Claude and Cursor can leverage. The
general recommendation from these tools is to keep the markdown files
lightweight but collaborative, so most folks using these tools in the repo for
development or otherwise can use it right out of the box.
Use https://gist.github.com/gianm/031a578a75b4dc44f3e45661d86bcca9 as a base
and add some more instructions.
---
AGENTS.md | 85 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 85 insertions(+)
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 00000000000..355a07d797c
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,85 @@
+<!--
+ ~ Licensed to the Apache Software Foundation (ASF) under one
+ ~ or more contributor license agreements. See the NOTICE file
+ ~ distributed with this work for additional information
+ ~ regarding copyright ownership. The ASF licenses this file
+ ~ to you under the Apache License, Version 2.0 (the
+ ~ "License"); you may not use this file except in compliance
+ ~ with the License. You may obtain a copy of the License at
+ ~
+ ~ http://www.apache.org/licenses/LICENSE-2.0
+ ~
+ ~ Unless required by applicable law or agreed to in writing,
+ ~ software distributed under the License is distributed on an
+ ~ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ ~ KIND, either express or implied. See the License for the
+ ~ specific language governing permissions and limitations
+ ~ under the License.
+ -->
+
+
+# Apache Druid
+
+Real-time analytics database. Java, Maven, multi-module project.
+
+## Key Modules
+
+- `processing/`: Core query processing, aggregation, data structures
+- `server/`: Common server functionality, HTTP services
+- `sql/`: SQL planning (Calcite), SQL-to-native translation
+- `indexing-service/`: Task framework, ingestion coordination
+- `multi-stage-query/`: MSQ engine
+- `extensions-core/`: Core extensions (S3, Kafka, Kinesis, Parquet,
DataSketches, etc.)
+- `web-console/`: React/TypeScript management UI
+- `quidem-ut/`: SQL query testing framework
+
+## Code Style
+
+- Read `dev/style-conventions.md` for conventions.
+- Forbidden APIs: `codestyle/druid-forbidden-apis.txt`.
+- **Always use `final`** for fields and variables that are not reassigned.
+- End every file with a newline.
+- Don't format changes unnecessarily.
+
+## Running Tests
+
+Use these flags for faster tests: `-Pskip-static-checks
-Dweb.console.skip=true -T1C`
+
+**Single test method:**
+```
+mvn test -pl sql -am
-Dtest="org.apache.druid.sql.calcite.CalciteQueryTest#testFoo"
-Dsurefire.failIfNoSpecifiedTests=false -Pskip-static-checks
-Dweb.console.skip=true -T1C
+```
+
+**All tests in a package:**
+```
+mvn test -pl sql -am -Dtest="org.apache.druid.sql.**"
-Dsurefire.failIfNoSpecifiedTests=false -Pskip-static-checks
-Dweb.console.skip=true -T1C
+```
+
+**Quidem (.iq) tests:**
+
+To run `sql/src/test/quidem/org.apache.druid.quidem.SqlQuidemTest/numMerge.iq`:
+
+```
+mvn test -pl sql -am -Dtest="org.apache.druid.sql.calcite.SqlQuidemTest"
-Dquidem.filter=numMerge -Dsurefire.failIfNoSpecifiedTests=false
-Pskip-static-checks -Dweb.console.skip=true -T1C
+```
+
+To run
`quidem-ut/src/test/quidem/org.apache.druid.quidem.QTest/qaWin/basics_group_by.all.iq`:
+
+```
+mvn test -pl quidem-ut -am -Dtest="org.apache.druid.quidem.QTest"
-Dquidem.filter=qaWin/basics_group_by.all
-Dsurefire.failIfNoSpecifiedTests=false -Pskip-static-checks
-Dweb.console.skip=true -T1C
+```
+
+Always use `-Dquidem.filter` to avoid running the full suite. To run multiple
tests, use commas like
+`-Dquidem.filter=file1,file2,file3` or use wildcards like
`-Dquidem.filter=join*`. Include subdirectory names if
+present, such as `-Dquidem.filter=qaWin/**`.
+
+
+### Web Console Development
+
+- Refer to `web-console/README.md` for instructions on developing, linting,
and testing web console features.
+
+### Documentation
+
+- When updating Markdown tables in `docs/`, preserve the existing table
formatting.
+- Use backquotes for any code references. e.g., `serverPriorityToReplicas`,
`ioConfig`.
+- Run `npm run spellcheck` from the `website/` directory to verify doc updates
and update the `.spelling` file if needed.
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
