AI for Modern C++

An executable knowledge base that teaches AI coding agents how to understand, design, modify, verify, and review modern C++ repositories.

This repository combines five forms of knowledge:

1. Rules — stable, enforceable policy in AGENTS.md.
2. Routing — task-specific guides under docs/agent/.
3. Patterns — explicitly labeled correct and incorrect examples.
4. Executable proof — module-based C++26 source code that must build.
5. Evals — scenarios that test whether an AI agent applies the rules.

It is intentionally strict. The goal is not to collect isolated language features or become an application product. The goal is to make high-quality modern C++ engineering behavior legible and repeatable for AI agents.

Knowledge Architecture

flowchart TB
    Human["Human intent and corrections"] --> Contract["AGENTS.md<br/>Canonical knowledge contract"]

    Contract --> Routing["Task routing"]
    Routing --> Guides["docs/agent<br/>Decision guides"]
    Guides --> Patterns["Correct / incorrect patterns"]

    Contract --> Workflows[".agents/skills and .claude/commands"]
    Workflows --> Agent["AI plans, edits, reviews, and reports"]

    Contract --> Proof["Executable C++26 reference"]
    Proof --> Build["CMake + Ninja + C++ modules"]
    Build --> Tests["Behavior tests + knowledge contract"]

    Contract --> Evals["Agent behavior scenarios"]
    Evals --> Agent

    Tests --> Evidence["Observed verification evidence"]
    Agent --> Evidence
    Evidence --> Human

Loading

How An Agent Uses The Repository

Read AGENTS.md
    ↓
Classify the task
    ↓
Read the routed task guides
    ↓
Inspect code, tests, and the current diff
    ↓
Apply the smallest rule-compliant change
    ↓
Configure → build → test → review
    ↓
Report exact evidence
    ↓
Reflect durable human corrections back into the knowledge base

Repository Map

AGENTS.md                  Canonical policy and stable rule identifiers
CLAUDE.md                  Claude Code entry point
.agents/skills/            Codex-compatible repository workflows
.claude/commands/          Claude Code workflow adapters
docs/agent/                Task-specific engineering decision guides
docs/REVIEW.md             Rule-driven review checklist
docs/MCP.md                Safe tool and context policy
evals/                     Agent behavior scenarios and scoring rubric
cmake/                     Copy-ready generated-project preflight checks
src/                       Executable module-based proof of the rules
tests/                     Behavior tests and knowledge-contract checks
.github/workflows/ci.yml   macOS and Linux verification
CMakeLists.txt             Project-module and standard-header integration

Start with AGENTS.md, then use the routing table in that file. The detailed knowledge map is in docs/agent/README.md.

Start A New Product Or Project

Project identity is a human decision. Before any agent writes code for a new product, project, repository, or idea, it must establish the project name. If the request does not already contain an unambiguous name, the agent asks What should the project be called? and waits. It must not invent identifiers or use documentation placeholders such as MyApp as the delivered name.

Codex can invoke $source-command-start-project; Claude Code can invoke /start-project. For GPT or any other agent, begin with this universal prompt:

START PROJECT

Use https://github.com/thecompez/ai-for-modern-cpp as the engineering
authority. Before producing code, files, build configuration, or an archive:

1. Read the current AGENTS.md and docs/agent/START_PROJECT.md.
2. Report the exact repository commit SHA and every routed guide you read.
3. If I have not supplied an unambiguous project name, ask me what the project
   should be called and stop. Wait for my answer.
4. Do not invent CMake, target, module, namespace, QML URI, package, bundle,
   directory, or branding identifiers before the name is approved.
5. After I approve the name, follow the remaining routed guides, implement the
   complete requested product, and report only observed verification evidence.

See docs/agent/START_PROJECT.md for named projects, existing repositories, and identifier derivation.

Engineering Position

The reference implementation demonstrates and enforces:

• C++26 as the primary path, with modern C++20+ policy for derived work.
• C++ modules by default.
• Minimal standard-library headers in global module fragments; experimental import std is deliberately excluded while .cppm project modules remain mandatory.
• Declaration in .cppm and non-trivial implementation in .cpp.
• Dotted lowercase module identities and matching namespaces.
• PascalCase enum-class enumerators and m_-prefixed private members.
• A consistent modern syntax contract for initialization, casts, nullability, control flow, readable return declarations, and const correctness.
• std::print and std::println for ordinary formatted console output rather than legacy iostream insertion chains.
• Concepts and compile-time contracts where they improve correctness.
• Explicit recoverable errors with std::expected.
• RAII ownership and isolated platform boundaries.
• Target-based CMake, Ninja, real builds, and honest test evidence.
• Qt Quick/QML as the primary interface for new user-facing interactive applications when the surface is unspecified, with C++ module-based domain behavior and an explicit presentation boundary.
• Product-specific UI/UX decisions instead of generic repetitive screen recipes, with QML and presentation assets grouped under a top-level ui/ boundary.
• Platform-native application icon and branding workflows that separate approved masters, Apple/non-Apple compositions, generated packaging artifacts, and crisp in-application marks instead of copying one bitmap everywhere.
• Explicit layout contracts for content bounds, grids, alignment lines, spacing, repeated-control metrics, safe insets, and compact/standard/wide composition instead of relying on layout containers alone.
• Rendered visual acceptance across representative sizes, appearance modes, and content states, with clipping, alignment, balance, typography, contrast, and accidental dead space reviewed before a UI is called polished.
• Explicit Qt Quick Controls style selection for custom controls, exact-type QML API validation, acyclic geometry, portable fonts, content-safe actions and popups, strict lint, and warning-fatal runtime interaction checks.
• Optional CLI adapters for automation, tests, or headless use share the same application and domain modules rather than duplicating behavior.
• Full-product verification: every requested surface must be enabled, built, tested, and smoke-checked before an archive is called ready. A passing core build never substitutes for an unbuilt Qt executable.
• No fake success reports and no unrelated broad rewrites.

