Skip to content

CLAUDE.md

Latest commit

 

History

History
55 lines (42 loc) · 2.73 KB

CLAUDE.md

File metadata and controls

55 lines (42 loc) · 2.73 KB

ml-cpp AI Context

This 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.

For full details, see the individual files in .cursor/rules/:

  • ml-cpp-build-system.mdc — CMake, Gradle, Docker, build acceleration
  • ml-cpp-buildkite-ci.mdc — CI pipelines, API access, known failures
  • ml-cpp-coding-conventions.mdc — Naming, cross-platform, testing patterns
  • ml-cpp-ci-analytics.mdc — Elasticsearch, anomaly detection, AI analysis

Build System

  • CMake is the primary build system. Toolchain files in cmake/ per platform.
  • Gradle (build.gradle) orchestrates macOS and Windows CI builds, invoking CMake.
  • Docker is used for Linux builds (dev-tools/docker/docker_entrypoint.sh).
  • include(CTest) reserves the test target name — our monolithic test target is ml_test.
  • test_individually runs tests via CTest with parallel execution.

Build Acceleration Options

  • -DCMAKE_UNITY_BUILD=ON — combines source files (not effective on all libraries)
  • -DML_PCH=ON — precompiled headers for STL/Boost
  • sccache with GCS backend for persistent compiler caching
  • MSVC uses /Z7 (not /Zi) to avoid PDB serialisation bottleneck

Test Parallelism

  • Formula: numCpus <= 4 ? 2 : ceil(numCpus / 2)
  • Never use wall-clock time for performance assertions — use std::clock() (CPU time)
  • Use process ID for unique temp file names in tests, not random numbers

Coding Conventions

  • Classes: CUpperCamelCase, Methods: lowerCamelCase, Members: m_Name
  • Types: TUpperCamelCase, Test files: CClassNameTest.cc
  • Commit messages: [ML] Short description
  • Use peek() == std::char_traits<char>::eof() for portable end-of-stream detection
  • Avoid anonymous-namespace constants with common names in libraries using unity builds

CI (Buildkite)

  • PR pipeline: ml-cpp-pr-builds (.buildkite/pipeline.json.py)
  • Nightly: ml-cpp-snapshot-builds (.buildkite/branch.json.py)
  • Debug: ml-cpp-debug-build (.buildkite/job-build-test-all-debug.json.py)
  • Platforms: Linux x86_64 (6 vCPU), Linux aarch64 (8 vCPU), macOS aarch64 (4 core), Windows x86_64 (16 vCPU)
  • Vault secrets via .buildkite/hooks/post-checkout
  • Diagnostic steps use: if: "build.state == 'failed'" + soft_fail: true + allow_dependency_failure: true

CI Analytics

  • Build timings indexed into Elasticsearch Serverless (buildkite-build-timings)
  • ML anomaly detection job: build-timing-regressions (high_mean by step_key)
  • PR regression check: compares against 30-day baseline (mean + 2σ)
  • AI failure analysis: Claude diagnoses failures, posts Buildkite annotations
  • Kibana dashboard: "ML-CPP Build Timing Overview"