Skip to content

AGENTS.md

Latest commit

 

History

History
105 lines (81 loc) · 4.75 KB

AGENTS.md

File metadata and controls

105 lines (81 loc) · 4.75 KB

AGENTS.md

Project position

This repository is in closure and hardening mode (archive-ready for low-frequency maintenance). Prefer normalization, defect fixing, and removal of stale or low-signal surfaces over adding new features.

C++ Standards and Style

  • Target: C++17 minimum, C++20 where beneficial
  • Style: enforced via .clang-format (Google style, 100 chars)
  • Memory safety: prefer RAII, smart pointers, avoid raw new/delete
  • Performance: always measure with benchmarks before claiming improvement
  • Concurrency: use std::atomic with explicit memory ordering
  • Header-only design: all library code in include/hpc/ and examples/*/include/ is header-only. Platform-specific code (Windows/POSIX, compiler intrinsics) is hidden behind preprocessor conditionals within headers. This design choice prioritizes ease of integration over compilation speed.

Canonical sources of truth

  1. Current code and build configuration
  2. openspec/ for requirements, change intent, and implementation order
  3. AGENTS.md / CLAUDE.md / .github/copilot-instructions.md for AI workflow guidance

If these sources disagree, fix the drift instead of working around it.

Repository layout

cpp-high-performance-guide/
├── CMakeLists.txt
├── CMakePresets.json
├── cmake/
├── examples/
├── tests/
├── benchmarks/
├── tools/
├── scripts/
├── docs/                  # VitePress site and bilingual learning docs
├── openspec/              # Capability specs and change proposals
├── .githooks/             # Project-managed Git hooks
└── .github/

OpenSpec workflow

  1. Inspect capability specs first in openspec/specs/.
  2. Create or update one change under openspec/changes/<change-id>/ with:
    • proposal.md
    • design.md
    • tasks.md
    • specs/<capability>/spec.md deltas for changed capabilities
  3. Implement in dependency order from tasks.md.
  4. Validate with existing project commands before considering the work complete.
  5. Run /review at phase gates or before merging non-trivial changes.
  6. Archive completed changes into openspec/changes/archive/.

Engineering rules

  • Prefer deleting or archiving stale content instead of preserving redundant surfaces in place.
  • Keep README focused on repository entry and onboarding; use the docs site for the richer narrative.
  • Treat GitHub Pages as a project landing page, not a thin README mirror.
  • Keep user-facing documentation English + Chinese where the surface is meant to be bilingual.
  • Use CMake presets as the default build and test entry points.
  • Keep workflows preset-driven, low-noise, and meaningful. Do not keep jobs that only produce churn.
  • Avoid over-engineering with extra plugins, MCP servers, or automation layers unless they clearly reduce maintenance cost.

Standard commands

# Build and test
cmake --preset=debug && cmake --build build/debug && ctest --preset=debug
cmake --preset=release && cmake --build build/release && ctest --preset=release

# Sanitizers
cmake --preset=asan && cmake --build build/asan && ctest --preset=asan
cmake --preset=tsan && cmake --build build/tsan && ctest --preset=tsan
cmake --preset=ubsan && cmake --build build/ubsan && ctest --preset=ubsan

# Benchmarks
cmake --preset=release && cmake --build build/release
./build/release/benchmarks/<benchmark_name> --benchmark_time_unit=us

# Utilities
./scripts/format.sh
./scripts/setup-hooks.sh

AI tooling policy

  • AGENTS.md: shared repo guidance for Codex-style agents and terminal copilots.
  • CLAUDE.md: Claude Code specific guidance.
  • .github/copilot-instructions.md: GitHub Copilot repository instructions.
  • LSP: prefer clangd backed by compile_commands.json. The .clangd config at the repo root points CompilationDatabase to build/debug; all CMake presets export compile_commands.json via CMAKE_EXPORT_COMPILE_COMMANDS=ON.
  • Review model: use /review before merge or after major cleanup phases.
  • Autopilot strategy: prefer a longer single-session implementation flow over /fleet unless the task is truly parallelizable.

Editor integration

The .vscode/ directory is gitignored and does not exist in the repository. Workspace settings live only in local developer environments. Do not commit .vscode/ content — use the .clangd, .editorconfig, and CMakePresets.json files for machine-readable project conventions instead.

Things to avoid reintroducing

  • HonKit / GitBook-era configuration
  • .kiro/-style legacy spec structures
  • duplicate changelog surfaces with no maintenance value
  • non-blocking CI steps that hide real failures
  • generic AI instructions that do not reflect this repository