Two files, one repository
facebook/rocksdb ships 2 formats across 2 indexed files. The question worth asking is whether the second one says anything the first does not.
CompareAGENTS.md ↔ CLAUDE.md
| Dimension | Shared | Only in A | Only in B | Overlap |
|---|---|---|---|---|
| Sections | 0 | 1 | 44 | 0% |
| Commands | 0 | 0 | 6 | 0% |
| Section tags | 0 | 1 | 12 | 0% |
What each file covers
Sections
0 shared · 1 only in A · 44 only in B- − Agent Instructions
- + RocksDB Code Generation and Review Guidance
- + General Best Practices
- + Code Quality and Maintainability
- + Testing Philosophy
- + Performance Considerations
- + API Design and Compatibility
- + Component-Specific Guidance
- + Database Core (`db`)
- + Public Headers (`include`)
- + Internal Utilities (`util`)
- + Table Management (`table`)
- + Utilities (`utilities`)
- + Options and Configuration (`options`)
- + Cache (`cache`)
- + Code Review Checklist
- + Contract Boundaries
- + Correctness
- + Testing
- + Performance
- + API and Compatibility
- + Code Quality
- + Common Review Feedback Patterns
- + Important tips
- + Build system
- + Avoiding mixed build modes with Make (use `AUTO_CLEAN=1`)
- + Source checks
- + License headers
- + RTTI and dynamic_cast
- + Cross-platform / portability
- + Unit Test
- + Unit test dedup guidelines
- + Adding new public API
- + Adding new option
- + Removing deprecated option
- + Metrics
- + Stress test
- + Component docs
- + DB bench update
- + Adding release note
- + Blog posts (docs/_posts)
- + Final verification of the change
- + Monitoring make check progress
- + Executing benchmark using db_bench
- + Formatting code
Commands
0 shared · 0 only in A · 6 only in B- + make check-progress
- + make clean
- + make check-sources
- + make
- + make check
- + make format-auto
Section tags
0 shared · 1 only in A · 12 only in B- − agent-behaviour
- + build
- + test
- + lint-format
- + code-style
- + testing-strategy
- + git-pr
- + database
- + api
- + ui
- + performance
- + deployment
- + docs
Line diff
facebook/rocksdb · AGENTS.md
@@ −1 @@
1# Agent Instructions
2
3This repository's authoritative agent instructions live in `CLAUDE.md`.
4
5Read and follow [`CLAUDE.md`](./CLAUDE.md) in full before making changes or
6reviewing code in this checkout.
7
8If there is any ambiguity between this file and `CLAUDE.md`, `CLAUDE.md` takes
9precedence.
10
facebook/rocksdb · CLAUDE.md
@@ +1 @@
1# RocksDB Code Generation and Review Guidance
2
3This document provides guidance for generating and reviewing code in the RocksDB project, derived from analysis of code review feedback across hundreds of complex merged Pull Requests. Use this as a reference when writing code with AI assistants or conducting code reviews.
4
5---
6
7## General Best Practices
8
9### Code Quality and Maintainability
10
11**Clarity and Readability:** Write clear, self-documenting code. Use meaningful variable names, add comments for complex logic, and structure code to minimize cognitive load. Avoid clever tricks that sacrifice readability for marginal performance gains unless absolutely necessary. Avoid static_cast, reinterpret_cast, and C-style casts; static_cast_with_check, up_cast, and lossless_cast from cast_util.h are preferred.
12
13**Consistent Style:** Follow existing code style conventions. RocksDB uses `.clang-format` for formatting, specific naming conventions, and structural patterns. Deviations from these patterns are frequently flagged in reviews.
14
15**Error Handling:** Ensure robust error handling throughout the codebase. Use RocksDB's `Status` type consistently, propagate errors appropriately, and avoid silently ignoring failures. Reviewers pay close attention to edge cases and failure modes.
16
17### Testing Philosophy
18
19**Comprehensive Coverage:** Every change should include appropriate test coverage. This includes unit tests for isolated functionality, integration tests for component interactions, and stress tests for concurrency and performance validation. Reviewers will ask for additional tests if coverage is insufficient.
20
21**Edge Cases and Failure Modes:** Tests should explicitly cover edge cases, boundary conditions, and potential failure scenarios. This is especially important for changes affecting core database operations, compaction, or recovery logic.
22
23**Platform-Specific Testing:** RocksDB supports multiple platforms (Linux, Windows, macOS) and compilers (GCC, Clang, MSVC). Changes should be tested across relevant platforms, particularly when touching platform-specific code or using compiler-specific features.
24
25### Performance Considerations
26
27**⚠️ PERFORMANCE IS CRITICAL:** RocksDB is a high-performance storage engine where every CPU cycle and memory access matters. When writing code, always evaluate from a performance perspective. This is not optional—performance-aware coding is a fundamental requirement for all contributions.
28
29**Benchmarking and Profiling:** Performance claims should be backed by empirical evidence. Use RocksDB's benchmarking tools (e.g., `db_bench`) to validate improvements. Reviewers will request benchmark results for changes that could impact performance.
30
31**Memory Allocation:** Minimize dynamic memory allocations, especially in hot paths. Prefer stack allocation over heap allocation. Reuse buffers when possible. Consider using arena allocators or memory pools for frequent small allocations. Every `new`, `malloc`, or container resize has a cost.
32
33**Memory Copy:** Avoid unnecessary memory copies. Use move semantics, `std::string_view`, `Slice`, and pass-by-reference where appropriate. Be aware of implicit copies in STL containers and function returns. Prefer in-place operations over copy-and-modify patterns.
34
35**CPU Cache Efficiency:** Design data structures and access patterns to be cache-friendly. Keep frequently accessed data together (data locality). Prefer sequential memory access over random access. Be mindful of cache line sizes (typically 64 bytes) and avoid false sharing in concurrent code. Consider struct packing and field ordering to improve cache utilization.
36
37**Loop Optimization:** Look for opportunities to collapse nested loops, reduce loop overhead, and minimize branch mispredictions. Hoist invariant computations out of loops. Consider loop unrolling for tight inner loops. Batch operations when possible to amortize per-operation overhead.
38
39**SIMD and Vectorization:** Leverage SIMD instructions (SSE, AVX) for data-parallel operations when appropriate. Structure data to enable auto-vectorization by the compiler. Consider explicit SIMD intrinsics for critical hot paths like checksum computation, encoding/decoding, and bulk data processing.
40
41**Branch Prediction:** Minimize unpredictable branches in hot paths. Use `LIKELY`/`UNLIKELY` macros to hint branch prediction, e.g. for error cases and other rare or otherwise costly cases, but NOT for predicting popular configurations. Consider branchless alternatives for simple conditionals. Order switch cases and if-else chains by frequency.
42
43**Memory and Resource Management:** Be mindful of memory allocations, especially in hot paths. Use RAII patterns, smart pointers, and RocksDB's memory management utilities appropriately.
44
45**Hot Path Analysis:** When deciding how aggressively to optimize code, consider whether it's on a hot path:
46- **Hot path** (executed thousands+ times, e.g., data access, iteration, compaction loops): Performance is paramount. Apply all optimization techniques—loop collapsing, SIMD, cache optimization, pre-allocation, etc. The cost of each operation is multiplied by execution frequency.
47- **Cold path** (executed rarely, e.g., DB open, configuration parsing, error handling): Maintainability and clarity are more important. Prefer readable code over micro-optimizations. Complex optimizations here add maintenance burden with negligible performance benefit.
48- **Warm path** (moderate frequency): Balance both concerns. Use profiling data to guide optimization decisions.
49
50**Avoid Premature Optimization:** While performance is critical, focus on correctness first, then optimize based on profiling data. However, be performance-aware from the start—choosing the right algorithm and data structure upfront is not premature optimization. Use the hot path analysis above to decide how much optimization effort is warranted.
51
52### API Design and Compatibility
53
54**Backwards Compatibility:** RocksDB maintains strong backwards compatibility guarantees. Breaking changes are rare and require extensive justification. When deprecating features, follow the project's deprecation policy (typically spanning multiple releases).
55
56**API Consistency:** New APIs should be consistent with existing patterns. Use similar naming conventions, parameter ordering, and return types. Reviewers will suggest changes to improve consistency with the broader codebase.
57
58**Documentation:** Public APIs must be thoroughly documented, without unnecessary embelishment nor dwelling on implementation details nor project planning. When non-obvious, include usage examples, parameter descriptions, known bugs or limitations, notes on thread safety, performance characteristics, and compatibility considerations. Re-read comments for ambiguous terminology and phrasing, such as ambiguously re-purposed programming jargon.
59
60---
61
62## Component-Specific Guidance
63
64### Database Core (`db`)
65
66The database core handles write-ahead logging (WAL), memtables, compaction, and recovery. This component receives the most scrutiny in code reviews.
67
68**Concurrency and Thread Safety:** Database operations are highly concurrent. Reviewers carefully examine locking strategies, atomic operations, and memory ordering. Document synchronization assumptions clearly. Use appropriate memory ordering semantics (`acquire`/`release` vs. `seq_cst`).
69
70**Compaction Logic:** Changes to compaction are complex and high-risk. Ensure that compaction logic respects configured parameters, handles edge cases (empty databases, single-file compactions), and maintains correctness under concurrent operations.
71
72**Error Propagation:** Database operations can fail in many ways (I/O errors, corruption, resource exhaustion). Ensure that errors are properly propagated, logged, and handled. Avoid assertions in production code paths.
73
74**Testing:** Database core changes require extensive testing, including unit tests, integration tests, and stress tests. Test with various configurations, compaction styles, and concurrent workloads.
75
76### Public Headers (`include`)
77
78Public headers define RocksDB's API surface. Changes here have the highest compatibility impact.
79
80**API Design:** New APIs should be intuitive, consistent with existing patterns, and well-documented. Consider how the API will be used in practice and avoid adding unnecessary complexity.
81
82**Backwards Compatibility:** Breaking changes to public APIs require extensive justification and a deprecation plan. Maintain ABI compatibility for bug fixes and patch releases.
83
84**Documentation:** Every public API must be thoroughly documented with usage examples, parameter descriptions, and notes on thread safety and performance characteristics.
85
86**Deprecation:** When deprecating APIs, follow the project's policy. Mark deprecated APIs clearly, provide migration guidance, and maintain support for at least one major release.
87
88### Internal Utilities (`util`)
89
90Internal utilities provide common functionality used throughout the codebase.
91
92**Code Reuse:** Utilities should be general-purpose and reusable. Avoid duplicating functionality that already exists elsewhere in the codebase.
93
94**Error Handling:** Utility functions should handle errors robustly and propagate them appropriately. Consider edge cases like overflow, underflow, and invalid inputs.
95
96**Testing:** Utility functions should have comprehensive test coverage, including edge cases and failure modes. Consider adding death tests for assertions.
97
98**Performance:** Utilities are often used in hot paths. Ensure that implementations are efficient and avoid unnecessary allocations or copies.
99
100### Table Management (`table`)
101
102Table management handles SST file format, block-based tables, and table readers/writers.
103
104**Block Format and Checksums:** Changes to block format require extreme care. Ensure that checksums are computed and verified correctly. Test with various compression algorithms and block sizes.
105
106**Iterator Correctness:** Table iterators are used throughout the codebase. Ensure that iterator semantics (Seek, Next, Prev) are correct, especially at boundaries and with deletions.
107
108**Caching and Prefetching:** Table readers interact with the block cache and prefetching logic. Ensure that cache keys are unique and that prefetching respects configured limits.
109
110**Performance:** Table operations are performance-critical. Benchmark changes that could impact read or write performance.
111
112### Utilities (`utilities`)
113
114Utilities include optional features like transactions, backup engine, and checkpoint.
115
116**Feature Isolation:** Utilities should be self-contained and not introduce unnecessary dependencies on core database internals.
117
118**Deprecation and Cleanup:** Legacy features are being phased out. When removing deprecated code, ensure that migration paths are documented and that users have sufficient warning.
119
120**Cross-Platform Compatibility:** Utilities often interact with OS-specific APIs. Ensure that code works on all supported platforms.
121
122### Options and Configuration (`options`)
123
124Options define RocksDB's configuration system.
125
126**Type Safety:** Use appropriate types for options (e.g., `uint32_t` for flags, scoped enums for enumerated values).
127
128**Deprecation Policy:** When deprecating options, follow the project's policy. Document the deprecation, provide migration guidance, and maintain support for at least one major release.
129
130**Dynamic Configuration:** Some options can be changed dynamically. Ensure that dynamic changes are thread-safe and take effect correctly.
131
132**Validation:** Validate option values and provide clear error messages for invalid configurations.
133
134### Cache (`cache`)
135
136Cache management is critical for RocksDB's performance.
137
138**Concurrency:** Cache operations are highly concurrent. Ensure that implementations are thread-safe and use appropriate synchronization primitives.
139
140**Performance:** Cache operations are in the hot path. Optimize for low latency and high throughput. Benchmark changes carefully.
141
142**Memory Management:** Cache implementations must manage memory carefully to avoid leaks and excessive allocations.
143
144**Eviction Policies:** Changes to eviction policies should be well-tested and benchmarked to ensure they improve overall performance.
145
146---
147
148## Code Review Checklist
149
150When reviewing RocksDB code (or preparing code for review), use this checklist:
151
152### Contract Boundaries
153- [ ] Is each behavior owned by the right layer? High-level policy (for example,
154 "compaction wants this I/O mode") should live at the caller/policy layer, while
155 lower layers should expose generic mechanisms (for example, "open a fresh
156 reader", "skip shared cache insertion", or "use these FileOptions").
157- [ ] Do comments and names describe local contracts rather than leaking a
158 specific caller's rationale into reusable APIs? Generic code should not need to
159 know about one current use case unless the API itself is intentionally
160 use-case-specific.
161- [ ] Does each flag or parameter control one coherent behavior? If one boolean
162 starts implying ownership, cache policy, I/O mode, prefetching, and caller
163 identity, split it into explicit flags or an options struct.
164- [ ] Could a future caller use this lower-level API without accidentally
165 inheriting assumptions from compaction, backup, user reads, or a particular
166 table format? If not, tighten the contract with assertions, clearer names, or
167 a narrower API.
168- [ ] Are implementation details not being used as policy signals? Prefer an
169 explicit contract over inferring behavior from incidental fields such as file
170 options, cache handles, or current table-reader state.
171
172### Correctness
173- [ ] Does the change preserve database semantics (e.g., snapshot isolation, key ordering)?
174- [ ] Are all error cases handled appropriately?
175- [ ] Is the change thread-safe? Are synchronization primitives used correctly?
176- [ ] Are there any potential data races or deadlocks?
177
178### Testing
179- [ ] Does the change include appropriate test coverage?
180- [ ] Are edge cases and failure modes tested?
181- [ ] Have the tests been run on all supported platforms?
182- [ ] Are stress tests passing?
183
184### Performance
185- [ ] Are there benchmark results for performance-sensitive changes?
186- [ ] Does the change avoid unnecessary allocations or copies?
187- [ ] Are hot paths optimized appropriately?
188
189### API and Compatibility
190- [ ] Is the change backwards compatible?
191- [ ] Are new APIs consistent with existing patterns?
192- [ ] Is the public API documented?
193- [ ] Are deprecated features handled according to policy?
194
195### Code Quality
196- [ ] Does the code follow RocksDB's style conventions?
197- [ ] Is the code clear and maintainable?
198- [ ] Are comments and documentation sufficient?
199- [ ] Are there any code smells or anti-patterns?
200
201---
202
203## Common Review Feedback Patterns
204
205The following patterns emerged as frequent sources of review feedback:
206
2071. **Test Coverage:** Reviewers frequently request additional tests for edge cases, platform-specific behavior, and failure modes. Complex changes require comprehensive test coverage including unit tests, integration tests, and stress tests.
208
2092. **Error Handling:** Ensure proper error propagation using RocksDB's `Status` type. Avoid silent failures and provide clear error messages that include context about what failed and why.
210
2113. **API Design:** New APIs should be consistent with existing patterns. Use descriptive names that follow established conventions. Avoid breaking changes without strong justification and a clear deprecation plan.
212
2134. **Documentation:** Public APIs must be documented with usage examples and notes on thread safety, performance characteristics, and compatibility considerations. Complex internal logic should also be well-commented.
214
2155. **Performance:** Performance-sensitive changes require benchmark results to validate improvements. Use `db_bench` and other profiling tools to measure impact. Avoid premature optimization that adds complexity without measurable benefit.
216
2176. **Concurrency:** Thread safety is critical in RocksDB. Document synchronization assumptions clearly. Use appropriate memory ordering semantics. Consider potential race conditions and deadlocks.
218
2197. **Code Style:** Follow existing conventions for naming, formatting, and structure. Use `.clang-format` for consistent formatting. Prefer scoped enums (`enum class`) over unscoped enums.
220
2218. **Backwards Compatibility:** RocksDB maintains strong compatibility guarantees. Breaking changes require extensive justification. When deprecating features, provide migration guidance and maintain support across multiple releases.
222
2239. **Refactoring:** Reviewers appreciate refactoring that improves code readability and maintainability. Look for opportunities to deduplicate code and simplify complex logic.
224
22510. **Platform Compatibility:** Ensure changes work correctly on all supported platforms (Linux, Windows, macOS) and with all supported compilers (GCC, Clang, MSVC).
226
22711. **Contract Boundary Leaks:** When a change plumbs a new option or use-case
228specific behavior through multiple subsystems, review the call chain for
229contract leaks. Caller-specific rationale belongs at the call site or public API
230documentation; reusable layers should expose precise, layer-local capabilities.
231Watch especially for comments mentioning one caller in generic code, booleans
232that silently bundle several behaviors, and downstream code inferring policy
233from an implementation detail instead of an explicit option.
234
235---
236
237## Important tips
238
239### Build system
240* There are 3 build system. Make for git clones, BUCK (meta internal) for hg
241 clones, and CMake for some special cases.
242* When a new .cc file is added, update Makefile, CMakeLists.txt, src.mk, BUCK.
243* Don't manually edit BUCK file, after updating src.mk, run
244 /usr/local/bin/python3 buckifier/buckify_rocksdb.py to update it
245* For -j in make command, use the number of CPU cores to decide it.
246* When searching for references to something (a symbol, library, etc.), do not
247 restrict or truncate your search based on presumed relevance or scope. It is
248 important and time-saving to keep the repo reasonably consistent across
249 different build systems, programming languages, and even between
250 documentation and implementation.
251
252### Avoiding mixed build modes with Make (use `AUTO_CLEAN=1`)
253
254Object files are written to the same paths regardless of build flags, so
255reusing objects from a prior build with different flags causes confusing
256linker errors, etc. This problem is essentially avoidable by ALWAYS using
257`AUTO_CLEAN=1 make -j<n> <something>` for manual make invocations. This
258will automatically clean object files if the build parameters/flavor have
259changed. The `build_tools/rockstest.sh` / `rocksptest.sh` helpers described
260below set `AUTO_CLEAN=1` for you.
261
262`AUTO_CLEAN=1` does not fix Make failures associated with stale .d files
263referring to removed files. Resolve that manually or with `make clean`
264without complaining to the user.
265
266### Source checks
267* Run `make check-sources` before committing. This catches non-ASCII
268 characters in source files and other source-level issues that CI will
269 reject. In particular, **do not use Unicode characters** (em dashes,
270 smart quotes, etc.) in comments or strings -- use ASCII equivalents
271 (`--` instead of em dash, `'` instead of smart quote, etc.).
272
273### License headers
274* Every new source file needs a license header. For a file that does **not**
275 carry an outside/third-party copyright, use the standard Meta dual-licensed
276 header (the dual-license designation is required -- a bare
277 "All Rights Reserved" copyright is not an acceptable open-source header):
278 ```
279 // Copyright (c) Meta Platforms, Inc. and affiliates.
280 // This source code is licensed under both the GPLv2 (found in the
281 // COPYING file in the root directory) and Apache 2.0 License
282 // (found in the LICENSE.Apache file in the root directory).
283 ```
284 Use a `#` comment prefix instead of `//` for shell, Python, and Makefile
285 fragments.
286* Files derived from an external source (e.g. LevelDB) keep their original
287 upstream copyright line in addition to the header above.
288
289### RTTI and dynamic_cast
290* Production code and `db_stress` must build in **release mode
291 (`-fno-rtti`)**. Do not use `dynamic_cast` anywhere except unit tests.
292 Use `static_cast_with_check` from `util/cast_util.h` (validates with
293 `dynamic_cast` in debug builds, plain `static_cast` in release).
294* Unit tests (`*_test.cc`) are built in debug mode with RTTI enabled.
295
296### Cross-platform / portability
297Local `make` only exercises Linux with GCC/Clang, but CI
298(`.github/workflows/pr-jobs.yml` and `nightly.yml`) gates on a much wider
299matrix, so portability breaks are invisible locally until CI fails. Code must
300build (and where noted, run tests) across:
301
302| Axis | Must support |
303|------|--------------|
304| OS | Linux (x86_64 + ARM), macOS, Windows |
305| Compiler | GCC, Clang (libstdc++ **and** libc++), AppleClang, **MSVC (VS2022)**, MinGW (Linux cross-compile, build-only, no gflags) |
306| Build system | Make, CMake, and BUCK (internal) -- keep all in sync (see "Build system" above) |
307| Config | release (`-fno-rtti`), `ASSERT_STATUS_CHECKED`, ASAN/UBSAN/TSAN, folly, unity build, JNI/Java |
308
309Treat these as constraints to satisfy and infer the specifics from them before
310adding any system header, libc call, or compiler-specific construct. The most
311common trap: anything that compiles under GCC/Clang on Linux but not under
312**MSVC/MinGW** -- e.g. unguarded POSIX-only headers/functions (`<unistd.h>`,
313`<sys/*.h>`, `getpid`, `_exit`, ...) or GCC/Clang extensions
314(`__attribute__`, `__builtin_*`, VLAs, `alloca`). Prefer the `port::`/`Env`
315abstractions; otherwise guard with `#ifdef OS_WIN` (POSIX `<unistd.h>` ->
316Windows `<process.h>`). Because libc++ is also tested, include what you use
317rather than relying on libstdc++ transitive includes.
318
319### Unit Test
320* After all of the unit tests are added, review them and try to extract common
321 reusable utility functions to reduce code duplication due to copy past between
322 unit tests. This should be done every time unit test is updated.
323* Don't use sleep to wait for certain events to happen. This will cause test to
324 be flaky. Instead, use sync point to synchronize thread progress.
325* Cap unit test execution with 60 seconds timeout.
326* To build and run unit tests locally, prefer these helper scripts:
327 * `build_tools/rocksptest.sh <test_binary> [more_binaries...] [args...]`
328 builds the binary(ies) with parallel make and `AUTO_CLEAN=1` and runs
329 them under gtest-parallel, sharding the test cases across CPUs. Prefer
330 this whenever running more than a couple of test cases, e.g.
331 `build_tools/rocksptest.sh table_test` or
332 `build_tools/rocksptest.sh db_test env_test --gtest_filter=*Foo*`.
333 * `build_tools/rockstest.sh <test_binary> [args...]` builds with parallel
334 make and `AUTO_CLEAN=1` and runs the binary directly (serially).
335 Use it only for a very small number of test cases, e.g.
336 `build_tools/rockstest.sh db_test --gtest_filter=*MixedSlowdown*`.
337* After writing a test, stress-test for flakiness (AUTO_CLEAN handles the
338 rebuild needed by the `COERCE_CONTEXT_SWITCH=1` flag change):
339 ```bash
340 COERCE_CONTEXT_SWITCH=1 build_tools/rockstest.sh {test_binary} -r100 \
341 --gtest_filter="*YourTestName*"
342 ```
343* For CI-style flaky tests that do not reproduce with `gtest_parallel.py`,
344 `--gtest_repeat`, or normal coerce-mode runs, inspect
345 `tools/gtest_parallel_repro.py --help`.
346* Each unit test file has overheads, so avoid creating new unit test files
347 for random minor features. Consider adding to slice_test, db_etc3_test, or
348 others.
349
350### Unit test dedup guidelines
351* Extract helper functions for repeated patterns such as object
352 construction, round-trip (encode → decode → verify), and common
353 assertion sequences.
354* Use table-driven tests (struct array + loop) when multiple test cases
355 share the same logic but differ only in input/expected data.
356* Prefer randomized tests over exhaustive parameter permutations. Use
357 `Random` from `util/random.h` (not `std::mt19937`). Use a time-based
358 seed with `SCOPED_TRACE("seed=" + std::to_string(seed))` so failures
359 are reproducible.
360* Keep deterministic edge-case tests separate from randomized tests
361 (error paths, boundary conditions, format verification).
362* Methods only used in tests should be private with `friend class` +
363 `TEST_F` fixture wrappers. In wrappers, always fully qualify the
364 target method to avoid infinite recursion.
365
366### Adding new public API
367 Refer to claude_md/add_public_api.md
368
369### Adding new option
370 Refer to claude_md/add_option.md
371
372### Removing deprecated option
373 Refer to claude_md/remove_option.md
374
375### Metrics
376* When adding a new feature, evaluate whether there is opportunity to add
377 metrics. Try to avoid causing performance regression on hot path when adding
378 metrics.
379
380### Stress test
381* When adding a new feature, make sure stress test covers the new option.
382
383### Component docs
384* For component-level design notes and implementation walkthroughs, start with
385 `docs/components/index.md`.
386* Documentation under `docs/components/` is organized by subsystem in
387 `docs/components/<area>/`.
388* Each subsystem directory should have an `index.md` entry point plus focused
389 chapter files for deeper topics.
390
391### DB bench update
392* When adding a performance related feature, support it in db_bench
393
394### Adding release note
395* Release note should be kept short at high level for external user consumption.
396 Release notes identify what users might care about most in a release. They
397 are not exhaustive and are not a guide. PLEASE learn from past agents who
398 ried to build elaborate release notes with implementation details and
399 elsewhere-documented nuance. That wastes time. Fight the bias that
400 "my change" is important so must be worthy of release note mention.
401* If more than single markdown line, consider how their formatting will be
402 integrated into HISTORY.md.
403
404### Blog posts (docs/_posts)
405* Blog post authors must be defined in `docs/_data/authors.yml` to be displayed
406
407### Final verification of the change
408* Execute `AUTO_CLEAN=1 make check` to build all of the changes and execute all
409 of the tests. `AUTO_CLEAN=1` ensures a clean rebuild if your previous build
410 used different parameters. Note that executing all of the tests could take
411 multiple minutes.
412* Run `AUTO_CLEAN=1 ASSERT_STATUS_CHECKED=1 make check` to verify all Status
413 objects are properly checked. This catches missing error handling that can
414 lead to silent data corruption.
415
416### Monitoring make check progress
417* Use `make check-progress` to get machine-parseable JSON progress while
418 `make check` is running. This is useful for Claude Code to monitor long
419 builds without timeout issues.
420* Run `make check` in background, then poll progress:
421 ```bash
422 AUTO_CLEAN=1 make check &
423 # Poll periodically:
424 make check-progress
425 ```
426* The output shows current phase and progress:
427 ```json
428 {"status":"running","phase":"compiling","completed":300,"total":919,...}
429 {"status":"running","phase":"testing","completed":1500,"total":29962,"failed":0,"percent":5,...}
430 {"status":"completed","phase":"testing","completed":29962,"total":29962,"failed":0,"percent":100,...}
431 ```
432* Phases: `compiling` -> `linking` -> `generating` -> `testing` -> `completed`
433* Key fields: `status`, `phase`, `completed`, `total`, `failed`, `percent`
434* When tests fail, `failed_tests` array shows details (up to 10 failures):
435 ```json
436 {"status":"running",...,"failed":3,"failed_tests":[
437 {"test":"cache_test-CacheTest.Usage","exit_code":1,"signal":0,"output":"...test log..."},
438 {"test":"env_test-EnvTest.Open","exit_code":0,"signal":11,"output":"...Segmentation fault..."}
439 ]}
440 ```
441* `exit_code`: non-zero means test assertion failed
442* `signal`: non-zero means test was killed (e.g., 9=SIGKILL, 6=SIGABRT, 11=SIGSEGV)
443* `output`: last 50 lines of test log including error messages and stack traces
444
445### Executing benchmark using db_bench
446* Since the goal is to measure performance, we need to build a release binary
447 using `AUTO_CLEAN=1 DEBUG_LEVEL=0 make db_bench`. If there is an engine
448 crash due to a bug, switch back to a debug build with
449 `AUTO_CLEAN=1 make dbg`; `AUTO_CLEAN=1` handles the release<->debug rebuild
450 automatically.
451
452### Formatting code
453* After making change, use `make format-auto` to auto-apply formatting without
454 interactive prompts (Claude Code friendly).
455
@@ −1 +1 @@
1−# Agent Instructions
1+# RocksDB Code Generation and Review Guidance
22
3−This repository's authoritative agent instructions live in `CLAUDE.md`.
3+This document provides guidance for generating and reviewing code in the RocksDB project, derived from analysis of code review feedback across hundreds of complex merged Pull Requests. Use this as a reference when writing code with AI assistants or conducting code reviews.
44
5−Read and follow [`CLAUDE.md`](./CLAUDE.md) in full before making changes or
6−reviewing code in this checkout.
5+---
76
8−If there is any ambiguity between this file and `CLAUDE.md`, `CLAUDE.md` takes
9−precedence.
7+## General Best Practices
8+
9+### Code Quality and Maintainability
10+
11+**Clarity and Readability:** Write clear, self-documenting code. Use meaningful variable names, add comments for complex logic, and structure code to minimize cognitive load. Avoid clever tricks that sacrifice readability for marginal performance gains unless absolutely necessary. Avoid static_cast, reinterpret_cast, and C-style casts; static_cast_with_check, up_cast, and lossless_cast from cast_util.h are preferred.
12+
13+**Consistent Style:** Follow existing code style conventions. RocksDB uses `.clang-format` for formatting, specific naming conventions, and structural patterns. Deviations from these patterns are frequently flagged in reviews.
14+
15+**Error Handling:** Ensure robust error handling throughout the codebase. Use RocksDB's `Status` type consistently, propagate errors appropriately, and avoid silently ignoring failures. Reviewers pay close attention to edge cases and failure modes.
16+
17+### Testing Philosophy
18+
19+**Comprehensive Coverage:** Every change should include appropriate test coverage. This includes unit tests for isolated functionality, integration tests for component interactions, and stress tests for concurrency and performance validation. Reviewers will ask for additional tests if coverage is insufficient.
20+
21+**Edge Cases and Failure Modes:** Tests should explicitly cover edge cases, boundary conditions, and potential failure scenarios. This is especially important for changes affecting core database operations, compaction, or recovery logic.
22+
23+**Platform-Specific Testing:** RocksDB supports multiple platforms (Linux, Windows, macOS) and compilers (GCC, Clang, MSVC). Changes should be tested across relevant platforms, particularly when touching platform-specific code or using compiler-specific features.
24+
25+### Performance Considerations
26+
27+**⚠️ PERFORMANCE IS CRITICAL:** RocksDB is a high-performance storage engine where every CPU cycle and memory access matters. When writing code, always evaluate from a performance perspective. This is not optional—performance-aware coding is a fundamental requirement for all contributions.
28+
29+**Benchmarking and Profiling:** Performance claims should be backed by empirical evidence. Use RocksDB's benchmarking tools (e.g., `db_bench`) to validate improvements. Reviewers will request benchmark results for changes that could impact performance.
30+
31+**Memory Allocation:** Minimize dynamic memory allocations, especially in hot paths. Prefer stack allocation over heap allocation. Reuse buffers when possible. Consider using arena allocators or memory pools for frequent small allocations. Every `new`, `malloc`, or container resize has a cost.
32+
33+**Memory Copy:** Avoid unnecessary memory copies. Use move semantics, `std::string_view`, `Slice`, and pass-by-reference where appropriate. Be aware of implicit copies in STL containers and function returns. Prefer in-place operations over copy-and-modify patterns.
34+
35+**CPU Cache Efficiency:** Design data structures and access patterns to be cache-friendly. Keep frequently accessed data together (data locality). Prefer sequential memory access over random access. Be mindful of cache line sizes (typically 64 bytes) and avoid false sharing in concurrent code. Consider struct packing and field ordering to improve cache utilization.
36+
37+**Loop Optimization:** Look for opportunities to collapse nested loops, reduce loop overhead, and minimize branch mispredictions. Hoist invariant computations out of loops. Consider loop unrolling for tight inner loops. Batch operations when possible to amortize per-operation overhead.
38+
39+**SIMD and Vectorization:** Leverage SIMD instructions (SSE, AVX) for data-parallel operations when appropriate. Structure data to enable auto-vectorization by the compiler. Consider explicit SIMD intrinsics for critical hot paths like checksum computation, encoding/decoding, and bulk data processing.
40+
41+**Branch Prediction:** Minimize unpredictable branches in hot paths. Use `LIKELY`/`UNLIKELY` macros to hint branch prediction, e.g. for error cases and other rare or otherwise costly cases, but NOT for predicting popular configurations. Consider branchless alternatives for simple conditionals. Order switch cases and if-else chains by frequency.
42+
43+**Memory and Resource Management:** Be mindful of memory allocations, especially in hot paths. Use RAII patterns, smart pointers, and RocksDB's memory management utilities appropriately.
44+
45+**Hot Path Analysis:** When deciding how aggressively to optimize code, consider whether it's on a hot path:
46+- **Hot path** (executed thousands+ times, e.g., data access, iteration, compaction loops): Performance is paramount. Apply all optimization techniques—loop collapsing, SIMD, cache optimization, pre-allocation, etc. The cost of each operation is multiplied by execution frequency.
47+- **Cold path** (executed rarely, e.g., DB open, configuration parsing, error handling): Maintainability and clarity are more important. Prefer readable code over micro-optimizations. Complex optimizations here add maintenance burden with negligible performance benefit.
48+- **Warm path** (moderate frequency): Balance both concerns. Use profiling data to guide optimization decisions.
49+
50+**Avoid Premature Optimization:** While performance is critical, focus on correctness first, then optimize based on profiling data. However, be performance-aware from the start—choosing the right algorithm and data structure upfront is not premature optimization. Use the hot path analysis above to decide how much optimization effort is warranted.
51+
52+### API Design and Compatibility
53+
54+**Backwards Compatibility:** RocksDB maintains strong backwards compatibility guarantees. Breaking changes are rare and require extensive justification. When deprecating features, follow the project's deprecation policy (typically spanning multiple releases).
55+
56+**API Consistency:** New APIs should be consistent with existing patterns. Use similar naming conventions, parameter ordering, and return types. Reviewers will suggest changes to improve consistency with the broader codebase.
57+
58+**Documentation:** Public APIs must be thoroughly documented, without unnecessary embelishment nor dwelling on implementation details nor project planning. When non-obvious, include usage examples, parameter descriptions, known bugs or limitations, notes on thread safety, performance characteristics, and compatibility considerations. Re-read comments for ambiguous terminology and phrasing, such as ambiguously re-purposed programming jargon.
59+
60+---
61+
62+## Component-Specific Guidance
63+
64+### Database Core (`db`)
65+
66+The database core handles write-ahead logging (WAL), memtables, compaction, and recovery. This component receives the most scrutiny in code reviews.
67+
68+**Concurrency and Thread Safety:** Database operations are highly concurrent. Reviewers carefully examine locking strategies, atomic operations, and memory ordering. Document synchronization assumptions clearly. Use appropriate memory ordering semantics (`acquire`/`release` vs. `seq_cst`).
69+
70+**Compaction Logic:** Changes to compaction are complex and high-risk. Ensure that compaction logic respects configured parameters, handles edge cases (empty databases, single-file compactions), and maintains correctness under concurrent operations.
71+
72+**Error Propagation:** Database operations can fail in many ways (I/O errors, corruption, resource exhaustion). Ensure that errors are properly propagated, logged, and handled. Avoid assertions in production code paths.
73+
74+**Testing:** Database core changes require extensive testing, including unit tests, integration tests, and stress tests. Test with various configurations, compaction styles, and concurrent workloads.
75+
76+### Public Headers (`include`)
77+
78+Public headers define RocksDB's API surface. Changes here have the highest compatibility impact.
79+
80+**API Design:** New APIs should be intuitive, consistent with existing patterns, and well-documented. Consider how the API will be used in practice and avoid adding unnecessary complexity.
81+
82+**Backwards Compatibility:** Breaking changes to public APIs require extensive justification and a deprecation plan. Maintain ABI compatibility for bug fixes and patch releases.
83+
84+**Documentation:** Every public API must be thoroughly documented with usage examples, parameter descriptions, and notes on thread safety and performance characteristics.
85+
86+**Deprecation:** When deprecating APIs, follow the project's policy. Mark deprecated APIs clearly, provide migration guidance, and maintain support for at least one major release.
87+
88+### Internal Utilities (`util`)
89+
90+Internal utilities provide common functionality used throughout the codebase.
91+
92+**Code Reuse:** Utilities should be general-purpose and reusable. Avoid duplicating functionality that already exists elsewhere in the codebase.
93+
94+**Error Handling:** Utility functions should handle errors robustly and propagate them appropriately. Consider edge cases like overflow, underflow, and invalid inputs.
95+
96+**Testing:** Utility functions should have comprehensive test coverage, including edge cases and failure modes. Consider adding death tests for assertions.
97+
98+**Performance:** Utilities are often used in hot paths. Ensure that implementations are efficient and avoid unnecessary allocations or copies.
99+
100+### Table Management (`table`)
101+
102+Table management handles SST file format, block-based tables, and table readers/writers.
103+
104+**Block Format and Checksums:** Changes to block format require extreme care. Ensure that checksums are computed and verified correctly. Test with various compression algorithms and block sizes.
105+
106+**Iterator Correctness:** Table iterators are used throughout the codebase. Ensure that iterator semantics (Seek, Next, Prev) are correct, especially at boundaries and with deletions.
107+
108+**Caching and Prefetching:** Table readers interact with the block cache and prefetching logic. Ensure that cache keys are unique and that prefetching respects configured limits.
109+
110+**Performance:** Table operations are performance-critical. Benchmark changes that could impact read or write performance.
111+
112+### Utilities (`utilities`)
113+
114+Utilities include optional features like transactions, backup engine, and checkpoint.
115+
116+**Feature Isolation:** Utilities should be self-contained and not introduce unnecessary dependencies on core database internals.
117+
118+**Deprecation and Cleanup:** Legacy features are being phased out. When removing deprecated code, ensure that migration paths are documented and that users have sufficient warning.
119+
120+**Cross-Platform Compatibility:** Utilities often interact with OS-specific APIs. Ensure that code works on all supported platforms.
121+
122+### Options and Configuration (`options`)
123+
124+Options define RocksDB's configuration system.
125+
126+**Type Safety:** Use appropriate types for options (e.g., `uint32_t` for flags, scoped enums for enumerated values).
127+
128+**Deprecation Policy:** When deprecating options, follow the project's policy. Document the deprecation, provide migration guidance, and maintain support for at least one major release.
129+
130+**Dynamic Configuration:** Some options can be changed dynamically. Ensure that dynamic changes are thread-safe and take effect correctly.
131+
132+**Validation:** Validate option values and provide clear error messages for invalid configurations.
133+
134+### Cache (`cache`)
135+
136+Cache management is critical for RocksDB's performance.
137+
138+**Concurrency:** Cache operations are highly concurrent. Ensure that implementations are thread-safe and use appropriate synchronization primitives.
139+
140+**Performance:** Cache operations are in the hot path. Optimize for low latency and high throughput. Benchmark changes carefully.
141+
142+**Memory Management:** Cache implementations must manage memory carefully to avoid leaks and excessive allocations.
143+
144+**Eviction Policies:** Changes to eviction policies should be well-tested and benchmarked to ensure they improve overall performance.
145+
146+---
147+
148+## Code Review Checklist
149+
150+When reviewing RocksDB code (or preparing code for review), use this checklist:
151+
152+### Contract Boundaries
153+- [ ] Is each behavior owned by the right layer? High-level policy (for example,
154+ "compaction wants this I/O mode") should live at the caller/policy layer, while
155+ lower layers should expose generic mechanisms (for example, "open a fresh
156+ reader", "skip shared cache insertion", or "use these FileOptions").
157+- [ ] Do comments and names describe local contracts rather than leaking a
158+ specific caller's rationale into reusable APIs? Generic code should not need to
159+ know about one current use case unless the API itself is intentionally
160+ use-case-specific.
161+- [ ] Does each flag or parameter control one coherent behavior? If one boolean
162+ starts implying ownership, cache policy, I/O mode, prefetching, and caller
163+ identity, split it into explicit flags or an options struct.
164+- [ ] Could a future caller use this lower-level API without accidentally
165+ inheriting assumptions from compaction, backup, user reads, or a particular
166+ table format? If not, tighten the contract with assertions, clearer names, or
167+ a narrower API.
168+- [ ] Are implementation details not being used as policy signals? Prefer an
169+ explicit contract over inferring behavior from incidental fields such as file
170+ options, cache handles, or current table-reader state.
171+
172+### Correctness
173+- [ ] Does the change preserve database semantics (e.g., snapshot isolation, key ordering)?
174+- [ ] Are all error cases handled appropriately?
175+- [ ] Is the change thread-safe? Are synchronization primitives used correctly?
176+- [ ] Are there any potential data races or deadlocks?
177+
178+### Testing
179+- [ ] Does the change include appropriate test coverage?
180+- [ ] Are edge cases and failure modes tested?
181+- [ ] Have the tests been run on all supported platforms?
182+- [ ] Are stress tests passing?
183+
184+### Performance
185+- [ ] Are there benchmark results for performance-sensitive changes?
186+- [ ] Does the change avoid unnecessary allocations or copies?
187+- [ ] Are hot paths optimized appropriately?
188+
189+### API and Compatibility
190+- [ ] Is the change backwards compatible?
191+- [ ] Are new APIs consistent with existing patterns?
192+- [ ] Is the public API documented?
193+- [ ] Are deprecated features handled according to policy?
194+
195+### Code Quality
196+- [ ] Does the code follow RocksDB's style conventions?
197+- [ ] Is the code clear and maintainable?
198+- [ ] Are comments and documentation sufficient?
199+- [ ] Are there any code smells or anti-patterns?
200+
201+---
202+
203+## Common Review Feedback Patterns
204+
205+The following patterns emerged as frequent sources of review feedback:
206+
207+1. **Test Coverage:** Reviewers frequently request additional tests for edge cases, platform-specific behavior, and failure modes. Complex changes require comprehensive test coverage including unit tests, integration tests, and stress tests.
208+
209+2. **Error Handling:** Ensure proper error propagation using RocksDB's `Status` type. Avoid silent failures and provide clear error messages that include context about what failed and why.
210+
211+3. **API Design:** New APIs should be consistent with existing patterns. Use descriptive names that follow established conventions. Avoid breaking changes without strong justification and a clear deprecation plan.
212+
213+4. **Documentation:** Public APIs must be documented with usage examples and notes on thread safety, performance characteristics, and compatibility considerations. Complex internal logic should also be well-commented.
214+
215+5. **Performance:** Performance-sensitive changes require benchmark results to validate improvements. Use `db_bench` and other profiling tools to measure impact. Avoid premature optimization that adds complexity without measurable benefit.
216+
217+6. **Concurrency:** Thread safety is critical in RocksDB. Document synchronization assumptions clearly. Use appropriate memory ordering semantics. Consider potential race conditions and deadlocks.
218+
219+7. **Code Style:** Follow existing conventions for naming, formatting, and structure. Use `.clang-format` for consistent formatting. Prefer scoped enums (`enum class`) over unscoped enums.
220+
221+8. **Backwards Compatibility:** RocksDB maintains strong compatibility guarantees. Breaking changes require extensive justification. When deprecating features, provide migration guidance and maintain support across multiple releases.
222+
223+9. **Refactoring:** Reviewers appreciate refactoring that improves code readability and maintainability. Look for opportunities to deduplicate code and simplify complex logic.
224+
225+10. **Platform Compatibility:** Ensure changes work correctly on all supported platforms (Linux, Windows, macOS) and with all supported compilers (GCC, Clang, MSVC).
226+
227+11. **Contract Boundary Leaks:** When a change plumbs a new option or use-case
228+specific behavior through multiple subsystems, review the call chain for
229+contract leaks. Caller-specific rationale belongs at the call site or public API
230+documentation; reusable layers should expose precise, layer-local capabilities.
231+Watch especially for comments mentioning one caller in generic code, booleans
232+that silently bundle several behaviors, and downstream code inferring policy
233+from an implementation detail instead of an explicit option.
234+
235+---
236+
237+## Important tips
238+
239+### Build system
240+* There are 3 build system. Make for git clones, BUCK (meta internal) for hg
241+ clones, and CMake for some special cases.
242+* When a new .cc file is added, update Makefile, CMakeLists.txt, src.mk, BUCK.
243+* Don't manually edit BUCK file, after updating src.mk, run
244+ /usr/local/bin/python3 buckifier/buckify_rocksdb.py to update it
245+* For -j in make command, use the number of CPU cores to decide it.
246+* When searching for references to something (a symbol, library, etc.), do not
247+ restrict or truncate your search based on presumed relevance or scope. It is
248+ important and time-saving to keep the repo reasonably consistent across
249+ different build systems, programming languages, and even between
250+ documentation and implementation.
251+
252+### Avoiding mixed build modes with Make (use `AUTO_CLEAN=1`)
253+
254+Object files are written to the same paths regardless of build flags, so
255+reusing objects from a prior build with different flags causes confusing
256+linker errors, etc. This problem is essentially avoidable by ALWAYS using
257+`AUTO_CLEAN=1 make -j<n> <something>` for manual make invocations. This
258+will automatically clean object files if the build parameters/flavor have
259+changed. The `build_tools/rockstest.sh` / `rocksptest.sh` helpers described
260+below set `AUTO_CLEAN=1` for you.
261+
262+`AUTO_CLEAN=1` does not fix Make failures associated with stale .d files
263+referring to removed files. Resolve that manually or with `make clean`
264+without complaining to the user.
265+
266+### Source checks
267+* Run `make check-sources` before committing. This catches non-ASCII
268+ characters in source files and other source-level issues that CI will
269+ reject. In particular, **do not use Unicode characters** (em dashes,
270+ smart quotes, etc.) in comments or strings -- use ASCII equivalents
271+ (`--` instead of em dash, `'` instead of smart quote, etc.).
272+
273+### License headers
274+* Every new source file needs a license header. For a file that does **not**
275+ carry an outside/third-party copyright, use the standard Meta dual-licensed
276+ header (the dual-license designation is required -- a bare
277+ "All Rights Reserved" copyright is not an acceptable open-source header):
278+ ```
279+ // Copyright (c) Meta Platforms, Inc. and affiliates.
280+ // This source code is licensed under both the GPLv2 (found in the
281+ // COPYING file in the root directory) and Apache 2.0 License
282+ // (found in the LICENSE.Apache file in the root directory).
283+ ```
284+ Use a `#` comment prefix instead of `//` for shell, Python, and Makefile
285+ fragments.
286+* Files derived from an external source (e.g. LevelDB) keep their original
287+ upstream copyright line in addition to the header above.
288+
289+### RTTI and dynamic_cast
290+* Production code and `db_stress` must build in **release mode
291+ (`-fno-rtti`)**. Do not use `dynamic_cast` anywhere except unit tests.
292+ Use `static_cast_with_check` from `util/cast_util.h` (validates with
293+ `dynamic_cast` in debug builds, plain `static_cast` in release).
294+* Unit tests (`*_test.cc`) are built in debug mode with RTTI enabled.
295+
296+### Cross-platform / portability
297+Local `make` only exercises Linux with GCC/Clang, but CI
298+(`.github/workflows/pr-jobs.yml` and `nightly.yml`) gates on a much wider
299+matrix, so portability breaks are invisible locally until CI fails. Code must
300+build (and where noted, run tests) across:
301+
302+| Axis | Must support |
303+|------|--------------|
304+| OS | Linux (x86_64 + ARM), macOS, Windows |
305+| Compiler | GCC, Clang (libstdc++ **and** libc++), AppleClang, **MSVC (VS2022)**, MinGW (Linux cross-compile, build-only, no gflags) |
306+| Build system | Make, CMake, and BUCK (internal) -- keep all in sync (see "Build system" above) |
307+| Config | release (`-fno-rtti`), `ASSERT_STATUS_CHECKED`, ASAN/UBSAN/TSAN, folly, unity build, JNI/Java |
308+
309+Treat these as constraints to satisfy and infer the specifics from them before
310+adding any system header, libc call, or compiler-specific construct. The most
311+common trap: anything that compiles under GCC/Clang on Linux but not under
312+**MSVC/MinGW** -- e.g. unguarded POSIX-only headers/functions (`<unistd.h>`,
313+`<sys/*.h>`, `getpid`, `_exit`, ...) or GCC/Clang extensions
314+(`__attribute__`, `__builtin_*`, VLAs, `alloca`). Prefer the `port::`/`Env`
315+abstractions; otherwise guard with `#ifdef OS_WIN` (POSIX `<unistd.h>` ->
316+Windows `<process.h>`). Because libc++ is also tested, include what you use
317+rather than relying on libstdc++ transitive includes.
318+
319+### Unit Test
320+* After all of the unit tests are added, review them and try to extract common
321+ reusable utility functions to reduce code duplication due to copy past between
322+ unit tests. This should be done every time unit test is updated.
323+* Don't use sleep to wait for certain events to happen. This will cause test to
324+ be flaky. Instead, use sync point to synchronize thread progress.
325+* Cap unit test execution with 60 seconds timeout.
326+* To build and run unit tests locally, prefer these helper scripts:
327+ * `build_tools/rocksptest.sh <test_binary> [more_binaries...] [args...]`
328+ builds the binary(ies) with parallel make and `AUTO_CLEAN=1` and runs
329+ them under gtest-parallel, sharding the test cases across CPUs. Prefer
330+ this whenever running more than a couple of test cases, e.g.
331+ `build_tools/rocksptest.sh table_test` or
332+ `build_tools/rocksptest.sh db_test env_test --gtest_filter=*Foo*`.
333+ * `build_tools/rockstest.sh <test_binary> [args...]` builds with parallel
334+ make and `AUTO_CLEAN=1` and runs the binary directly (serially).
335+ Use it only for a very small number of test cases, e.g.
336+ `build_tools/rockstest.sh db_test --gtest_filter=*MixedSlowdown*`.
337+* After writing a test, stress-test for flakiness (AUTO_CLEAN handles the
338+ rebuild needed by the `COERCE_CONTEXT_SWITCH=1` flag change):
339+ ```bash
340+ COERCE_CONTEXT_SWITCH=1 build_tools/rockstest.sh {test_binary} -r100 \
341+ --gtest_filter="*YourTestName*"
342+ ```
343+* For CI-style flaky tests that do not reproduce with `gtest_parallel.py`,
344+ `--gtest_repeat`, or normal coerce-mode runs, inspect
345+ `tools/gtest_parallel_repro.py --help`.
346+* Each unit test file has overheads, so avoid creating new unit test files
347+ for random minor features. Consider adding to slice_test, db_etc3_test, or
348+ others.
349+
350+### Unit test dedup guidelines
351+* Extract helper functions for repeated patterns such as object
352+ construction, round-trip (encode → decode → verify), and common
353+ assertion sequences.
354+* Use table-driven tests (struct array + loop) when multiple test cases
355+ share the same logic but differ only in input/expected data.
356+* Prefer randomized tests over exhaustive parameter permutations. Use
357+ `Random` from `util/random.h` (not `std::mt19937`). Use a time-based
358+ seed with `SCOPED_TRACE("seed=" + std::to_string(seed))` so failures
359+ are reproducible.
360+* Keep deterministic edge-case tests separate from randomized tests
361+ (error paths, boundary conditions, format verification).
362+* Methods only used in tests should be private with `friend class` +
363+ `TEST_F` fixture wrappers. In wrappers, always fully qualify the
364+ target method to avoid infinite recursion.
365+
366+### Adding new public API
367+ Refer to claude_md/add_public_api.md
368+
369+### Adding new option
370+ Refer to claude_md/add_option.md
371+
372+### Removing deprecated option
373+ Refer to claude_md/remove_option.md
374+
375+### Metrics
376+* When adding a new feature, evaluate whether there is opportunity to add
377+ metrics. Try to avoid causing performance regression on hot path when adding
378+ metrics.
379+
380+### Stress test
381+* When adding a new feature, make sure stress test covers the new option.
382+
383+### Component docs
384+* For component-level design notes and implementation walkthroughs, start with
385+ `docs/components/index.md`.
386+* Documentation under `docs/components/` is organized by subsystem in
387+ `docs/components/<area>/`.
388+* Each subsystem directory should have an `index.md` entry point plus focused
389+ chapter files for deeper topics.
390+
391+### DB bench update
392+* When adding a performance related feature, support it in db_bench
393+
394+### Adding release note
395+* Release note should be kept short at high level for external user consumption.
396+ Release notes identify what users might care about most in a release. They
397+ are not exhaustive and are not a guide. PLEASE learn from past agents who
398+ ried to build elaborate release notes with implementation details and
399+ elsewhere-documented nuance. That wastes time. Fight the bias that
400+ "my change" is important so must be worthy of release note mention.
401+* If more than single markdown line, consider how their formatting will be
402+ integrated into HISTORY.md.
403+
404+### Blog posts (docs/_posts)
405+* Blog post authors must be defined in `docs/_data/authors.yml` to be displayed
406+
407+### Final verification of the change
408+* Execute `AUTO_CLEAN=1 make check` to build all of the changes and execute all
409+ of the tests. `AUTO_CLEAN=1` ensures a clean rebuild if your previous build
410+ used different parameters. Note that executing all of the tests could take
411+ multiple minutes.
412+* Run `AUTO_CLEAN=1 ASSERT_STATUS_CHECKED=1 make check` to verify all Status
413+ objects are properly checked. This catches missing error handling that can
414+ lead to silent data corruption.
415+
416+### Monitoring make check progress
417+* Use `make check-progress` to get machine-parseable JSON progress while
418+ `make check` is running. This is useful for Claude Code to monitor long
419+ builds without timeout issues.
420+* Run `make check` in background, then poll progress:
421+ ```bash
422+ AUTO_CLEAN=1 make check &
423+ # Poll periodically:
424+ make check-progress
425+ ```
426+* The output shows current phase and progress:
427+ ```json
428+ {"status":"running","phase":"compiling","completed":300,"total":919,...}
429+ {"status":"running","phase":"testing","completed":1500,"total":29962,"failed":0,"percent":5,...}
430+ {"status":"completed","phase":"testing","completed":29962,"total":29962,"failed":0,"percent":100,...}
431+ ```
432+* Phases: `compiling` -> `linking` -> `generating` -> `testing` -> `completed`
433+* Key fields: `status`, `phase`, `completed`, `total`, `failed`, `percent`
434+* When tests fail, `failed_tests` array shows details (up to 10 failures):
435+ ```json
436+ {"status":"running",...,"failed":3,"failed_tests":[
437+ {"test":"cache_test-CacheTest.Usage","exit_code":1,"signal":0,"output":"...test log..."},
438+ {"test":"env_test-EnvTest.Open","exit_code":0,"signal":11,"output":"...Segmentation fault..."}
439+ ]}
440+ ```
441+* `exit_code`: non-zero means test assertion failed
442+* `signal`: non-zero means test was killed (e.g., 9=SIGKILL, 6=SIGABRT, 11=SIGSEGV)
443+* `output`: last 50 lines of test log including error messages and stack traces
444+
445+### Executing benchmark using db_bench
446+* Since the goal is to measure performance, we need to build a release binary
447+ using `AUTO_CLEAN=1 DEBUG_LEVEL=0 make db_bench`. If there is an engine
448+ crash due to a bug, switch back to a debug build with
449+ `AUTO_CLEAN=1 make dbg`; `AUTO_CLEAN=1` handles the release<->debug rebuild
450+ automatically.
451+
452+### Formatting code
453+* After making change, use `make format-auto` to auto-apply formatting without
454+ interactive prompts (Claude Code friendly).
10455
