be

Imported from gencau/test-practices-agent-configurations (dataset/repos/StarRocks§starrocks/be/AGENTS.md). Install upstream with npx skills add gencau/test-practices-agent-configurations --skill be. Copyright stays with the author.

AGENTS.md - StarRocks Backend

Backend operating contract for agentic work in be/.

Read This First

• Repo-wide topology and active engineering plans live in handbook/index.md.
• The backend domain map lives in handbook/domains/backend.md.
• The BE harness overview lives in handbook/architecture/be-boundary-harness.md.
• The BE module boundary source of truth is be/module_boundary_manifest.json.
• The harness is enforced by build-support/check_be_module_boundaries.py.
• The generated module section in this file is enforced by build-support/render_be_agents.py.
• Reviewed legacy violations are frozen in build-support/be_module_boundary_baseline.json. Only the deferred allocator-related entries should remain, and the baseline must only shrink.

Harness Commands

# Full BE architecture check
python3 build-support/check_be_module_boundaries.py --mode full

# PR-style changed-files check
python3 build-support/check_be_module_boundaries.py --mode changed --base origin/main

# PR-style check plus baseline shrink-only guard
python3 build-support/check_be_module_boundaries.py --mode changed --base origin/main --enforce-baseline-shrink

# Verify this file matches the manifest
python3 build-support/render_be_agents.py --check

# Rewrite the generated module section after manifest edits
python3 build-support/render_be_agents.py --write

Fast Loops

# Standard BE build
./build.sh --be

# Debug or ASAN build
BUILD_TYPE=Debug ./build.sh --be
BUILD_TYPE=ASAN ./build.sh --be

# Fast single-binary UT loop
./run-be-ut.sh --build-target <test_binary> --module <test_binary> --without-java-ext

Useful core binaries for fast iterations:

• base_test
• io_test
• fs_core_test
• types_test
• column_test
• runtime_core_test
• expr_core_test

Core C++ Rules

• Format with the repo .clang-format.
• Prefer #pragma once.
• Keep include order: corresponding header, C system, C++ stdlib, third-party, StarRocks.
• Use Status and StatusOr for recoverable errors.
• Treat hot-path allocations and row-by-row virtual dispatch as performance smells.

Architecture Workflow

• If you change BE layering rules, edit be/module_boundary_manifest.json first.
• After manifest changes, run python3 build-support/render_be_agents.py --write.
• Before finishing BE work, run python3 build-support/check_be_module_boundaries.py --mode full.
• If the check fails on a pre-existing edge, confirm it is already listed in build-support/be_module_boundary_baseline.json.
• If the check fails on a new edge, fix the code or update the manifest. Do not add to the baseline unless the debt is deliberate and reviewed.
• If you touch the baseline file, run the changed-files check with --enforce-baseline-shrink; fixed entries should be deleted, never rewritten into new debt.

Module Harness

This section is generated from be/module_boundary_manifest.json. Run python3 build-support/render_be_agents.py --write after changing the manifest. Run python3 build-support/check_be_module_boundaries.py --mode full to validate the same rules mechanically.

Base (base)

Lowest-level BE primitives. Keep it free of higher-level StarRocks module dependencies.

• Targets: Base
• Allowed internal include prefixes: base/, gutil/, gen_cpp/
• Allowed target deps: Gutil
• Core tests: base_test
• Remediation: Move shared helpers into Base/Gutil or introduce a lower-level interface instead of pulling in higher-level BE modules.

Gutil (gutil)

Standalone utility substrate. Do not couple it to BE modules.

• Targets: Gutil
• Allowed internal include prefixes: gutil/
• Remediation: Keep Gutil independent; move BE-specific logic out instead of importing BE modules.

Common (common)

Core shared infrastructure above Base/Gutil only. Higher-level BE modules must not leak back into it.

• Targets: Common
• Allowed internal include prefixes: common/, base/, gutil/, gen_cpp/
• Allowed target deps: Base, Gutil
• Core tests: common_test
• Remediation: Move the dependency upward or add a lower-level abstraction; Common may only depend on Base, Gutil, and generated headers.

IOCore (iocore)

Minimal IO foundation used by upper IO/FS layers.

• Targets: IOCore
• Allowed internal include prefixes: io/core/, common/, base/, gutil/, gen_cpp/
• Allowed target deps: Common, Base, Gutil
• Core tests: io_test
• Remediation: Keep IOCore free of higher IO/FS/runtime/storage code; lift the dependency into IO or FileSystem instead.

FSCore (fscore)

Minimal filesystem core on top of IOCore.

• Targets: FSCore
• Allowed internal include prefixes: fs/, io/core/, common/, base/, gutil/, gen_cpp/
• Allowed target deps: IOCore, Common, Base, Gutil
• Core tests: fs_core_test
• Remediation: Keep FSCore limited to IOCore plus core FS abstractions; move backend-specific behavior into FileSystem.

TypesCore (typecore)

Core type system without runtime/storage/exec coupling.

• Targets: TypesCore
• Allowed internal include prefixes: types/, common/, base/, gutil/, gen_cpp/
• Allowed target deps: Common, Base, Gutil
• Core tests: types_test
• Remediation: Keep TypesCore independent of runtime/util/storage/exec layers; move integration code into higher layers.

ColumnCore (columncore)

Core column representations that must stay independent of ChunkCore and higher layers.

• Targets: ColumnCore
• Allowed internal include prefixes: column/, types/, common/, base/, gutil/, gen_cpp/
• Allowed target deps: TypesCore, Common, Base, Gutil, StarRocksGen
• Core tests: column_test
• Remediation: Keep ColumnCore free of ChunkCore/Runtime/Exec/Storage coupling; move integration code upward or introduce an interface.

RuntimeCore (runtimecore)

Core runtime building blocks without full Runtime/Exec/Storage coupling.

• Targets: RuntimeCore
• Allowed internal include prefixes: runtime/, column/, types/, common/, base/, gutil/, gen_cpp/
• Allowed target deps: ChunkCore, ColumnCore, TypesCore, Common, Base, Gutil, StarRocksGen
• Core tests: runtime_core_test
• Remediation: Keep RuntimeCore restricted to core runtime infrastructure; move service/storage/stream-load/integration code into Runtime.

ExprCore (exprcore)

Core expression infrastructure that depends only on RuntimeCore and lower layers.

• Targets: ExprCore
• Allowed internal include prefixes: exprs/, runtime/, column/, types/, common/, base/, gutil/, gen_cpp/
• Allowed target deps: RuntimeCore, ChunkCore, ColumnCore, TypesCore, Common, Base, Gutil, StarRocksGen
• Core tests: expr_core_test
• Remediation: Keep ExprCore limited to core expression infrastructure; move aggregate/UDF/integration code into Exprs.

BE-Specific Sync Rules

• BE configs are declared in be/src/common/config.h; update docs/en/administration/management/BE_configuration.md and docs/zh/ peer docs when config behavior changes.
• BE metrics must update the matching monitoring docs when names, meanings, or labels change.
• be/src/common has extra config-header rules in be/src/common/AGENTS.md.

Verification Before Handoff

Run the smallest relevant UT binary plus the architecture harness:

python3 build-support/check_be_module_boundaries.py --mode full
python3 build-support/render_be_agents.py --check

If you changed a core module, prefer its focused test binary before broader run-be-ut.sh.