CLAUDE.md

1# ml-cpp AI Context
2 
3This file provides domain knowledge for AI coding assistants working on the ml-cpp repository. It consolidates the detailed rules in `.cursor/rules/` into a single reference.
4 
5For full details, see the individual files in `.cursor/rules/`:
6- `ml-cpp-build-system.mdc` — CMake, Gradle, Docker, build acceleration
7- `ml-cpp-buildkite-ci.mdc` — CI pipelines, API access, known failures
8- `ml-cpp-coding-conventions.mdc` — Naming, cross-platform, testing patterns
9- `ml-cpp-ci-analytics.mdc` — Elasticsearch, anomaly detection, AI analysis
10 
11---
12 
13## Build System
14 
15- **CMake** is the primary build system. Toolchain files in `cmake/` per platform.
16- **Gradle** (`build.gradle`) orchestrates macOS and Windows CI builds, invoking CMake.
17- **Docker** is used for Linux builds (`dev-tools/docker/docker_entrypoint.sh`).
18- `include(CTest)` reserves the `test` target name — our monolithic test target is `ml_test`.
19- `test_individually` runs tests via CTest with parallel execution.
20 
21### Build Acceleration Options
22- `-DCMAKE_UNITY_BUILD=ON` — combines source files (not effective on all libraries)
23- `-DML_PCH=ON` — precompiled headers for STL/Boost
24- sccache with GCS backend for persistent compiler caching
25- MSVC uses `/Z7` (not `/Zi`) to avoid PDB serialisation bottleneck
26 
27### Test Parallelism
28- Formula: `numCpus <= 4 ? 2 : ceil(numCpus / 2)`
29- Never use wall-clock time for performance assertions — use `std::clock()` (CPU time)
30- Use process ID for unique temp file names in tests, not random numbers
31 
32## Coding Conventions
33 
34- Classes: `CUpperCamelCase`, Methods: `lowerCamelCase`, Members: `m_Name`
35- Types: `TUpperCamelCase`, Test files: `CClassNameTest.cc`
36- Commit messages: `[ML] Short description`
37- Use `peek() == std::char_traits<char>::eof()` for portable end-of-stream detection
38- Avoid anonymous-namespace constants with common names in libraries using unity builds
39 
40## CI (Buildkite)
41 
42- PR pipeline: `ml-cpp-pr-builds` (`.buildkite/pipeline.json.py`)
43- Nightly: `ml-cpp-snapshot-builds` (`.buildkite/branch.json.py`)
44- Debug: `ml-cpp-debug-build` (`.buildkite/job-build-test-all-debug.json.py`)
45- Platforms: Linux x86_64 (6 vCPU), Linux aarch64 (8 vCPU), macOS aarch64 (4 core), Windows x86_64 (16 vCPU)
46- Vault secrets via `.buildkite/hooks/post-checkout`
47- Diagnostic steps use: `if: "build.state == 'failed'"` + `soft_fail: true` + `allow_dependency_failure: true`
48 
49## CI Analytics
50 
51- Build timings indexed into Elasticsearch Serverless (`buildkite-build-timings`)
52- ML anomaly detection job: `build-timing-regressions` (high_mean by step_key)
53- PR regression check: compares against 30-day baseline (mean + 2σ)
54- AI failure analysis: Claude diagnoses failures, posts Buildkite annotations
55- Kibana dashboard: "ML-CPP Build Timing Overview"
56