# AGENTS.md - StarRocks

Agent entrypoint for this repository. Start with the nearest nested `AGENTS.md`; use this file for repo-wide rules only.

## Read Order

1. Read [`handbook/index.md`](./handbook/index.md) for repo topology, architecture entrypoints, and active engineering plans. If `handbook/plans/local/index.md` exists, treat it as a checkout-local extension to the tracked plan set after reading [`handbook/plans/index.md`](./handbook/plans/index.md).
2. Read the nearest nested `AGENTS.md`.
3. For Backend work, read [`handbook/domains/backend.md`](./handbook/domains/backend.md) and [`be/AGENTS.md`](./be/AGENTS.md).
4. For Frontend work, read [`handbook/domains/frontend.md`](./handbook/domains/frontend.md) and [`fe/AGENTS.md`](./fe/AGENTS.md).
5. For SQL tests, docs, generated code, Java extensions, or CI/tooling, read the matching `handbook/domains/` page before the nested guide.

## Repo Map

- `be/`: C++ backend for execution, storage, services, and data processing.
- `fe/`: Java frontend for parsing, planning, metadata, and coordination.
- `gensrc/`: generated thrift/protobuf code.
- `test/`: SQL integration tests.
- `docs/`: user and admin documentation.
- `java-extensions/`: JNI and external source integrations.

## Quick Commands

```bash
# Build backend or frontend
./build.sh --be
./build.sh --fe

# Run backend or frontend unit tests
./run-be-ut.sh
./run-fe-ut.sh

# Run SQL integration tests
cd test && python3 run.py -v
```

## Repo-Wide Invariants

- Do not hand-edit generated outputs in `gensrc/` unless the generator workflow explicitly requires it.
- Protobuf fields must stay optional/repeated; never add `required` and never reuse ordinals.
- Thrift fields must stay optional/repeated; never add `required` and never reuse ordinals.
- User-facing config or metric changes must update the matching docs in `docs/en/` and `docs/zh/` when applicable.
- When editing any file under `docs/`, read `docs/CLAUDE.md` for documentation-specific rules before making changes.

## Observability Awareness

Before generating or modifying production code for a feature, bug fix, or performance optimization, review the existing observability of the affected end-to-end path. Follow the [Observability Awareness policy](./handbook/policies/observability-awareness.md) and the matching domain guide before deciding whether existing signals must be preserved or extended.

In the final change summary or PR description, state which existing signals were reviewed, what was preserved or extended, or why no observability change was needed.

## PR Contract

- Commit messages: English, imperative, concise.
- PR titles: `[BugFix] ...`, `[Feature] ...`, `[Enhancement] ...`, `[Refactor] ...`, `[UT] ...`, `[Doc] ...`, or `[Tool] ...`.
- Fill the repository PR template completely, including behavior-change classification and test/docs checkboxes.
- Bug-fix PRs intended for branch backports must set the version checkboxes that drive auto-backporting.
- When editing any file under `docs/`, read `docs/CLAUDE.md` for documentation-specific rules before making changes.

## Codex PR Review Context

When performing a PR review (including `@codex review`), first inspect the PR
comments for one beginning with `<!-- module-risk-briefing -->`.

If a current briefing exists, treat it as review focus, not a finding list:
- check the listed modules/files first;
- validate every risk against the actual diff before reporting;
- do not report a finding solely because the briefing cites a historical risk;
- if the embedded `<!-- module-risk-head-sha: X -->` differs from the PR's
  current head commit, the briefing predates the latest push: use it only as
  historical reference, NOT as the primary review focus for the current diff,
  and flag this in the review summary;
- if the briefing is stale or absent, say so briefly — never silently drop the
  historical risks, and never report one as a current finding without checking
  the diff.

## Nested Guides

- [`handbook/index.md`](./handbook/index.md)
- [`handbook/domains/index.md`](./handbook/domains/index.md)
- [`handbook/policies/index.md`](./handbook/policies/index.md)
- [`handbook/quality/index.md`](./handbook/quality/index.md)
- [`be/AGENTS.md`](./be/AGENTS.md)
- [`fe/AGENTS.md`](./fe/AGENTS.md)
- [`docs/AGENTS.md`](./docs/AGENTS.md)
- [`gensrc/AGENTS.md`](./gensrc/AGENTS.md)
- [`java-extensions/AGENTS.md`](./java-extensions/AGENTS.md)
- [`test/AGENTS.md`](./test/AGENTS.md)