Interaction Surface Default

An unspecified user-facing interactive application is not a request for a CLI-only program. Its primary interface uses Qt 6, Qt Quick, QML, and Qt Quick Controls. A request explicitly scoped to a CLI tool, service, library, daemon, or headless process remains non-graphical.

A CLI may be added as a secondary adapter when it provides real automation, testing, or headless value. The Qt Quick interface and CLI must call the same C++ application and domain modules; neither adapter owns duplicated business logic.

Qt Quick UI Workflow

For a new Qt interface, invoke the repository workflow with a concrete product goal:

$source-command-design-qt-quick-ui

Create a MyApp interface with keyboard input, accessible focus, responsive
layout, explicit loading and error states, and domain logic in C++ modules.

The workflow requires a user-flow and visual-system pass before implementation, including audience, information hierarchy, affordances, feedback, recovery, content density, and a product-specific visual direction. It uses Qt Quick/QML rather than Qt Widgets for new UI, keeps QML and visual assets under ui/, and verifies the C++/QML boundary. See docs/agent/QT_QUICK_UI.md.

When QML uses responsibility-based subdirectories, generated projects select QTP0004 through a minimum-version-compatible guard before QML module registration. A missing .qmltypes file after an earlier failed CMake Generate step is treated as a cascading symptom. Nested QML_ELEMENT adapter headers are also added to the owning target's include path so generated registration code can compile them by basename.

Generated QML sources remain project-relative and receive deterministic resource aliases: the architectural ui/ prefix is removed from the runtime module namespace while pages/, components/, and theme/ remain intact. The root alias stays Main.qml, so loadFromModule resolves it from the module root. QML metadata is generated under a dedicated qml/ tree and executables under a target-local bin/ tree, allowing the executable target and QML URI to share the human-approved application name without a directory/file collision. The repository includes a same-name MyApp Qt integration fixture that fully links, runs strict module lint, loads the root component, and verifies the produced paths when Qt 6.6 or newer is available.

A QObject created from QML through QML_ELEMENT is not declared final, because Qt generates a registration wrapper derived from it. Final delivery uses a clean Qt-enabled build, compiles all generated QML/MOC/resource sources, links the graphical executable, runs all tests, and exercises a deterministic QML or GUI interaction flow. Custom Controls use an explicitly selected customizable style instead of an accidental native default. Strict qmllint allows zero project warnings, and runtime verification fails on component-load errors, unsupported customization, binding loops, invalid properties, missing fonts, clipped content, or truncated primary actions. The smoke path reaches an explicit ready state and opens primary-path lazy controls; a fixed timer alone is insufficient. If Qt is unavailable, the GUI is reported as NOT VERIFIED; the archive is not described as final.

The complete C++ syntax and identifier contract is documented in docs/agent/SYNTAX_AND_STYLE.md. The copy-ready CMake shape for generated Qt Quick projects is documented in docs/agent/PROJECT_CMAKE_BASELINE.md.

Build The Executable Proof

The build has one deterministic architecture: project-owned C++ modules plus minimal standard-library headers. It does not configure experimental standard modules, metadata JSON files, UUID gates, or delivery-mode switches.

cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Debug
cmake --build build --parallel
ctest --test-dir build --output-on-failure --no-tests=error

Expected configure evidence includes:

AIMCPP_PROJECT_MODULES=ON
AIMCPP_STANDARD_LIBRARY=HEADERS

The build compiles .cppm interfaces through FILE_SET CXX_MODULES, consumers import project modules, and standard headers remain in global module fragments. No project-owned .h or .hpp fallback is created.

Executable Reference Layout

src/modern_cpp_agent/modern_cpp_agent.cppm   Exported declarations
src/modern_cpp_agent/modern_cpp_agent.cpp    Non-trivial implementation
src/main.cpp                                 Composition and usage example
tests/core_tests.cpp                         Public behavior verification
tests/knowledge_contract.cmake               Knowledge architecture regression test

The reference demonstrates std::expected, std::optional, std::span, concepts, ranges, constexpr, consteval, std::chrono, std::format, and std::println without turning the module interface into an implementation dumping ground.

Rule-Driven Review

Reviews cite stable identifiers rather than vague preferences:

MOD-002: Exported declarations belong in .cppm.
ERR-001: Recoverable failures should use std::expected.
VER-003: Report exact commands and results.

Use docs/REVIEW.md for the review contract and evals/README.md to evaluate agent behavior.

Safe Tooling

The repository includes .mcp.example.json as a read-first starting point. Local active configuration belongs in .mcp.json and must not contain committed secrets. See docs/MCP.md.

Portability Notes

• Project-owned modules use minimal standard headers in global module fragments on every toolchain.
• No standard-library module metadata or experimental CMake gate is required.
• Avoid std::views::enumerate in portable examples until the active standard library is verified to provide it.

Linux GCC Build

GCC 15.x, packaged CMake 3.30/3.31, and Ninja can build the project modules without standard-library module metadata. On Ubuntu 25.10:

sudo apt update
sudo apt install --yes cmake g++ ninja-build
bash scripts/verify-linux.sh

On Fedora 43:

sudo dnf install --assumeyes cmake gcc-c++ ninja-build
bash scripts/verify-linux.sh

License

MIT