diff --git a/.gitignore b/.gitignore
index 4cd336b0e9c..1f46243b3a3 100644
--- a/.gitignore
+++ b/.gitignore
@@ -66,9 +66,9 @@ greptimedb_data
 !/.github
 
 # AI related
-# Root-level personal/local agent config only; per-crate AGENTS.md files are tracked.
-/CLAUDE.md
-/AGENTS.md
+# Root AGENTS.md is the shared project guide (tracked); CLAUDE.md symlinks to it.
+# Personal/local agent config goes under .local/ and stays untracked.
+/.local/
 .codex
 .gemini
 .opencode
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 00000000000..ce25569aff1
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,91 @@
+# AGENTS.md
+
+Guidance for coding agents (Claude Code, Codex, ...) and contributors working in
+this repository. `CLAUDE.md` is a symlink to this file. If `.local/AGENTS.md` or
+`.local/CLAUDE.md` is present, you **MUST** read it as well — it holds personal
+or machine-local overrides (gitignored, not shared). To record a personal or
+machine-local override, write it to `.local/AGENTS.md` (create `.local/` and the
+file if absent), not to this shared file.
+
+GreptimeDB is an open-source, cloud-native observability database for unified
+collection and analysis of metrics, logs, and traces. It is written in Rust and
+provides sub-second querying at PB scale with high cost efficiency.
+
+## Core commands
+
+| Task | Command |
+| --- | --- |
+| Build (debug) | `make build` |
+| Build (release) | `make build RELEASE=true` |
+| Run standalone | `cargo run -- standalone start` |
+| Test | `cargo nextest run` (preferred over `cargo test`) |
+| SQL tests | `cargo sqlness bare` (single case: `cargo sqlness bare -t <name>`) |
+| Format | `make fmt` (and `make fmt-toml` for TOML) |
+| Lint | `make clippy` (= `cargo clippy --workspace --all-targets --all-features -- -D warnings`) |
+| Type check | `make check` |
+
+Toolchain: Rust nightly, Protobuf compiler (>= 3.15), C/C++ build essentials.
+Install the test runner with `cargo install cargo-nextest --locked`.
+
+## Repo map
+
+GreptimeDB is a Cargo workspace rooted at the repository; most crates live under
+`src/` (plus `tests-fuzz`, `tests-integration`, `tests/runner`). Key areas:
+
+- **Frontend / protocol**: `src/frontend/` (request orchestration), `src/servers/`
+  (wire protocols), `src/sql/` (SQL parsing)
+- **Storage engines**: `src/mito2/` (main time-series engine), `src/metric-engine/`
+  (metrics), `src/file-engine/`
+- **Coordination**: `src/meta-srv/` (metadata & cluster control), `src/meta-client/`
+- **Execution / statements**: `src/operator/` (DDL/DML, request conversion, procedures)
+- **Stream / transform**: `src/flow/` (continuous aggregation), `src/pipeline/`
+- **Query / index**: `src/query/`, `src/promql/`, `src/index/`
+- **Shared**: `src/common/`, `src/datatypes/`, `src/store-api/` (engine contract),
+  `src/catalog/`, `src/table/`
+
+Hot crates carry their own `AGENTS.md` with a module map, read/write paths,
+change-coupling points, and gotchas:
+
+- [`src/mito2/AGENTS.md`](src/mito2/AGENTS.md)
+- [`src/metric-engine/AGENTS.md`](src/metric-engine/AGENTS.md)
+- [`src/flow/AGENTS.md`](src/flow/AGENTS.md)
+- [`src/frontend/AGENTS.md`](src/frontend/AGENTS.md)
+- [`src/meta-srv/AGENTS.md`](src/meta-srv/AGENTS.md)
+
+## Read before changing code
+
+- [`.agents/architecture-invariants.md`](.agents/architecture-invariants.md) —
+  repo-wide rules that are easy to violate and expensive to get wrong (persisted/
+  wire format compatibility, crate layering, async runtimes, error handling,
+  feature gating, the DataFusion fork).
+- [`.agents/generated-files.md`](.agents/generated-files.md) — tool-generated
+  artifacts that must not be hand-edited (sqlness `.result`, `config/config.md`,
+  Grafana dashboards, proto).
+- [`docs/style-guide.md`](docs/style-guide.md) — code style.
+- [`CONTRIBUTING.md`](CONTRIBUTING.md) — contribution flow and CLA.
+
+## High-signal entry points
+
+- Main binary: `src/cmd/src/bin/greptime.rs`
+- Configuration: `src/common/config/`, example TOMLs in `config/`
+- Error handling: `src/common/error/` (`ErrorExt`, `StatusCode`)
+- Protocol implementations: `src/servers/src/`
+
+## Before opening a PR
+
+1. `make fmt`
+2. `make clippy`
+3. `make test` (or `cargo nextest run`)
+4. `make check-udeps` (run `make fix-udeps` if it reports unused dependencies).
+5. If you changed sample config under `config/`, run `make config-docs` (needs
+   Docker) and commit the regenerated `config/config.md`.
+6. If you changed a persisted or wire format, add a compatibility test case (see
+   `.agents/architecture-invariants.md`).
+7. Use a conventional-commit title, sign off commits (`git commit -s`), and sign
+   the CLA.
+
+## More
+
+- Agent skills and resources: [`.agents/`](.agents/) (see [`.agents/README.md`](.agents/README.md))
+- Architecture decisions: [`docs/rfcs/`](docs/rfcs/)
+- How-to guides: [`docs/how-to/`](docs/how-to/)
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 120000
index 00000000000..47dc3e3d863
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1 @@
+AGENTS.md
\ No newline at end of file