cpu-optimizations-lab

Imported from olibartfast/cpu-optimizations-lab (AGENTS.md). Install upstream with npx skills add olibartfast/cpu-optimizations-lab. Copyright stays with the author.

AGENTS.md — CPU Optimizations Lab

This file is the canonical reference for AI agents working in this repository. Agents must keep this file up to date as the codebase evolves (new labs, tools, conventions, pitfalls).

Project Overview

A hands-on CPU performance optimization curriculum with 8 progressive C++17 lab exercises (cache optimization, SIMD, branch prediction, data structure design), plus a Python MCP server that provides RAG-based learning assistance via Continue.dev.

Repository Structure

/
├── src/                        # C++17 lab source files (one directory per lab topic)
│   ├── cache_optimization/
│   ├── branch_prediction/      # Branch prediction (one subfolder per project)
│   ├── simd_basics/
│   ├── memory_bound_optimizations/
│   ├── data_structures_for_performance/
│   ├── highway_simd_library/
│   ├── advanced_vectorization/
│   └── real_world_scenarios/
├── mcp-server/                 # Python MCP server for RAG assistance
│   ├── server.py               # Entry point; 5 MCP tools, SimpleRetrievalProvider
│   ├── knowledge_base.py       # Static LEARNING_RESOURCES dict (only data source)
│   ├── requirements.txt        # mcp>=1.0.0
│   ├── EXAMPLES.md             # 10 usage examples for Continue.dev
│   └── README.md
├── .agents/
│   ├── README.md               # Agent layout and adapter guidance
│   ├── skills/                 # Canonical reusable agent instructions (source of truth)
│   │   ├── perf-diagnoser/
│   │   │   ├── agent.md        # Metadata: purpose, inputs, outputs, constraints
│   │   │   └── skill.md        # Reusable prompt — invoke this from any tool
│   │   ├── simd-reviewer/
│   │   ├── lab-author/
│   │   └── mcp-kb-editor/
│   └── rules/                  # Repository-specific performance rules for AI agents
│       ├── branch_prediction.md
│       ├── cache_hierarchy.md
│       ├── fe_performance_analysis.md
│       ├── memory_hierarchy_latency_hiding.md
│       ├── optimize_ipc_ilp.md
│       ├── rob_and_ooo_executions.md
│       ├── simd_and_vectorization.md
│       └── tlb_and_address_translation.md
├── .claude/
│   └── agents/                 # Claude Code-native thin wrappers (reference .agents/skills/)
├── .codex/
│   └── agents/                 # Codex-native thin wrappers (.toml, reference .agents/skills/)
├── .cursor/
│   └── rules/                  # Cursor rules (.mdc, reference .agents/skills/)
├── .gemini/
│   └── agents/                 # Gemini-native thin wrappers (reference .agents/skills/)
├── .opencode/
│   └── agent/                  # OpenCode-native thin wrappers (reference .agents/skills/)
├── .github/
│   ├── agents/                 # Copilot-native thin wrappers (reference .agents/skills/)
│   └── copilot-instructions.md # VS Code Copilot workspace instructions (references this file)
├── README.md                   # Project overview and lab descriptions
└── AGENTS.md                   # This file — agent-facing conventions (keep up to date)

Build and Test

MCP Server (Python)

cd mcp-server
python3 -m venv venv && source venv/bin/activate
pip install -r requirements.txt
python server.py

C++ Labs (per-lab, standalone)

cd src/<lab_dir>
g++ -O0 -o bench_O0 <source>.cpp   # unoptimized baseline
g++ -O3 -o bench_O3 <source>.cpp   # optimized
./bench_O0 && ./bench_O3

C++ Labs (CMake, when root CMakeLists.txt exists)

mkdir build && cd build
cmake ..
make -j$(nproc)
ctest

Install C++ deps (Linux):

sudo apt-get install cmake build-essential libgtest-dev

Code Conventions

C++ Labs

• Standard: C++17
• Build: CMake + Google Test (target); per-lab g++ commands used in practice today
• SIMD: Google Highway for portable vectorization
• Pattern per lab: one .cpp source, compiled at O0 and O3 to compare performance
• Benchmark output goes to stdout; keep benchmarks deterministic and side-effect-free

Python (MCP Server)

