CLAUDE.md

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=&quot;*YourTestName*&quot;
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 &amp;
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