thecompez/ai-for-modern-cpp

AI 코딩 에이전트에게 현대 C++ 저장소(repository)를 이해하고, 설계하며, 수정하고, 검증하고, 리뷰하는 방법을 가르치는 실행 가능한 지식 기반입니다.

이 저장소는 다섯 가지 형태의 지식을 결합합니다:

규칙 (Rules)— AGENTS.md에 명시된 안정적이고 강제적인 정책

.라우팅 (Routing)— docs/agent/ 아래의 작업별 가이드

.패턴 (Patterns)— 명시적으로 레이블링 된 올바른 예시와 잘못된 예시

.실행 가능한 증명 (Executable proof)— 빌드되어야 하는 모듈 기반 C++26 소스 코드

.평가 (Evals)— AI 에이전트가 규칙을 적용하는지 테스트하는 시나리오.

이는 의도적으로 엄격합니다. 목표는 고립된 언어 기능을 수집하거나 애플리케이션 제품이 되는 것이 아닙니다. 목표는 높은 품질의 현대 C++ 엔지니어링 동작을 AI 에이전트에게 가독성 있고 반복 가능하게 만드는 것입니다.

flowchart TB
Human["인간 의도 및 수정"] --> Contract["AGENTS.md<br/>표준 지식 계약"]
Contract --> Routing["작업 라우팅"]
...

Read AGENTS.md once for the task
↓
Classify the task and verification level
...

AGENTS.md Canonical policy and stable rule identifiers
CLAUDE.md Claude Code entry point
.agents/skills/ Codex-compatible repository workflows
...

AGENTS.md로 시작하고, 그 파일에 있는 라우팅 테이블을 사용합니다.
자세한 지식 맵은 docs/agent/README.md에 있습니다.

프로젝트의 정체성은 인간의 결정입니다. 어떤 에이전트가 새로운 제품, 프로젝트, 저장소 또는 아이디어에 대한 코드를 작성하기 전에, 반드시 프로젝트 이름을 확립해야 합니다. 요청에 이미 모호하지 않은 이름이 포함되어 있지 않다면, 에이전트는 **

이름 있는 프로젝트, 기존 저장소 및 식별자 도출에 대해서는 docs/agent/START_PROJECT.md를 참고하십시오.

참조 구현체는 다음 사항들을 시연하고 강제합니다:

• 기본 경로는 C++26이며, 파생 작업에는 최신 C++20+ 정책을 적용합니다.
• 기본적으로 C++ 모듈(C++ modules)을 사용합니다.
• 전역 모듈 조각(global module fragments)에서는 최소한의 표준 라이브러리 헤더를 사용하며, 실험적인 import std는 의도적으로 제외하는 반면, .cppm 프로젝트 모듈은 필수입니다. - 선언은 .cppm에서, 비자명한 구현은 .cpp에서 이루어집니다.
• 점으로 구분된 소문자 모듈 식별자와 일치하는 네임스페이스를 사용합니다.
• PascalCase 열거형 클래스(enum-class) 열거자 및 m_ 접두사가 붙은 private 멤버 변수를 사용합니다. - 초기화, 캐스팅, Null 가능성(nullability), 제어 흐름, 가독성 높은 반환 선언, const 정확성 등에 대한 일관된 최신 구문 계약을 유지합니다.
• 일반적인 형식 지정 콘솔 출력에는 레거시 iostream 삽입 체인 대신 std::print와 std::println을 사용합니다. - 정합성을 개선하는 개념(Concepts) 및 컴파일 타임 계약을 적용합니다.
• std::expected를 이용한 명시적 복구 가능한 오류 처리 기능을 제공합니다.
• RAII 소유권 관리 및 격리된 플랫폼 경계를 유지합니다.
• 대상 기반 CMake, Ninja, 실제 빌드, 그리고 정직한 테스트 증거를 제공합니다.
• 적응형 V0–V4 검증: 수정된 프로덕션 코드가 영향을 받는 프로덕션 표면(production surface)을 컴파일하는 반면, 깨끗한 전체 빌드는 실제로 필요한 구조적/최종 게이트에만 예약됩니다. - 기본적으로 단일 에이전트 실행, 경계가 설정된 탐색(bounded discovery), 라우팅된 컨텍스트, 웹 검색 전 로컬 증거, 점진적인 빌드 트리 재사용, 인과적 재실행(causal reruns), 그리고 명시적인 중지 조건 등을 구현합니다.
• 표면이 지정되지 않은 경우 새로운 사용자 대면 인터랙티브 애플리케이션의 기본 인터페이스로 Qt Quick/QML을 사용하며, C++ 모듈 기반 도메인 동작과 명시적인 프레젠테이션 경계를 갖춥니다.
• 일반적이고 반복적인 화면 레시피 대신 제품별 특화된 UI/UX 결정을 따르며, QML 및 프레젠테이션 에셋은 최상위 ui/ 디렉터리 아래에 그룹화합니다.