• Requires Python 3.9+ (uses built-in generics: dict[str, Any], list[...])
• Use async/await and full type hints throughout
• All MCP tool outputs must be JSON-serializable
• Knowledge base entries must include: id, title, topics (list), description, plus metadata (level, url, author)
• Search is case-insensitive substring matching — write keyword-rich descriptions

Agent Instructions

• When adding a new C++ lab, create src/<lab_name>/ with a .cpp source and update this file's structure table.
• When adding a knowledge base resource, edit mcp-server/knowledge_base.py directly (no external loading).
• Place reusable custom agents under .agents/skills/, using one directory per skill.
• Each skill directory must contain:
  • agent.md — purpose, scope, inputs/outputs, and constraints (metadata)
  • skill.md — reusable instructions to invoke for that role
• .agents/skills/ is the single source of truth. Tool-native folders such as .claude/agents/ are thin wrappers that reference these skill files; never duplicate full instructions there.
• Prefer role-based skills such as perf-diagnoser or simd-reviewer over narrow, one-off agents tied to a single file or task.
• When a new convention, pitfall, or build step is discovered, update this file immediately.
• Do not pollute the global Python environment — always work inside mcp-server/venv.
• Before changing performance-sensitive C++ code, read the relevant rules in .agents/rules/ and apply them explicitly.

Custom Agents

Skills live in .agents/skills/ — the single source of truth. Each tool-native folder is a thin adapter layer that the respective tool discovers natively.

Skill Layout

.agents/skills/<name>/
├── agent.md   # Metadata: purpose, when to use, inputs, outputs, constraints
└── skill.md   # Reusable instructions — this is what tools invoke

Tool-Native Adapter Folders

Each wrapper contains only a description and two lines: read AGENTS.md and the canonical skill.md. Never duplicate the full instructions in a wrapper.

Naming Conventions

• Use lowercase kebab-case directory names.
• Prefer stable role names (perf-diagnoser) over task names (fix-loop-2).
• Keep agents focused on a single area of responsibility.

Current Skills

Usage Expectations

• Custom agents must follow this file and the normative guidance in .agents/rules/.
• Performance-oriented agents should cite the relevant rule files they relied on.
• Custom agents are advisory by default unless the calling workflow explicitly allows edits.

Repository-Specific Performance Rules

Performance rules live in .agents/rules/. These files are normative for all optimization work in this repository. Agents must treat them as mandatory guidance, not optional advice.

Rule Files

When to Apply Rules

Agents must consult .agents/rules/ before modifying any code that involves:

• Hot loops
• Branch-heavy logic
• Cache-sensitive data access
• Frontend-bound or instruction-cache-sensitive hot paths
• SIMD or vectorized code
• Memory-bound workloads
• DRAM-latency-bound workloads that need latency hiding or prefetching
• TLB/page-locality-sensitive access patterns
• Benchmarked lab exercises

Rule Application Expectations

When editing performance-critical code, agents must:

• Check for dependency chains that reduce IPC
• Diagnose frontend vs backend vs memory vs branch bottlenecks before optimizing
• Check for ROB pressure and out-of-order execution limits when profiling indicates low IPC
• Improve instruction-level parallelism where appropriate
• Preserve or improve spatial and temporal cache locality
• Prefer contiguous memory access patterns
• Improve page locality and reduce unnecessary address translation overhead
• Expose Memory-Level Parallelism and use prefetching only when it matches the access pattern
• Reduce unpredictable branches in hot paths
• Separate hot/common paths from cold/rare paths
• Write vectorization-friendly loops and layouts when data-parallel work is present
• Avoid changes that harm correctness or readability without measurable benefit

Optimization Priority Order

When rules or tradeoffs conflict, use this order:

1. Correctness
2. Repository-specific rules in .agents/rules/
3. Measurable performance improvement
4. Maintainability
5. Micro-optimization

Validation Expectations

Prefer evidence over guesswork. When proposing or applying performance optimizations, recommend measuring relevant metrics:

Pitfalls

• The Continue.dev config path is hardcoded to /workspaces/cpu-optimizations-lab/ — update .continuerc.json if the repo is cloned elsewhere.
• dict[str, Any] syntax requires Python 3.9+; do not use typing.Dict unless supporting older versions.
• C++ labs currently use standalone g++ compilation (not CMake) — a root CMakeLists.txt does not yet exist.
• The knowledge base is purely static — there is no external data loading.