You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@iotdb.apache.org by ha...@apache.org on 2026/10/21 08:03:26 UTC
(iotdb) branch master updated: [Docs] Consolidate repository agent instructions in AGENTS.md (#18952)
This is an automated email from the ASF dual-hosted git repository.
HTHou pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/iotdb.git
The following commit(s) were added to refs/heads/master by this push:
new 36e1a13e558 [Docs] Consolidate repository agent instructions in AGENTS.md (#18952)
36e1a13e558 is described below
commit 36e1a13e5584312a4062a28334f3be0b66c46e2b
Author: Jackie Tien <ja...@gmail.com>
AuthorDate: Wed Oct 21 16:03:19 2026 +0800
[Docs] Consolidate repository agent instructions in AGENTS.md (#18952)
---
AGENTS.md | 180 +++++++++++++++++++++++++++++++++++++++++++++++++++++++-
CLAUDE.md | 178 -------------------------------------------------------
CONTRIBUTING.md | 21 +++++++
THREAT_MODEL.md | 4 +-
pom.xml | 1 -
5 files changed, 202 insertions(+), 182 deletions(-)
diff --git a/AGENTS.md b/AGENTS.md
deleted file mode 120000
index 681311eb9cf..00000000000
--- a/AGENTS.md
+++ /dev/null
@@ -1 +0,0 @@
-CLAUDE.md
\ No newline at end of file
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 00000000000..cb1d54cae57
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,179 @@
+<!--
+
+ 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.
+
+-->
+
+# AGENTS.md
+
+This file provides repository-wide guidance for coding agents working on Apache IoTDB.
+For setup and compatibility notes, see [Coding agents](CONTRIBUTING.md#coding-agents).
+
+## Project Overview
+
+Apache IoTDB is a time series database for IoT data. It uses a distributed architecture with ConfigNodes (metadata/coordination) and DataNodes (storage/query). Data is stored in TsFile columnar format (separate repo: https://github.com/apache/tsfile). Current version is 2.0.11-SNAPSHOT.
+
+## Build Commands
+
+```bash
+# Full build (skip tests)
+mvn clean package -pl distribution -am -DskipTests
+
+# Build a specific module (e.g., datanode)
+mvn clean package -pl iotdb-core/datanode -am -DskipTests
+
+# Run unit tests for a specific module
+mvn clean test -pl iotdb-core/datanode
+
+# Run a single test class
+mvn clean test -pl iotdb-core/datanode -Dtest=ClassName
+
+# Run a single test method
+mvn clean test -pl iotdb-core/datanode -Dtest=ClassName#methodName
+
+# Build with Chinese log & error messages
+mvn clean package -pl distribution -am -DskipTests -P with-zh-locale
+
+# Format code (requires JDK 17+; auto-skipped on JDK <17)
+mvn spotless:apply
+
+# Check formatting without applying
+mvn spotless:check
+```
+
+## Integration Tests
+
+Before editing or running integration tests, read and follow
+[integration-test/AGENTS.md](integration-test/AGENTS.md). It contains the IT authoring rules,
+formatting and build commands, test profiles, targeted verification, and Edge/IDE instructions.
+Keep IT-specific rules and commands in that module-level file.
+
+## Code Style
+
+- **Apache License header**: Every new file committed to the repository MUST include the Apache License 2.0 header. Use the comment syntax appropriate for the file type (e.g., `<!-- -->` for `.md`, `/* */` for `.java`, `#` for `.properties`/`.py`). JSON files are exempt (no comment syntax). Refer to existing files in the repo for the exact format.
+- **Spotless** with Google Java Format (GOOGLE style). Import order: `org.apache.iotdb`, blank, `javax`, `java`, static.
+- **Checkstyle** is also configured (see `checkstyle.xml` at project root).
+- Java source/target level is 17 (compiled with `maven.compiler.release=17` on JDK 17+).
+
+## Architecture
+
+### Node Types
+
+- **ConfigNode** (`iotdb-core/confignode`): Manages cluster metadata, schema regions, data regions, partition tables. Coordinates via Ratis consensus.
+- **DataNode** (`iotdb-core/datanode`): Handles data storage, query execution, and client connections. The main server component.
+- **AINode** (`iotdb-core/ainode`): Python-based node for AI/ML inference tasks.
+
+### Edge Distribution
+
+- `EdgeNode` (`iotdb-core/confignode/src/main/java/org/apache/iotdb/edge/EdgeNode.java`) starts the ConfigNode and DataNode in one JVM for resource-constrained single-node deployments.
+- `distribution/src/assembly/edge.xml` produces the additional `apache-iotdb-<version>-edge-bin.zip` artifact. Keep its `edge-bin` assembly id unique so it cannot replace an existing attached artifact.
+- Edge-specific system defaults live under `iotdb-core/node-commons/src/assembly/resources/conf/edge/`. Standard node, all-in-one, and integration-test assemblies must continue to exclude `edge/**`.
+- Edge launchers must reuse the configuration-aware port checks in `scripts/conf/iotdb-common.sh`. Stop scripts must match both the `EdgeNode` main class and the exact `IOTDB_HOME`; never fall back to a global process-name kill.
+- Package node-independent tools that work with the combined process. Exclude scripts that require standalone node launchers or environment files, including destructive, daemon-management, and health-check scripts.
+- After packaging changes, run a clean distribution build, check that every existing distribution artifact is still produced, and inspect the Edge zip contents and startup/shutdown behavior.
+
+### Dual Data Model
+
+IoTDB supports two data models operating on the same storage:
+- **Tree model**: Traditional IoT hierarchy (e.g., `root.ln.wf01.wt01.temperature`). SQL uses path-based addressing.
+- **Table model** (relational): SQL table semantics. Grammar lives in `iotdb-core/relational-grammar/`. Query plan code under `queryengine/plan/relational/`.
+
+### Key DataNode Subsystems (`iotdb-core/datanode`)
+
+- **queryengine**: SQL parsing, planning, optimization, and execution.
+ - `plan/parser/` - ANTLR-based SQL parser
+ - `plan/statement/` - AST statement nodes
+ - `plan/planner/` - Logical and physical planning (tree model: `TreeModelPlanner`, table model: under `plan/relational/`)
+ - `plan/optimization/` - Query optimization rules
+ - `execution/operator/` - Physical operators (volcano-style iterator model)
+ - `execution/exchange/` - Inter-node data exchange
+ - `execution/fragment/` - Distributed query fragment management
+- **storageengine**: Write path, memtable, flush, WAL, compaction, TsFile management.
+ - `dataregion/` - DataRegion lifecycle, memtable, flush, compaction
+ - `dataregion/wal/` - Write-ahead log
+ - `buffer/` - Memory buffer management
+- **schemaengine**: Schema (timeseries metadata) management.
+- **pipe**: Data sync/replication framework (source -> processor -> sink pipeline).
+- **consensus**: DataNode-side consensus integration.
+- **subscription**: Client subscription service for streaming data changes.
+
+### Consensus (`iotdb-core/consensus`)
+
+Pluggable consensus protocols: Simple (single-node), Ratis (Raft-based), IoT Consensus (optimized for IoT writes). Factory pattern via `ConsensusFactory`.
+
+### Protocol Layer (`iotdb-protocol/`)
+
+Thrift IDL definitions for RPC between nodes. Generated sources are produced automatically during build. Sub-modules: `thrift-commons`, `thrift-confignode`, `thrift-datanode`, `thrift-consensus`, `thrift-ainode`.
+
+### Client Libraries (`iotdb-client/`)
+
+- `session/` - Java Session API (primary client interface)
+- `jdbc/` - JDBC driver
+- `cli/` - Command-line client
+- `client-cpp/`, `client-go/`, `client-py/` - Multi-language clients
+- `service-rpc/` - Shared Thrift service definitions
+
+### API Layer (`iotdb-api/`)
+
+Extension point interfaces: `udf-api` (user-defined functions), `trigger-api` (event triggers), `pipe-api` (data sync plugins), `external-api`, `external-service-api`.
+
+## IDE Setup
+
+After `mvn package`, right-click the root project in IntelliJ and choose "Maven -> Reload Project" to add generated source roots (Thrift and ANTLR).
+
+Generated source directories that need to be on the source path:
+- `**/target/generated-sources/thrift`
+- `**/target/generated-sources/antlr4`
+
+## Common Pitfalls
+
+### Build
+
+- **Missing Thrift compiler**: The local machine may not have the `thrift` binary installed. Running `mvn clean package -pl <module> -am -DskipTests` will fail at the `iotdb-thrift` module. **Workaround**: To verify your changes compile, use `mvn compile -pl <module>` (without `-am` or `clean`) to leverage existing target caches.
+- **Pre-existing compilation errors in unrelated modules**: The datanode module may have pre-existing compile errors in other subsystems (e.g., pipe, copyto) that cause `mvn clean test -pl iotdb-core/datanode -Dtest=XxxTest` to fail during compilation. **Workaround**: First run `mvn compile -pl iotdb-core/datanode` to confirm your changed files compile successfully. If the errors are in files you did not modify, they are pre-existing and do not affect your changes.
+- **Single-module / no-`clean` compiles hide cross-module and i18n errors**: `mvn compile -pl <module>` (the thrift workaround above) builds only that module against the **installed** jars in `~/.m2` and the existing `target/` classes; an incremental `mvn test-compile` without `clean` reuses stale `target/*.class`. If you add/rename a `*Messages` constant (or any cross-module API) in module B but `~/.m2`/`target/` still holds B's old artifact, module A referencing the new symbol compiles [...]
+
+### i18n (Chinese Messages)
+
+The project uses compile-time i18n via the `build-helper-maven-plugin`. The property `i18n.locale` (default: `en`) controls which source directory is added: `src/main/i18n/${i18n.locale}`. Activating `-P with-zh-locale` sets `i18n.locale=zh`, swapping English message constant classes for Chinese ones. Each module that participates has both `src/main/i18n/en/` and `src/main/i18n/zh/` directories containing Java classes with identical structure but different string literals.
+
+**Rule — never inline a user-facing English string literal.** Every string a user, operator, or log reader will see MUST be a `public static final String` constant in the module's `*Messages` class (e.g. `DataNodeQueryMessages`), referenced as `MessagesClass.CONSTANT` — never a `"raw literal"`. This applies to: `LOGGER/log.info|warn|error|debug|trace(...)`, `throw new …Exception(…)`, `super(…)` in exception constructors, `resp.setMessage(…)`, the message arg of `requireNonNull/checkArgum [...]
+
+**Naming a new constant** (deterministic, matches existing files): `<PREFIX>_<NORMALIZED>_<HASH>` where `PREFIX` is `LOG_` for `LOGGER`/log calls, `MESSAGE_` for `setMessage(...)`, and `EXCEPTION_` for `throw new …(…)`, `super(…)`, and the message arg of `requireNonNull/checkArgument/checkState/checkNotNull` (the three prefixes the codebase already uses — ~`LOG_`/`MESSAGE_`/`EXCEPTION_`); `NORMALIZED` is the English value uppercased with non-alphanumeric runs collapsed to `_` and `%s`/`% [...]
+
+**Verify before commit**:
+- `mvn spotless:apply -pl <module>` (the PostToolUse formatter does not add the i18n import; spotless does).
+- Compile **both** locales: `mvn test-compile -DskipTests` AND `mvn test-compile -P with-zh-locale -DskipTests` (the `.github/workflows/zh-locale-compile.yml` CI enforces the zh build).
+- The `en` and `zh` files must stay in key parity (same constant names) with identical format-specifier counts; a raw-literal scan of main java must return nothing.
+
+### Code Style
+
+- **Always run `mvn spotless:apply` after editing Java files**: Spotless runs `spotless:check` automatically during the `compile` phase. Format violations cause an immediate BUILD FAILURE. Make it a habit to run `mvn spotless:apply -pl <module>` right after editing, not at the end.
+- **Always run `black` and `isort` after editing Python files under `iotdb-core/ainode/`**: The AINode Code Style Check CI runs `black --check .` and `isort --check-only --profile black .` on that directory. Run `cd iotdb-core/ainode && black . && isort --profile black .` before committing. Requires `pip install black==25.1.0 isort==6.0.1`.
+- **Gson version compatibility**: `JsonObject.isEmpty()` / `JsonArray.isEmpty()` may not be available in the Gson version used by this project. Use `size() > 0` instead and add a comment explaining why.
+
+## Git Commit
+
+- Do NOT add `Co-Authored-By` trailer to commit messages.
+
+## Security
+
+Security model: [SECURITY.md](./SECURITY.md)
+
+Agents that scan this repository should consult `SECURITY.md` and the
+threat model it links before reporting issues.
diff --git a/CLAUDE.md b/CLAUDE.md
deleted file mode 100644
index 5ef345696db..00000000000
--- a/CLAUDE.md
+++ /dev/null
@@ -1,178 +0,0 @@
-<!--
-
- 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.
-
--->
-
-# CLAUDE.md
-
-This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
-
-## Project Overview
-
-Apache IoTDB is a time series database for IoT data. It uses a distributed architecture with ConfigNodes (metadata/coordination) and DataNodes (storage/query). Data is stored in TsFile columnar format (separate repo: https://github.com/apache/tsfile). Current version is 2.0.11-SNAPSHOT.
-
-## Build Commands
-
-```bash
-# Full build (skip tests)
-mvn clean package -pl distribution -am -DskipTests
-
-# Build a specific module (e.g., datanode)
-mvn clean package -pl iotdb-core/datanode -am -DskipTests
-
-# Run unit tests for a specific module
-mvn clean test -pl iotdb-core/datanode
-
-# Run a single test class
-mvn clean test -pl iotdb-core/datanode -Dtest=ClassName
-
-# Run a single test method
-mvn clean test -pl iotdb-core/datanode -Dtest=ClassName#methodName
-
-# Build with Chinese log & error messages
-mvn clean package -pl distribution -am -DskipTests -P with-zh-locale
-
-# Format code (requires JDK 17+; auto-skipped on JDK <17)
-mvn spotless:apply
-
-# Check formatting without applying
-mvn spotless:check
-```
-
-## Integration Tests
-
-Before editing or running integration tests, read and follow
-[integration-test/AGENTS.md](integration-test/AGENTS.md). It contains the IT authoring rules,
-formatting and build commands, test profiles, targeted verification, and Edge/IDE instructions.
-Keep IT-specific rules and commands in that module-level file.
-
-## Code Style
-
-- **Apache License header**: Every new file committed to the repository MUST include the Apache License 2.0 header. Use the comment syntax appropriate for the file type (e.g., `<!-- -->` for `.md`, `/* */` for `.java`, `#` for `.properties`/`.py`). JSON files are exempt (no comment syntax). Refer to existing files in the repo for the exact format.
-- **Spotless** with Google Java Format (GOOGLE style). Import order: `org.apache.iotdb`, blank, `javax`, `java`, static.
-- **Checkstyle** is also configured (see `checkstyle.xml` at project root).
-- Java source/target level is 17 (compiled with `maven.compiler.release=17` on JDK 17+).
-
-## Architecture
-
-### Node Types
-
-- **ConfigNode** (`iotdb-core/confignode`): Manages cluster metadata, schema regions, data regions, partition tables. Coordinates via Ratis consensus.
-- **DataNode** (`iotdb-core/datanode`): Handles data storage, query execution, and client connections. The main server component.
-- **AINode** (`iotdb-core/ainode`): Python-based node for AI/ML inference tasks.
-
-### Edge Distribution
-
-- `EdgeNode` (`iotdb-core/confignode/src/main/java/org/apache/iotdb/edge/EdgeNode.java`) starts the ConfigNode and DataNode in one JVM for resource-constrained single-node deployments.
-- `distribution/src/assembly/edge.xml` produces the additional `apache-iotdb-<version>-edge-bin.zip` artifact. Keep its `edge-bin` assembly id unique so it cannot replace an existing attached artifact.
-- Edge-specific system defaults live under `iotdb-core/node-commons/src/assembly/resources/conf/edge/`. Standard node, all-in-one, and integration-test assemblies must continue to exclude `edge/**`.
-- Edge launchers must reuse the configuration-aware port checks in `scripts/conf/iotdb-common.sh`. Stop scripts must match both the `EdgeNode` main class and the exact `IOTDB_HOME`; never fall back to a global process-name kill.
-- Package node-independent tools that work with the combined process. Exclude scripts that require standalone node launchers or environment files, including destructive, daemon-management, and health-check scripts.
-- After packaging changes, run a clean distribution build, check that every existing distribution artifact is still produced, and inspect the Edge zip contents and startup/shutdown behavior.
-
-### Dual Data Model
-
-IoTDB supports two data models operating on the same storage:
-- **Tree model**: Traditional IoT hierarchy (e.g., `root.ln.wf01.wt01.temperature`). SQL uses path-based addressing.
-- **Table model** (relational): SQL table semantics. Grammar lives in `iotdb-core/relational-grammar/`. Query plan code under `queryengine/plan/relational/`.
-
-### Key DataNode Subsystems (`iotdb-core/datanode`)
-
-- **queryengine**: SQL parsing, planning, optimization, and execution.
- - `plan/parser/` - ANTLR-based SQL parser
- - `plan/statement/` - AST statement nodes
- - `plan/planner/` - Logical and physical planning (tree model: `TreeModelPlanner`, table model: under `plan/relational/`)
- - `plan/optimization/` - Query optimization rules
- - `execution/operator/` - Physical operators (volcano-style iterator model)
- - `execution/exchange/` - Inter-node data exchange
- - `execution/fragment/` - Distributed query fragment management
-- **storageengine**: Write path, memtable, flush, WAL, compaction, TsFile management.
- - `dataregion/` - DataRegion lifecycle, memtable, flush, compaction
- - `dataregion/wal/` - Write-ahead log
- - `buffer/` - Memory buffer management
-- **schemaengine**: Schema (timeseries metadata) management.
-- **pipe**: Data sync/replication framework (source -> processor -> sink pipeline).
-- **consensus**: DataNode-side consensus integration.
-- **subscription**: Client subscription service for streaming data changes.
-
-### Consensus (`iotdb-core/consensus`)
-
-Pluggable consensus protocols: Simple (single-node), Ratis (Raft-based), IoT Consensus (optimized for IoT writes). Factory pattern via `ConsensusFactory`.
-
-### Protocol Layer (`iotdb-protocol/`)
-
-Thrift IDL definitions for RPC between nodes. Generated sources are produced automatically during build. Sub-modules: `thrift-commons`, `thrift-confignode`, `thrift-datanode`, `thrift-consensus`, `thrift-ainode`.
-
-### Client Libraries (`iotdb-client/`)
-
-- `session/` - Java Session API (primary client interface)
-- `jdbc/` - JDBC driver
-- `cli/` - Command-line client
-- `client-cpp/`, `client-go/`, `client-py/` - Multi-language clients
-- `service-rpc/` - Shared Thrift service definitions
-
-### API Layer (`iotdb-api/`)
-
-Extension point interfaces: `udf-api` (user-defined functions), `trigger-api` (event triggers), `pipe-api` (data sync plugins), `external-api`, `external-service-api`.
-
-## IDE Setup
-
-After `mvn package`, right-click the root project in IntelliJ and choose "Maven -> Reload Project" to add generated source roots (Thrift and ANTLR).
-
-Generated source directories that need to be on the source path:
-- `**/target/generated-sources/thrift`
-- `**/target/generated-sources/antlr4`
-
-## Common Pitfalls
-
-### Build
-
-- **Missing Thrift compiler**: The local machine may not have the `thrift` binary installed. Running `mvn clean package -pl <module> -am -DskipTests` will fail at the `iotdb-thrift` module. **Workaround**: To verify your changes compile, use `mvn compile -pl <module>` (without `-am` or `clean`) to leverage existing target caches.
-- **Pre-existing compilation errors in unrelated modules**: The datanode module may have pre-existing compile errors in other subsystems (e.g., pipe, copyto) that cause `mvn clean test -pl iotdb-core/datanode -Dtest=XxxTest` to fail during compilation. **Workaround**: First run `mvn compile -pl iotdb-core/datanode` to confirm your changed files compile successfully. If the errors are in files you did not modify, they are pre-existing and do not affect your changes.
-- **Single-module / no-`clean` compiles hide cross-module and i18n errors**: `mvn compile -pl <module>` (the thrift workaround above) builds only that module against the **installed** jars in `~/.m2` and the existing `target/` classes; an incremental `mvn test-compile` without `clean` reuses stale `target/*.class`. If you add/rename a `*Messages` constant (or any cross-module API) in module B but `~/.m2`/`target/` still holds B's old artifact, module A referencing the new symbol compiles [...]
-
-### i18n (Chinese Messages)
-
-The project uses compile-time i18n via the `build-helper-maven-plugin`. The property `i18n.locale` (default: `en`) controls which source directory is added: `src/main/i18n/${i18n.locale}`. Activating `-P with-zh-locale` sets `i18n.locale=zh`, swapping English message constant classes for Chinese ones. Each module that participates has both `src/main/i18n/en/` and `src/main/i18n/zh/` directories containing Java classes with identical structure but different string literals.
-
-**Rule — never inline a user-facing English string literal.** Every string a user, operator, or log reader will see MUST be a `public static final String` constant in the module's `*Messages` class (e.g. `DataNodeQueryMessages`), referenced as `MessagesClass.CONSTANT` — never a `"raw literal"`. This applies to: `LOGGER/log.info|warn|error|debug|trace(...)`, `throw new …Exception(…)`, `super(…)` in exception constructors, `resp.setMessage(…)`, the message arg of `requireNonNull/checkArgum [...]
-
-**Naming a new constant** (deterministic, matches existing files): `<PREFIX>_<NORMALIZED>_<HASH>` where `PREFIX` is `LOG_` for `LOGGER`/log calls, `MESSAGE_` for `setMessage(...)`, and `EXCEPTION_` for `throw new …(…)`, `super(…)`, and the message arg of `requireNonNull/checkArgument/checkState/checkNotNull` (the three prefixes the codebase already uses — ~`LOG_`/`MESSAGE_`/`EXCEPTION_`); `NORMALIZED` is the English value uppercased with non-alphanumeric runs collapsed to `_` and `%s`/`% [...]
-
-**Verify before commit**:
-- `mvn spotless:apply -pl <module>` (the PostToolUse formatter does not add the i18n import; spotless does).
-- Compile **both** locales: `mvn test-compile -DskipTests` AND `mvn test-compile -P with-zh-locale -DskipTests` (the `.github/workflows/zh-locale-compile.yml` CI enforces the zh build).
-- The `en` and `zh` files must stay in key parity (same constant names) with identical format-specifier counts; a raw-literal scan of main java must return nothing.
-
-### Code Style
-
-- **Always run `mvn spotless:apply` after editing Java files**: Spotless runs `spotless:check` automatically during the `compile` phase. Format violations cause an immediate BUILD FAILURE. Make it a habit to run `mvn spotless:apply -pl <module>` right after editing, not at the end.
-- **Always run `black` and `isort` after editing Python files under `iotdb-core/ainode/`**: The AINode Code Style Check CI runs `black --check .` and `isort --check-only --profile black .` on that directory. Run `cd iotdb-core/ainode && black . && isort --profile black .` before committing. Requires `pip install black==25.1.0 isort==6.0.1`.
-- **Gson version compatibility**: `JsonObject.isEmpty()` / `JsonArray.isEmpty()` may not be available in the Gson version used by this project. Use `size() > 0` instead and add a comment explaining why.
-
-## Git Commit
-
-- Do NOT add `Co-Authored-By` trailer to commit messages.
-
-## Security
-
-Security model: [SECURITY.md](./SECURITY.md)
-
-Agents that scan this repository should consult `SECURITY.md` and the
-threat model it links before reporting issues.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 7a5191cad6e..c369a96f2be 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -79,6 +79,27 @@ Precautions:
* Do not use special Unicode chars, e.g., U+FF1A
* Do not use the character of dollar (as we will use Latex to generate pdf files)
+## Coding agents
+
+[AGENTS.md](AGENTS.md) is the shared entry point for repository-wide build, testing, and coding
+instructions. Follow any module-level `AGENTS.md` as well, including
+[integration-test/AGENTS.md](integration-test/AGENTS.md) when working on integration tests.
+Maintain shared guidance in these files.
+
+For Claude Code contributors:
+
+* Upgrade to a current release. Direct `AGENTS.md` support was introduced in v2.1.277;
+ v2.1.281 or later is needed for some sessions, including Amazon Bedrock or sessions with
+ telemetry disabled.
+* By default, a `CLAUDE.md`, `.claude/CLAUDE.md`, or `CLAUDE.local.md` in the working directory
+ or an ancestor directory takes precedence over `AGENTS.md`. To load both, open `/config`
+ and set **Project instructions** to `claude-md-and-agents-md`.
+* Start a new session after upgrading and check that the repository's `AGENTS.md` appears in
+ `/memory` (available for directly loaded `AGENTS.md` files since v2.1.280).
+
+See the [Claude Code loading and configuration rules](https://code.claude.com/docs/en/memory#agentsmd)
+for details.
+
## Code Formatting
We use the [Spotless
diff --git a/THREAT_MODEL.md b/THREAT_MODEL.md
index 4191f5e07d8..eaf4a7d1b9a 100644
--- a/THREAT_MODEL.md
+++ b/THREAT_MODEL.md
@@ -24,12 +24,12 @@ limitations under the License.
- **Reporting cross-reference:** findings that violate a §8 property should be reported privately per the ASF process (`security@apache.org` → `private@iotdb.apache.org`); findings that fall under §3 or §9 will be closed citing this document.
- **Provenance legend:** *(documented)* = stated in IoTDB's own docs/repo; *(maintainer)* = confirmed by an IoTDB PMC member through this process; *(inferred)* = reasoned from architecture/domain knowledge, not yet confirmed. The high-stakes inferred claims were routed to §14 and have since been resolved across two PMC review passes; the residual *(inferred)* tags are low-stakes environmental details the PMC can confirm or correct at leisure.
- **Draft confidence:** a v0 that has had **two PMC review passes**. First pass (HTHou, issue-comment review 2026-06-03): deployment posture, default-credential disposition, default-enabled protocols (REST/MQTT off; client Thrift SSL off), extension-privilege model, and the resource/DoS line. Second pass (JackieTien97, PR review 2026-06-04): the previously-open items — TsFile/SDK boundary, inter-node posture (trusted-network; no transport encryption), inter-node TLS (none today), cluster [...]
-- **What IoTDB is:** Apache IoTDB is a time-series database management system for IoT data — collection, storage, query, and analysis. It runs as a server (standalone, or a distributed cluster of ConfigNodes for metadata/coordination and DataNodes for storage/query), stores data in the TsFile columnar format, and is accessed over a Thrift-based RPC protocol via a SQL-like language and JDBC/session clients. *(documented — README, repo `CLAUDE.md`)*
+- **What IoTDB is:** Apache IoTDB is a time-series database management system for IoT data — collection, storage, query, and analysis. It runs as a server (standalone, or a distributed cluster of ConfigNodes for metadata/coordination and DataNodes for storage/query), stores data in the TsFile columnar format, and is accessed over a Thrift-based RPC protocol via a SQL-like language and JDBC/session clients. *(documented — README, repo `AGENTS.md`)*
## §2 Scope and intended use
- **Primary use:** an operator-deployed time-series database server, written to by IoT/device data pipelines and read by analytics clients, over the network. IoTDB should generally be treated as operator-deployed infrastructure, deployed inside a **trusted network by default**, with the application/ingestion tier in front of it. *(maintainer — HTHou: "IoTDB should generally be treated as operator-deployed infrastructure … trusted-network-by-default")*
-- **Deployment shapes:** standalone single-node, and a distributed cluster (ConfigNode + DataNode roles, optional AINode for model execution, inter-node/control-plane RPC, and consensus). *(documented — repo `CLAUDE.md`)*
+- **Deployment shapes:** standalone single-node, and a distributed cluster (ConfigNode + DataNode roles, optional AINode for model execution, inter-node/control-plane RPC, and consensus). *(documented — repo `AGENTS.md`)*
- **Caller roles** (this is a network service, not an in-process library — the "caller" splits):
- **client** — connects over the Thrift session protocol / JDBC / SQL; authenticates with a username/password and is constrained by RBAC privileges. Treated as **untrusted** beyond its granted privileges. The authenticated client RPC surface is the main in-model boundary. *(maintainer — HTHou: "the client RPC surface as the main in-model boundary")*
- **operator/admin** — the `root` superuser and whoever controls the deployment, configs, and the host. **Trusted** for the instance. *(inferred)*
diff --git a/pom.xml b/pom.xml
index 65e622de726..c6bbd90cdda 100644
--- a/pom.xml
+++ b/pom.xml
@@ -706,7 +706,6 @@
<exclude>**/.gitmodules</exclude>
<exclude>**/.git-blame-ignore-revs</exclude>
<exclude>**/git.properties</exclude>
- <exclude>AGENTS.md</exclude>
<!-- Maven related files -->
<exclude>**/target/**</exclude>
<!-- Eclipse related files -->