boundary. - 승인된 마스터, Apple/비(非)Apple 구성, 생성된 패키징 아티팩트, 그리고 곳곳에 비트맵을 복사하는 대신 깔끔한 인앱 마크를 분리하는 플랫폼 네이티브 애플리케이션 아이콘 및 브랜딩 워크플로우.

• 레이아웃 컨테이너에만 의존하는 대신 콘텐츠 경계(content bounds), 그리드, 정렬선, 간격, 반복 제어 메트릭(repeated-control metrics), 안전 인셋(safe insets), 그리고 컴팩트/표준/와이드 구성에 대한 명시적 레이아웃 계약.
• 대표적인 크기, 모양 모드, 콘텐츠 상태 전반에 걸쳐 렌더링된 시각적 수용성 검토 (클리핑, 정렬, 균형, 타이포그래피, 대비, 그리고 우발적인 데드 스페이스까지)를 거쳐 UI가 세련되었다고 간주되기 전에 확인.
• 사용자 정의 컨트롤을 위한 명시적 Qt Quick Controls 스타일 선택, 정확한 타입의 QML API 검증, 비순환 기하학(acyclic geometry), 이식 가능한 폰트, 콘텐츠 안전 액션 및 팝업, 엄격한 린트(lint), 그리고 경고를 치명적인 런타임 상호작용 확인.
• 자동화, 테스트 또는 헤드리스 사용을 위한 선택적 CLI 어댑터는 동작을 중복하는 대신 동일한 애플리케이션 및 도메인 모듈을 공유함.
• 전체 제품 검증: 아카이브가 준비되었다고 간주되기 전에 요청된 모든 표면은 활성화되고, 빌드되며, 테스트되고, 스모크 체크(smoke-checked)되어야 함. 성공적인 핵심 빌드가 구축되지 않은 Qt 실행 파일을 대체할 수는 없음.
• 가짜 성공 보고서와 관련 없는 광범위한 재작성은 없음.

명시적으로 지정되지 않은 사용자 대면 상호 작용 애플리케이션은 CLI 전용 프로그램에 대한 요청이 아님. 이의 주요 인터페이스는 Qt 6, Qt Quick, QML, 그리고 Qt Quick Controls를 사용함. CLI 도구, 서비스, 라이브러리, 데몬 또는 헤드리스 프로세스로 명시적으로 범위가 지정된 요청은 비그래픽 상태로 유지됨.

CLI는 실제 자동화, 테스트 또는 헤드리스 가치를 제공할 때 보조 어댑터로 추가될 수 있음. Qt Quick 인터페이스와 CLI는 동일한 C++ 애플리케이션 및 도메인 모듈을 호출해야 하며, 어느 어댑터도 비즈니스 로직을 중복 소유하지 않음.

새로운 Qt 인터페이스의 경우, 구체적인 제품 목표를 가지고 리포지토리 워크플로우를 실행하십시오:

