milvus/CLAUDE.md

Milvus

Vector database. Go + C++ (internal/core/) + Rust (tantivy). pkg has its own go.mod (module: github.com/milvus-io/milvus/pkg/v3). Run go get from pkg/ when adding dependencies there, not from root.

Architecture

Coordinators manage metadata and scheduling; nodes execute work.

• Coordinators: rootcoord, datacoord, querycoordv2 (note the v2 suffix in directory names)
• Nodes: proxy (user-facing), querynodev2, datanode, streamingnode
• All component interfaces defined in internal/types/types.go

Subsystems & Code Map

Each subsystem has a top-level doc (overview with links to sub-documents) and multiple sub-documents (detailed design, invariants, interfaces). The top-level doc alone is NOT sufficient — it is an index, not the content.

Mandatory reading procedure

When your task modifies, explains, depends on, or affects a subsystem below, execute these steps IN ORDER before responding or writing code:

Step 1 — Read the top-level doc. Identify all sub-documents it links to.

Step 2 — Read sub-documents. The scope depends on task type:

• Design tasks (new feature, architecture change, cross-component change): Read every sub-document under the subsystem. No exceptions — design requires full-picture understanding. Do NOT judge relevance yourself; read all of them.
• Targeted tasks (bug fix, single-component change, code explanation): Read sub-documents that cover the components your task touches. When uncertain whether a sub-document is relevant, read it.

Step 3 — Read source code listed in each doc's "Key Packages" section. At minimum read the files directly related to your task.

Step 4 — Cross-check documentation against code. If they contradict, STOP and ask the user to resolve before proceeding.

NEVER answer based on documentation alone or code alone. NEVER skip Step 2 — this is the most common failure mode.

Subsystems Reference

• Streaming System: Write path, WAL, DDL/DCL execution, replication && CDC.

Testing

Go tests MUST use -tags dynamic,test and -gcflags="all=-N -l" (disable optimizations/inlining) or they won't compile / mockey-based monkey patching will fail:

go test -tags dynamic,test -gcflags="all=-N -l" -count=1 ./internal/querycoordv2/...
go test -tags dynamic,test -gcflags="all=-N -l" -count=1 ./internal/proxy/... -run TestXxx

Per-module shortcuts: make test-querycoord, make test-proxy, etc.

Run Milvus Locally

scripts/start_standalone.sh    # start standalone mode
scripts/start_cluster.sh       # start cluster mode
scripts/stop_graceful.sh       # stop
scripts/standalone_embed.sh    # embedded standalone (no external deps)

Code Conventions

• Error handling: use merr package, not fmt.Errorf
• Logging: use pkg/v2/log, not standard "log" or fmt.Println
• Import order: standard → third-party → github.com/milvus-io (enforced by gci)
• Config params: paramtable (pkg/v2/util/paramtable), config in configs/milvus.yaml

PR and Commit Conventions

PR title format: {type}: {description}. Valid types: feat:, fix:, enhance:, test:, doc:, auto:, build(deps):. PR body must be non-empty. Issue/doc linking rules:

• fix: — must link issue (e.g. issue: #123)
• feat: — must link issue + design doc under docs/design-docs
• Every Milvus feature should have a related design doc under docs/design-docs; submit the doc in this repository and link it from the Milvus feature PR.
• enhance: — must link issue if size L/XL/XXL
• doc:, test: — no issue required
• 2.x branch PRs must link the corresponding master PR (e.g. pr: #123)

DCO check is required. Always use -s so the developer's Signed-off-by is appended last:

git commit -s -m "commit message

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>"

-s auto-appends Signed-off-by: <developer> at the end. The developer MUST be the final sign-off, not the AI.

Generated Files — Do Not Hand-Edit

• Mock files (internal/mocks/*, mock_*.go): regenerate with make generate-mockery-{module}
• Proto files (pkg/proto/*.pb.go): regenerate with make generated-proto-without-cpp