| Dimension | Shared | Only in A | Only in B | Overlap |
|---|---|---|---|---|
| Sections | 1 | 9 | 20 | 3% |
| Commands | 1 | 3 | 12 | 6% |
| Section tags | 4 | 0 | 3 | 57% |
What each file covers
Sections
1 shared · 9 only in A · 20 only in B- − Test Placement
- − Harness Helpers
- − Ports and Services
- − Running Tests
- − Build the TiDB server used by the harness when needed.
- − Run every Dumpling integration case.
- − Run one case.
- − Run one case with shell tracing.
- − Validation Notes
- + Purpose and Precedence
- + Non-negotiables
- + Agent Interaction Overrides (Repo-Local)
- + ExecPlans
- + Quick Decision Matrix
- + Skills
- + Pre-flight Checklist
- + Repository Map (Entry Points)
- + Notes
- + Build Flow
- + When `make bazel_prepare` is required
- + Conditional step: run only when required by this section or `.agents/skills/tidb-bazel-prepare-gate`.
- + Then continue with normal local build steps.
- + Task -> Validation Matrix
- + Testing Policy
- + Code Style Guide
- + Go and backend code
- + Tests and testdata
- + Docs and command snippets
- + Agent Output Contract
- AGENTS.md
Commands
1 shared · 3 only in A · 12 only in B- − make server
- − make dumpling_integration_test
- − git describe --tags
- + make bazel_bin
- + make gogenerate
- + go mod tidy
- + git fetch origin --prune
- + go.mod
- + go.sum
- + make lint
- + make bazel_lint_changed
- + make parser
- + make parser_yacc
- + make parser_fmt
- + make parser_unit_test
- make bazel_prepare
Section tags
4 shared · 0 only in A · 3 only in B- + lint-format
- + api
- + docs
- build
- test
- code-style
- agent-behaviour
Line diff
pingcap/tidb · dumpling/tests/AGENTS.md
@@ −1 @@
1# AGENTS.md
2
3This file adds path-specific guidance for Dumpling integration tests under
4`dumpling/tests/**`. The repository root `AGENTS.md` still applies.
5
6## Test Placement
7
8- Prefer extending the nearest existing case in `dumpling/tests/<case>/run.sh`
9 before adding a new case directory.
10- Keep new cases focused on one Dumpling behavior or workflow. Avoid broad
11 setup churn in shared cases unless the behavior under test needs it.
12- Use deterministic table data and exact assertions against generated files in
13 `$DUMPLING_OUTPUT_DIR`.
14- Set up and clean the database/table state needed by the test block itself.
15 Do not rely on state left by an earlier block in the same script.
16
17## Harness Helpers
18
19- Use `run_sql` for SQL setup and assertions against the source database.
20- Use `run_dumpling` for Dumpling invocations instead of calling `bin/dumpling`
21 directly, unless the test is specifically about the helper or command wrapper.
22- Use `file_should_exist` and `file_not_exist` for simple file presence checks.
23- Inspect dumped SQL or CSV output under `$DUMPLING_OUTPUT_DIR`; keep greps and
24 cuts narrow enough that the assertion proves the intended behavior.
25
26## Ports and Services
27
28- `DUMPLING_TEST_PORT=4000` targets the TiDB server started by the Dumpling test
29 harness. Use this for TiDB-specific features and TiDB version-gated behavior.
30- `DUMPLING_TEST_PORT=3306` targets the external MySQL service expected by the
31 harness. Use this only for MySQL compatibility coverage or existing cases that
32 intentionally compare MySQL behavior.
33- When a script switches ports, set `DUMPLING_TEST_PORT` explicitly before each
34 block that depends on a specific server. Do not assume the previous block left
35 the desired value.
36- If a test depends on TiDB version parsing, verify the local or CI
37 `bin/tidb-server` was built from a checkout with enough Git tag/history context
38 for `git describe --tags` to produce a semver-shaped release string. A
39 shallow or tagless checkout can make Dumpling detect TiDB as version `0.0.0`.
40
41## Running Tests
42
43Run commands from the repository root.
44
45```bash
46# Build the TiDB server used by the harness when needed.
47make server
48```
49
50```bash
51# Run every Dumpling integration case.
52make dumpling_integration_test
53```
54
55```bash
56# Run one case.
57CASE=basic make dumpling_integration_test
58```
59
60```bash
61# Run one case with shell tracing.
62VERBOSE=true CASE=basic make dumpling_integration_test
63```
64
65The `dumpling_integration_test` target checks these binaries before running:
66`bin/tidb-server`, `bin/minio`, `bin/mc`, `bin/tidb-lightning`, and
67`bin/sync_diff_inspector`. The required sync-diff binary path uses an underscore:
68`bin/sync_diff_inspector`.
69
70The full harness also expects the `mysql` client and a local MySQL-compatible
71server on `127.0.0.1:3306` for cases that target MySQL.
72
73## Validation Notes
74
75- For a small shell-only test change, run the changed case with
76 `CASE=<case> make dumpling_integration_test` when local prerequisites are
77 available.
78- If unrelated blocks in the same case require unavailable local services, a
79 focused TiDB-only reproduction may be useful while iterating, but report that
80 the official case target was not fully run.
81- `make bazel_prepare` is not required for changes limited to Dumpling shell
82 integration tests or this file. Re-check root `AGENTS.md` if Go files, Bazel
83 metadata, or module files are also changed.
84
pingcap/tidb · AGENTS.md
@@ +1 @@
1# AGENTS.md
2
3This file provides guidance to agents working in this repository.
4
5## Purpose and Precedence
6
7- MUST means required.
8- SHOULD means recommended unless there is a concrete reason to deviate.
9- MAY means optional.
10- Root `AGENTS.md` defines repository-wide defaults. If a deeper path later adds a more specific `AGENTS.md`, the deeper file SHOULD be treated as higher precedence for that subtree.
11
12## Non-negotiables
13
141. Correctness first. TiDB is a distributed SQL database; seemingly small changes can alter SQL semantics, consistency, or cluster behavior.
152. No speculative behavior. Do not invent APIs, defaults, protocol behavior, or test workflows.
163. Keep diffs minimal. Avoid unrelated refactors, broad renames, or formatting-only churn unless explicitly requested.
174. Leave verifiable evidence. Run targeted checks and report exact commands.
185. Respect generated code artifacts. Do not hand-edit generated code outputs; regenerate from source inputs.
19
20## Agent Interaction Overrides (Repo-Local)
21
22- For short non-code questions about definitions, acronyms, symbols, errors, or other potentially repository-specific terms, agents MUST search the active repository and read the closest authoritative local definition before answering, lead with the repository-specific meaning, and use general knowledge only when local evidence is absent or the user explicitly requests broader context.
23
24## ExecPlans
25
26When writing complex features or significant refactors, use an ExecPlan from design to implementation.
27
28- Definition and format: `PLANS.md` at repository root.
29- Requirement: keep the ExecPlan updated as a living document while implementation progresses.
30- Scope: use this for multi-step work where losing context would risk correctness or incomplete validation.
31
32## Quick Decision Matrix
33
34| Task | Required action |
35| --- | --- |
36| Added/moved/renamed/removed Go files, changed the import section of an existing Go file, added a new top-level Go test function matching `func TestXxx(t *testing.T)` in an existing `*_test.go` file, changed Bazel files, updated Bazel test targets, or changed `go.mod`/`go.sum` | MUST run `make bazel_prepare` and include resulting Bazel metadata changes in the PR (for example `BUILD.bazel`, `**/*.bazel`, and `**/*.bzl`). |
37| Running package unit tests | SHOULD run targeted tests and avoid full-package runs unless needed (see `docs/agents/testing-flow.md` -> `Unit tests`). |
38| Unit tests in a package that uses failpoints | MUST enable failpoints before tests and disable afterward (see `docs/agents/testing-flow.md` -> `Failpoint decision for unit tests`). |
39| Recording integration tests | MUST use the recording command in `docs/agents/testing-flow.md` -> `Integration tests` (not `-record`; `-record` is for unit-test suites that explicitly support it). |
40| RealTiKV tests | MUST start playground in background, run tests, then clean up playground/data (see `docs/agents/testing-flow.md` -> `RealTiKV tests`). |
41| Bug fix | MUST add a regression test and verify it fails before fix and passes after fix. |
42| Fmt-only PR | MUST NOT run costly `realtikvtest`; local compilation is enough. |
43| During local coding iterations (not claiming completion) | SHOULD use the `WIP` verification profile from `.agents/skills/tidb-verify-profile` to run only scoped checks. |
44| Claiming task completion / PR readiness | MUST use the `Ready` verification profile from `.agents/skills/tidb-verify-profile`; if there are code changes, this includes `make lint`. `Ready` is mandatory before making final-status claims such as "fixed", "done", "all tests pass", "ready for review", or "ready for PR". |
45| Creating or updating a GitHub issue | SHOULD use `.agents/skills/tidb-issue-metadata-guard` to preserve issue templates and label hygiene. |
46| Creating a PR or editing PR metadata | SHOULD use `.agents/skills/tidb-pr-metadata-guard` to preserve PR templates, title scope, and bot-parsed checklist sections. |
47| Before finishing | SHOULD self-review diff quality before finishing. |
48| Expensive optional sweeps (for example `make bazel_lint_changed`, broad package runs) | MUST run only when required by change scope, CI reproduction, or explicit user request. |
49
50### Skills
51
52- Repository-level skills are maintained under `.agents/skills` (relative to the repository root / current working directory).
53- Keep skill content and references together under each skill folder (for example: `.agents/skills/<skill>/SKILL.md` and `.agents/skills/<skill>/references/`).
54- `.github/skills` is kept only as a migration note path and should not be used as the primary location for new skill updates.
55- Policy belongs in `AGENTS.md`; detailed command playbooks SHOULD live in `docs/agents/*`, and skills SHOULD provide entrypoint workflows that reference those playbooks.
56- Operational testing/build skills are indexed in `.agents/skills/README.md` to avoid duplicated lists drifting in multiple docs.
57
58## Pre-flight Checklist
59
601. Restate the task goal and acceptance criteria.
612. Locate the owning subsystem and the closest existing tests (`Repository Map`, `Task -> Validation Matrix`). If the target package has `doc.go`, agents MUST read that package-level doc first before diving into implementation files.
623. Decide prerequisites before running tests/build (`docs/agents/testing-flow.md` -> `Failpoint decision for unit tests`; `AGENTS.md` -> `Build Flow` -> `When make bazel_prepare is required`).
634. Pick the smallest valid validation set and prepare final reporting items (`Agent Output Contract`).
645. If `AGENTS.md` or docs under `docs/agents/` changed, follow the checklist in `docs/agents/agents-review-guide.md` before finishing.
65
66## Repository Map (Entry Points)
67
68- Detailed subsystem path mapping and test surfaces live in `docs/agents/architecture-index.md` (source of truth).
69- Update policy: when module/path mapping changes, update `docs/agents/architecture-index.md` first; update this section only when top-level entry points change.
70- `/pkg/planner/`: planner and optimization entrypoint.
71- `/pkg/executor/`, `/pkg/expression/`: SQL execution and expression evaluation.
72- `/pkg/session/`, `/pkg/sessionctx/`: session lifecycle and runtime statement context.
73- `/pkg/ddl/`, `/pkg/infoschema/`, `/pkg/meta/`: schema and metadata management.
74- `/pkg/store/`, `/pkg/kv/`: storage and distributed query interfaces.
75- `/pkg/statistics/`: statistics and estimation behavior entrypoint.
76- `/pkg/parser/`: SQL grammar and AST.
77- `/tests/integrationtest/`, `/tests/realtikvtest/`: SQL integration and real TiKV test surfaces.
78- `/cmd/tidb-server/`: TiDB server entrypoint.
79
80## Notes
81
82- Follow `docs/agents/notes-guide.md`.
83- DDL module-only rules (applies to changes under `pkg/ddl/` and `docs/agents/ddl/`):
84 - MUST: Before making/reviewing any DDL changes in the DDL module, read `docs/agents/ddl/README.md` first and use it as the default map of the execution framework.
85 - Debugging: You MAY reference `docs/agents/ddl/*`, but you MUST NOT treat it as authoritative. Treat it as hypotheses until verified in code/tests (avoid hallucination/outdated assumptions).
86 - Doc drift: If implementation and `docs/agents/ddl/*` differ, you MUST update the docs to match reality and call it out in the PR/issue. Do not defer.
87
88## Build Flow
89
90### When `make bazel_prepare` is required
91
92Run `make bazel_prepare` before building when any of the following is true:
93
94- New workspace or fresh clone.
95- Bazel-related files changed (for example `WORKSPACE`, `DEPS.bzl`, `BUILD.bazel`, `MODULE.bazel`, `MODULE.bazel.lock`).
96- Any Go source file is added/removed/renamed/moved in the PR.
97- The import section changed in any existing Go source file (including `*_test.go`).
98- A code change adds a new top-level Go test function matching `func TestXxx(t *testing.T)` in an existing `*_test.go` file.
99- Go module dependencies changed (for example `go.mod`, `go.sum`), including adding third-party dependencies.
100- Bazel test targets were updated (for example `shard_count` changed, test `srcs` list edited, or `tests/realtikvtest/**/BUILD.bazel` modified).
101- Local Bazel dependency/toolchain errors occurred.
102
103For an operational decision checklist, use `.agents/skills/tidb-bazel-prepare-gate`.
104
105Recommended local build flow:
106
107```bash
108# Conditional step: run only when required by this section or `.agents/skills/tidb-bazel-prepare-gate`.
109make bazel_prepare
110```
111
112```bash
113# Then continue with normal local build steps.
114make bazel_bin
115make gogenerate # optional: regenerate generated code
116go mod tidy # optional: if go.mod/go.sum changed
117git fetch origin --prune
118```
119
120`make bazel_lint_changed` is intentionally excluded from the default local flow because it can be slow and resource-intensive on local macOS environments. Agents MUST NOT run `make bazel_lint_changed` unless the user explicitly requests it.
121
122## Task -> Validation Matrix
123
124Use the smallest set that still proves correctness.
125Command details for package, integration-test, and RealTiKV surfaces live in `docs/agents/testing-flow.md`.
126
127| Change scope | Minimum validation |
128| --- | --- |
129| `pkg/planner/**` rules or logical/physical plans | Targeted planner unit tests and update rule testdata when needed |
130| `pkg/executor/**` SQL behavior | Targeted unit test plus relevant integration test (`tests/integrationtest`) |
131| `pkg/expression/**` builtins or type inference | Targeted expression unit tests with edge-case coverage |
132| `pkg/session/**` / variables / protocol behavior | Targeted package tests plus SQL integration tests for user-visible behavior |
133| `pkg/ddl/**` schema changes | DDL-focused unit/integration tests and compatibility impact checks |
134| `pkg/store/**` / `pkg/kv/**` storage behavior | Targeted unit tests; use realtikv tests if behavior depends on real TiKV |
135| Parser files (`pkg/parser/**`) | Parser-specific Make targets (`make parser`, `make parser_yacc`, `make parser_fmt`, `make parser_unit_test`) and related unit tests |
136| `tests/integrationtest/t/**` changed | Record and verify regenerated result correctness (see `docs/agents/testing-flow.md` -> `Integration tests`) |
137| `tests/realtikvtest/**` changed | Start playground, run scoped tests, then mandatory cleanup (see `docs/agents/testing-flow.md` -> `RealTiKV tests`) |
138
139## Testing Policy
140
141- Detailed command playbooks live in `docs/agents/testing-flow.md`.
142- Select required test surfaces first (`Task -> Validation Matrix`), then run scoped commands from the playbook.
143- Use `.agents/skills/tidb-verify-profile` to pick a validation profile (`WIP` / `Ready` / `Heavy`). `Ready` is required before any final-status claim; trigger phrases are defined in `Quick Decision Matrix`.
144- All other testing rules (failpoints, integration recording, RealTiKV lifecycle, regression tests) are stated once in `Quick Decision Matrix` above; do not duplicate them here.
145
146## Code Style Guide
147
148### Go and backend code
149
150- Because TiDB is a complex system, code SHOULD remain maintainable for future readers with basic TiDB familiarity, including readers who are not experts in the specific subsystem/feature.
151- Follow existing package-local conventions first and keep style consistent with nearby files.
152- Code SHOULD be self-documenting through clear naming and structure.
153 - Example: when implementing a well-known algorithm, naming SHOULD be clear enough to make the approach recognizable; if naming alone may not make intent obvious, add a brief comment.
154- Keep changes focused; avoid unrelated refactors, renames, or moves in the same PR.
155- Keep error handling actionable and contextual; avoid silently swallowing errors.
156- For new source files (for example `*.go`), include the standard TiDB license header (copyright + Apache 2.0) by copying from a nearby file and updating year if needed.
157- Comments SHOULD explain non-obvious intent, constraints, invariants, concurrency guarantees, SQL/compatibility contracts, or important performance trade-offs, and SHOULD NOT restate what the code already makes clear.
158- Keep exported-symbol doc comments, and prefer semantic constraints over name restatement.
159
160### Tests and testdata
161
162- Prefer extending existing test suites and fixtures over creating new scaffolding.
163- Keep test changes minimal and deterministic; avoid broad golden/testdata churn unless required.
164- When recording outputs, verify changed result files before reporting completion.
165
166### Docs and command snippets
167
168- Commands in docs SHOULD be copy-pasteable from repository root unless explicitly scoped.
169- Use explicit placeholders such as `<package_name>`, `<TestName>`, and `<dir>`.
170- Documentation updates SHOULD keep terminology, policy wording, and command conventions consistent across related docs.
171- Keep guidance executable and concrete; avoid ambiguous phrasing.
172
173## Agent Output Contract
174
175When finishing a task, report:
176
1771. Files changed.
1782. Validation profile used (`WIP`, `Ready`, or `Heavy`) and why.
1793. Risks: correctness, compatibility, performance.
1804. Exact commands run for validation.
1815. What was not verified locally.
182
@@ −1 +1 @@
11 # AGENTS.md
22
3−This file adds path-specific guidance for Dumpling integration tests under
4−`dumpling/tests/**`. The repository root `AGENTS.md` still applies.
3+This file provides guidance to agents working in this repository.
54
6−## Test Placement
5+## Purpose and Precedence
76
8−- Prefer extending the nearest existing case in `dumpling/tests/<case>/run.sh`
9− before adding a new case directory.
10−- Keep new cases focused on one Dumpling behavior or workflow. Avoid broad
11− setup churn in shared cases unless the behavior under test needs it.
12−- Use deterministic table data and exact assertions against generated files in
13− `$DUMPLING_OUTPUT_DIR`.
14−- Set up and clean the database/table state needed by the test block itself.
15− Do not rely on state left by an earlier block in the same script.
7+- MUST means required.
8+- SHOULD means recommended unless there is a concrete reason to deviate.
9+- MAY means optional.
10+- Root `AGENTS.md` defines repository-wide defaults. If a deeper path later adds a more specific `AGENTS.md`, the deeper file SHOULD be treated as higher precedence for that subtree.
1611
17−## Harness Helpers
12+## Non-negotiables
1813
19−- Use `run_sql` for SQL setup and assertions against the source database.
20−- Use `run_dumpling` for Dumpling invocations instead of calling `bin/dumpling`
21− directly, unless the test is specifically about the helper or command wrapper.
22−- Use `file_should_exist` and `file_not_exist` for simple file presence checks.
23−- Inspect dumped SQL or CSV output under `$DUMPLING_OUTPUT_DIR`; keep greps and
24− cuts narrow enough that the assertion proves the intended behavior.
14+1. Correctness first. TiDB is a distributed SQL database; seemingly small changes can alter SQL semantics, consistency, or cluster behavior.
15+2. No speculative behavior. Do not invent APIs, defaults, protocol behavior, or test workflows.
16+3. Keep diffs minimal. Avoid unrelated refactors, broad renames, or formatting-only churn unless explicitly requested.
17+4. Leave verifiable evidence. Run targeted checks and report exact commands.
18+5. Respect generated code artifacts. Do not hand-edit generated code outputs; regenerate from source inputs.
2519
26−## Ports and Services
20+## Agent Interaction Overrides (Repo-Local)
2721
28−- `DUMPLING_TEST_PORT=4000` targets the TiDB server started by the Dumpling test
29− harness. Use this for TiDB-specific features and TiDB version-gated behavior.
30−- `DUMPLING_TEST_PORT=3306` targets the external MySQL service expected by the
31− harness. Use this only for MySQL compatibility coverage or existing cases that
32− intentionally compare MySQL behavior.
33−- When a script switches ports, set `DUMPLING_TEST_PORT` explicitly before each
34− block that depends on a specific server. Do not assume the previous block left
35− the desired value.
36−- If a test depends on TiDB version parsing, verify the local or CI
37− `bin/tidb-server` was built from a checkout with enough Git tag/history context
38− for `git describe --tags` to produce a semver-shaped release string. A
39− shallow or tagless checkout can make Dumpling detect TiDB as version `0.0.0`.
22+- For short non-code questions about definitions, acronyms, symbols, errors, or other potentially repository-specific terms, agents MUST search the active repository and read the closest authoritative local definition before answering, lead with the repository-specific meaning, and use general knowledge only when local evidence is absent or the user explicitly requests broader context.
4023
41−## Running Tests
24+## ExecPlans
4225
43−Run commands from the repository root.
26+When writing complex features or significant refactors, use an ExecPlan from design to implementation.
4427
45−```bash
46−# Build the TiDB server used by the harness when needed.
47−make server
48−```
28+- Definition and format: `PLANS.md` at repository root.
29+- Requirement: keep the ExecPlan updated as a living document while implementation progresses.
30+- Scope: use this for multi-step work where losing context would risk correctness or incomplete validation.
4931
50−```bash
51−# Run every Dumpling integration case.
52−make dumpling_integration_test
53−```
32+## Quick Decision Matrix
5433
34+| Task | Required action |
35+| --- | --- |
36+| Added/moved/renamed/removed Go files, changed the import section of an existing Go file, added a new top-level Go test function matching `func TestXxx(t *testing.T)` in an existing `*_test.go` file, changed Bazel files, updated Bazel test targets, or changed `go.mod`/`go.sum` | MUST run `make bazel_prepare` and include resulting Bazel metadata changes in the PR (for example `BUILD.bazel`, `**/*.bazel`, and `**/*.bzl`). |
37+| Running package unit tests | SHOULD run targeted tests and avoid full-package runs unless needed (see `docs/agents/testing-flow.md` -> `Unit tests`). |
38+| Unit tests in a package that uses failpoints | MUST enable failpoints before tests and disable afterward (see `docs/agents/testing-flow.md` -> `Failpoint decision for unit tests`). |
39+| Recording integration tests | MUST use the recording command in `docs/agents/testing-flow.md` -> `Integration tests` (not `-record`; `-record` is for unit-test suites that explicitly support it). |
40+| RealTiKV tests | MUST start playground in background, run tests, then clean up playground/data (see `docs/agents/testing-flow.md` -> `RealTiKV tests`). |
41+| Bug fix | MUST add a regression test and verify it fails before fix and passes after fix. |
42+| Fmt-only PR | MUST NOT run costly `realtikvtest`; local compilation is enough. |
43+| During local coding iterations (not claiming completion) | SHOULD use the `WIP` verification profile from `.agents/skills/tidb-verify-profile` to run only scoped checks. |
44+| Claiming task completion / PR readiness | MUST use the `Ready` verification profile from `.agents/skills/tidb-verify-profile`; if there are code changes, this includes `make lint`. `Ready` is mandatory before making final-status claims such as "fixed", "done", "all tests pass", "ready for review", or "ready for PR". |
45+| Creating or updating a GitHub issue | SHOULD use `.agents/skills/tidb-issue-metadata-guard` to preserve issue templates and label hygiene. |
46+| Creating a PR or editing PR metadata | SHOULD use `.agents/skills/tidb-pr-metadata-guard` to preserve PR templates, title scope, and bot-parsed checklist sections. |
47+| Before finishing | SHOULD self-review diff quality before finishing. |
48+| Expensive optional sweeps (for example `make bazel_lint_changed`, broad package runs) | MUST run only when required by change scope, CI reproduction, or explicit user request. |
49+
50+### Skills
51+
52+- Repository-level skills are maintained under `.agents/skills` (relative to the repository root / current working directory).
53+- Keep skill content and references together under each skill folder (for example: `.agents/skills/<skill>/SKILL.md` and `.agents/skills/<skill>/references/`).
54+- `.github/skills` is kept only as a migration note path and should not be used as the primary location for new skill updates.
55+- Policy belongs in `AGENTS.md`; detailed command playbooks SHOULD live in `docs/agents/*`, and skills SHOULD provide entrypoint workflows that reference those playbooks.
56+- Operational testing/build skills are indexed in `.agents/skills/README.md` to avoid duplicated lists drifting in multiple docs.
57+
58+## Pre-flight Checklist
59+
60+1. Restate the task goal and acceptance criteria.
61+2. Locate the owning subsystem and the closest existing tests (`Repository Map`, `Task -> Validation Matrix`). If the target package has `doc.go`, agents MUST read that package-level doc first before diving into implementation files.
62+3. Decide prerequisites before running tests/build (`docs/agents/testing-flow.md` -> `Failpoint decision for unit tests`; `AGENTS.md` -> `Build Flow` -> `When make bazel_prepare is required`).
63+4. Pick the smallest valid validation set and prepare final reporting items (`Agent Output Contract`).
64+5. If `AGENTS.md` or docs under `docs/agents/` changed, follow the checklist in `docs/agents/agents-review-guide.md` before finishing.
65+
66+## Repository Map (Entry Points)
67+
68+- Detailed subsystem path mapping and test surfaces live in `docs/agents/architecture-index.md` (source of truth).
69+- Update policy: when module/path mapping changes, update `docs/agents/architecture-index.md` first; update this section only when top-level entry points change.
70+- `/pkg/planner/`: planner and optimization entrypoint.
71+- `/pkg/executor/`, `/pkg/expression/`: SQL execution and expression evaluation.
72+- `/pkg/session/`, `/pkg/sessionctx/`: session lifecycle and runtime statement context.
73+- `/pkg/ddl/`, `/pkg/infoschema/`, `/pkg/meta/`: schema and metadata management.
74+- `/pkg/store/`, `/pkg/kv/`: storage and distributed query interfaces.
75+- `/pkg/statistics/`: statistics and estimation behavior entrypoint.
76+- `/pkg/parser/`: SQL grammar and AST.
77+- `/tests/integrationtest/`, `/tests/realtikvtest/`: SQL integration and real TiKV test surfaces.
78+- `/cmd/tidb-server/`: TiDB server entrypoint.
79+
80+## Notes
81+
82+- Follow `docs/agents/notes-guide.md`.
83+- DDL module-only rules (applies to changes under `pkg/ddl/` and `docs/agents/ddl/`):
84+ - MUST: Before making/reviewing any DDL changes in the DDL module, read `docs/agents/ddl/README.md` first and use it as the default map of the execution framework.
85+ - Debugging: You MAY reference `docs/agents/ddl/*`, but you MUST NOT treat it as authoritative. Treat it as hypotheses until verified in code/tests (avoid hallucination/outdated assumptions).
86+ - Doc drift: If implementation and `docs/agents/ddl/*` differ, you MUST update the docs to match reality and call it out in the PR/issue. Do not defer.
87+
88+## Build Flow
89+
90+### When `make bazel_prepare` is required
91+
92+Run `make bazel_prepare` before building when any of the following is true:
93+
94+- New workspace or fresh clone.
95+- Bazel-related files changed (for example `WORKSPACE`, `DEPS.bzl`, `BUILD.bazel`, `MODULE.bazel`, `MODULE.bazel.lock`).
96+- Any Go source file is added/removed/renamed/moved in the PR.
97+- The import section changed in any existing Go source file (including `*_test.go`).
98+- A code change adds a new top-level Go test function matching `func TestXxx(t *testing.T)` in an existing `*_test.go` file.
99+- Go module dependencies changed (for example `go.mod`, `go.sum`), including adding third-party dependencies.
100+- Bazel test targets were updated (for example `shard_count` changed, test `srcs` list edited, or `tests/realtikvtest/**/BUILD.bazel` modified).
101+- Local Bazel dependency/toolchain errors occurred.
102+
103+For an operational decision checklist, use `.agents/skills/tidb-bazel-prepare-gate`.
104+
105+Recommended local build flow:
106+
55107 ```bash
56−# Run one case.
57−CASE=basic make dumpling_integration_test
108+# Conditional step: run only when required by this section or `.agents/skills/tidb-bazel-prepare-gate`.
109+make bazel_prepare
58110 ```
59111
60112 ```bash
61−# Run one case with shell tracing.
62−VERBOSE=true CASE=basic make dumpling_integration_test
113+# Then continue with normal local build steps.
114+make bazel_bin
115+make gogenerate # optional: regenerate generated code
116+go mod tidy # optional: if go.mod/go.sum changed
117+git fetch origin --prune
63118 ```
64119
65−The `dumpling_integration_test` target checks these binaries before running:
66−`bin/tidb-server`, `bin/minio`, `bin/mc`, `bin/tidb-lightning`, and
67−`bin/sync_diff_inspector`. The required sync-diff binary path uses an underscore:
68−`bin/sync_diff_inspector`.
120+`make bazel_lint_changed` is intentionally excluded from the default local flow because it can be slow and resource-intensive on local macOS environments. Agents MUST NOT run `make bazel_lint_changed` unless the user explicitly requests it.
69121
70−The full harness also expects the `mysql` client and a local MySQL-compatible
71−server on `127.0.0.1:3306` for cases that target MySQL.
122+## Task -> Validation Matrix
72123
73−## Validation Notes
124+Use the smallest set that still proves correctness.
125+Command details for package, integration-test, and RealTiKV surfaces live in `docs/agents/testing-flow.md`.
74126
75−- For a small shell-only test change, run the changed case with
76− `CASE=<case> make dumpling_integration_test` when local prerequisites are
77− available.
78−- If unrelated blocks in the same case require unavailable local services, a
79− focused TiDB-only reproduction may be useful while iterating, but report that
80− the official case target was not fully run.
81−- `make bazel_prepare` is not required for changes limited to Dumpling shell
82− integration tests or this file. Re-check root `AGENTS.md` if Go files, Bazel
83− metadata, or module files are also changed.
127+| Change scope | Minimum validation |
128+| --- | --- |
129+| `pkg/planner/**` rules or logical/physical plans | Targeted planner unit tests and update rule testdata when needed |
130+| `pkg/executor/**` SQL behavior | Targeted unit test plus relevant integration test (`tests/integrationtest`) |
131+| `pkg/expression/**` builtins or type inference | Targeted expression unit tests with edge-case coverage |
132+| `pkg/session/**` / variables / protocol behavior | Targeted package tests plus SQL integration tests for user-visible behavior |
133+| `pkg/ddl/**` schema changes | DDL-focused unit/integration tests and compatibility impact checks |
134+| `pkg/store/**` / `pkg/kv/**` storage behavior | Targeted unit tests; use realtikv tests if behavior depends on real TiKV |
135+| Parser files (`pkg/parser/**`) | Parser-specific Make targets (`make parser`, `make parser_yacc`, `make parser_fmt`, `make parser_unit_test`) and related unit tests |
136+| `tests/integrationtest/t/**` changed | Record and verify regenerated result correctness (see `docs/agents/testing-flow.md` -> `Integration tests`) |
137+| `tests/realtikvtest/**` changed | Start playground, run scoped tests, then mandatory cleanup (see `docs/agents/testing-flow.md` -> `RealTiKV tests`) |
138+
139+## Testing Policy
140+
141+- Detailed command playbooks live in `docs/agents/testing-flow.md`.
142+- Select required test surfaces first (`Task -> Validation Matrix`), then run scoped commands from the playbook.
143+- Use `.agents/skills/tidb-verify-profile` to pick a validation profile (`WIP` / `Ready` / `Heavy`). `Ready` is required before any final-status claim; trigger phrases are defined in `Quick Decision Matrix`.
144+- All other testing rules (failpoints, integration recording, RealTiKV lifecycle, regression tests) are stated once in `Quick Decision Matrix` above; do not duplicate them here.
145+
146+## Code Style Guide
147+
148+### Go and backend code
149+
150+- Because TiDB is a complex system, code SHOULD remain maintainable for future readers with basic TiDB familiarity, including readers who are not experts in the specific subsystem/feature.
151+- Follow existing package-local conventions first and keep style consistent with nearby files.
152+- Code SHOULD be self-documenting through clear naming and structure.
153+ - Example: when implementing a well-known algorithm, naming SHOULD be clear enough to make the approach recognizable; if naming alone may not make intent obvious, add a brief comment.
154+- Keep changes focused; avoid unrelated refactors, renames, or moves in the same PR.
155+- Keep error handling actionable and contextual; avoid silently swallowing errors.
156+- For new source files (for example `*.go`), include the standard TiDB license header (copyright + Apache 2.0) by copying from a nearby file and updating year if needed.
157+- Comments SHOULD explain non-obvious intent, constraints, invariants, concurrency guarantees, SQL/compatibility contracts, or important performance trade-offs, and SHOULD NOT restate what the code already makes clear.
158+- Keep exported-symbol doc comments, and prefer semantic constraints over name restatement.
159+
160+### Tests and testdata
161+
162+- Prefer extending existing test suites and fixtures over creating new scaffolding.
163+- Keep test changes minimal and deterministic; avoid broad golden/testdata churn unless required.
164+- When recording outputs, verify changed result files before reporting completion.
165+
166+### Docs and command snippets
167+
168+- Commands in docs SHOULD be copy-pasteable from repository root unless explicitly scoped.
169+- Use explicit placeholders such as `<package_name>`, `<TestName>`, and `<dir>`.
170+- Documentation updates SHOULD keep terminology, policy wording, and command conventions consistent across related docs.
171+- Keep guidance executable and concrete; avoid ambiguous phrasing.
172+
173+## Agent Output Contract
174+
175+When finishing a task, report:
176+
177+1. Files changed.
178+2. Validation profile used (`WIP`, `Ready`, or `Heavy`) and why.
179+3. Risks: correctness, compatibility, performance.
180+4. Exact commands run for validation.
181+5. What was not verified locally.
84182