워크플로우는 구현 전에 사용자 흐름(user-flow) 및 시각 시스템 패스(visual-system pass)를 필요로 하며, 여기에는 대상 고객, 정보 계층 구조(information hierarchy), 어포던스(affordances), 피드백(feedback), 복구(recovery), 콘텐츠 밀도(content density), 그리고 제품별 시각 방향이 포함됩니다. 새로운 UI에는 Qt Widgets 대신 Qt Quick/QML을 사용하며, QML 및 시각 자산은 ui/ 아래에 보관하고 C++/QML 경계를 검증합니다. 자세한 내용은 docs/agent/QT_QUICK_UI.md를 참조하십시오.

QML이 책임 기반 하위 디렉터리(responsibility-based subdirectories)를 사용할 때, 생성된 프로젝트는 QML 모듈 등록 전에 최소 버전 호환성 가드(minimum-version-compatible guard)를 통해 QTP0004를 선택합니다. 이전의 CMake Generate 단계 실패 이후 .qmltypes 파일이 누락되는 것은 연쇄적인 증상으로 간주됩니다. 중첩된 QML_ELEMENT 어댑터 헤더도 소유 타겟(owning target)의 include path에 추가되어 생성된 등록 코드가 basename을 통해 이를 컴파일할 수 있게 합니다.

생성된 QML 소스는 프로젝트 상대적이며 결정론적 리소스 별칭(deterministic resource aliases)을 받습니다: 아키텍처적인 ui/ 접두사는 런타임 모듈 네임스페이스에서 제거되지만, pages/, components/, 및 theme/는 그대로 유지됩니다. 루트 별칭은 Main.qml로 유지되어 loadFromModule이 이를 모듈 루트에서 해석합니다. QML 메타데이터는 전용 qml/ 트리에, 실행 파일은 타겟 로컬 bin/ 트리에 생성되어, 실행 가능한 타겟과 QML URI가 디렉터리/파일 충돌 없이 인간이 승인한 애플리케이션 이름을 공유할 수 있도록 합니다. 이 저장소에는 Qt 6.6 이상 사용 가능 시 동일한 이름의 MyApp Qt 통합 테스트(integration fixture)가 포함되어 있으며, 이는 완전히 링크하고, 엄격 모듈 린트(strict module lint)를 실행하며, 루트 컴포넌트를 로드하고, 생성된 경로를 검증합니다.

QML_ELEMENT를 통해 QML에서 생성된 QObject는 final로 선언되지 않습니다.

, 왜냐하면 Qt가 이를 기반으로 등록 래퍼(registration wrapper)를 생성하기 때문입니다. 최종 배포는 깨끗한 Qt 지원 빌드를 사용하며, 모든 생성된 QML/MOC/리소스 소스를 컴파일하고, 그래픽 실행 파일을 링크하며, 모든 테스트를 실행하고, 결정론적(deterministic) QML 또는 GUI 상호 작용 흐름을 수행합니다. 사용자 정의 컨트롤은 우발적인 네이티브 기본값 대신 명시적으로 선택된 사용자 정의 스타일을 사용합니다. 엄격한 qmllint 검사는 프로젝트 경고가 0개여야 하며, 런타임 검증은 컴포넌트 로드 오류, 지원되지 않는 사용자 정의, 바인딩 루프, 유효하지 않은 속성, 누락된 글꼴, 잘린 콘텐츠 또는 잘린 기본 동작(primary actions)에서 실패합니다. 스모크 패스(smoke path)는 명시적인 준비 상태(ready state)에 도달하며 주요 경로의 지연 로드 컨트롤을 열어야 합니다. 고정 타이머만으로는 불충분합니다. Qt를 사용할 수 없는 경우, GUI는 검증되지 않음 (NOT VERIFIED)으로 보고됩니다.; 아카이브가 최종 버전이라고 설명되지는 않습니다.

완전한 C++ 구문 및 식별자 계약(identifier contract)은 docs/agent/SYNTAX_AND_STYLE.md에 문서화되어 있습니다.

표준 C++ 속성(attributes)은 적절한 경우에만 사용해야 하는 전용 정책, 호환성 매트릭스, 그리고 안전성/ABI 결정 가이드가 docs/agent/ATTRIBUTES.md에 있습니다.

안전 필수(Safety-critical) C++20–C++26 기능은 경계(bounds), 소유권(ownership), 파싱(parsing), 정수 오버플로우(integer overflow), 동시성(concurrency), 계약(contracts), 그리고 외부 API(foreign APIs)를 다루는 증거 기반 가이드가 SAFETY_AND_LIFETIME.md에 있습니다.

더 광범위한, 필요할 때만 사용해야 하는 기능 매트릭스는 CPP20_26_FEATURES.md에 있습니다.

생성된 Qt Quick 프로젝트를 위한 복사 준비가 된 CMake 형태는 docs/agent/PROJECT_CMAKE_BASELINE.md에 문서화되어 있습니다.

빌드는 하나의 결정론적 아키텍처를 가집니다: 프로젝트 소유 C++ 모듈과 최소한의 표준 라이브러리 헤더만 사용합니다. 실험적인 표준 모듈, 메타데이터 JSON 파일, UUID 게이트, 또는 배포 모드 스위치는 구성하지 않습니다.

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)는 다음을 포함합니다:

AIMCPP_PROJECT_MODULES=ON
AIMCPP_STANDARD_LIBRARY=HEADERS

빌드는 .cppm

interfaces를 통해 FILE_SET CXX_MODULES

, 소비자(consumers)
프로젝트 모듈을 가져오고 표준 헤더는 전역 모듈 조각(global module fragments)에 남아 있습니다.
프로젝트 소유의 .h 또는 .hpp 폴백(fallback)은 생성되지 않습니다.

src/modern_cpp_agent/modern_cpp_agent.cppm 내보낸 선언(Exported declarations)
src/modern_cpp_agent/modern_cpp_agent.cpp 비자명한 구현(Non-trivial implementation)
src/main.cpp 구성 및 사용 예제
...

이 레퍼런스는 모듈 인터페이스를 구현 덤프장으로 만들지 않으면서 std::expected, std::optional, std::span, 개념(concepts), 범위(ranges), constexpr, consteval, std::chrono, std::format, 그리고 std::println을 시연합니다.

리뷰들은 모호한 선호도보다는 안정적인 식별자를 인용합니다:

MOD-002: 내보낸 선언은 .cppm에 속해야 합니다.
ERR-001: 복구 가능한 실패는 std::expected를 사용해야 합니다.
VER-003: 정확한 명령어와 결과를 보고하세요.

리뷰 계약(review contract)을 위해 docs/REVIEW.md를, 에이전트 동작 평가를 위해 evals/README.md를 사용하세요.

저장소에는 읽기 전용 시작점으로서 .mcp.example.json이 포함되어 있습니다.
로컬 활성 구성(Local active configuration)은 .mcp.json에 속하며, 커밋된 비밀 정보가 포함되어서는 안 됩니다. docs/MCP.md를 참조하세요.

• 프로젝트 소유 모듈은 모든 툴체인에서 전역 모듈 조각 내 최소한의 표준 헤더를 사용합니다.
• 표준 라이브러리 모듈 메타데이터나 실험적인 CMake 게이트가 필요하지 않습니다.
• 활성 표준 라이브러리가 이를 제공한다고 검증될 때까지 포터블 예제에서 std::views::enumerate 사용을 피하세요.

GCC 15.x, 패키징된 CMake 3.30/3.31, 그리고 Ninja를 사용하여 표준 라이브러리 모듈 메타데이터 없이 프로젝트 모듈을 빌드할 수 있습니다. Ubuntu 25.10에서는:

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

Fedora 43에서는:

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