# AGENTS.md ## Project Overview This repository holds the content for a C++ course: lecture material, exercises, and runnable code examples. The language target is modern C++ (C++23). The repository is in a startup phase: no course content exists yet. As material is added, document its layout under "Source Layout". ## Build System No build system is set up yet. When one is added for the course examples, document its configure, build, and test commands here. ## Coding Conventions - **Language:** C++23 - **Primitive types:** use fixed-width type aliases (`u32`, `i64`, ...) instead of `std::uint32_t` etc. - **Trailing return type** for function signatures (e.g. `auto fn() -> void`) - **4-space indentation** - **No semicolons after closing braces** for namespaces/classes - `auto` for obvious types (e.g. `auto main(...) -> int`) - **East const** (e.g. `char const*` not `const char*`) - **Trailing return type** for all function definitions, including operators (e.g. `auto operator=(T&&) noexcept -> T&`) - **Public members first** in class declarations, private members at the bottom - **Private data members** start with `m_` (e.g. `m_state`) - `<>` includes only for system headers (std, OS, etc.) - `""` includes for third-party dependencies (e.g. `fmt`, `nlohmann/json`) - **Naming:** `snake_case` for variables, functions, and classes - **Naming:** `SCREAMING_SNAKE_CASE` only for macros and constants - **Header extensions:** C++ headers use `.hpp`, C headers use `.h` - Include order: 1. C++ standard library headers (``, ``, etc.) 2. _(blank line)_ 3. C standard library headers (``, ``, etc.) 4. _(blank line)_ 5. OS-specific headers (Windows API, POSIX, etc.) 6. _(blank line)_ 7. Third-party dependencies (`"fmt/core.h"`, etc.) 8. _(blank line)_ 9. Local/project headers ## Shell Scripts - Always use `#!/bin/sh` shebang for shell scripts - Scripts must be POSIX compliant (no bashisms) - When providing commands to users: - Windows/PowerShell: use `` ` `` for line continuation - Unix/Linux/macOS: use `\` for line continuation ## Commit Messages Follow the git skill (`.agents/skills/git/SKILL.md`) for commit message format, conventional types, co-author trailers, and the committing workflow. ## Versioning This project follows [Semantic Versioning](https://semver.org) for tagged releases of the course material. - **Patch** (`x.y.Z`): corrections and small updates to existing material. No change is too small. - **Minor** (`x.Y.z`): new lectures, exercises, or other significant additions. - **Major** (`X.y.z`): restructuring that breaks how the material is organized or used. ## Documentation (Markdown) - Wrap normal text and lists at **max 80 columns** (for readability in terminals and editors). - **Exceptions**: Tables and code blocks (` ``` `) can exceed 80 columns when formatting requires it (e.g. trees, alignment). - Use standard Markdown: `**bold**`, `` `inline code` ``, `##` headings, `-` or numbered lists, fenced code blocks with language hints (` ```cpp `, ` ```sh `). - Keep examples concise, up-to-date, and self-documenting. - This file (`AGENTS.md`) follows its own rules. - Do not use em dashes (`—`). Use a colon or rewrite the sentence. ### Auto-Formatting with oxfmt - All markdown files are formatted with **oxfmt** - **Always run `npx oxfmt --write .` after editing any markdown file** - This is mandatory. Do not skip it. Run it before finishing your response - Use `npx oxfmt --check .` to verify formatting before committing - Config is in `.oxfmtrc.json` at the project root - Do not manually fight the formatter. Let oxfmt handle spacing, line breaks, and list alignment ## Source Layout ```text cppcourse/ AGENTS.md # This file .oxfmtrc.json # oxfmt config .agents/ # Agent skills (git workflow) ``` Course content (lectures, exercises, examples) will be added as the course is developed. Document the layout here when it takes shape. ## Behavioral Guidelines Reduce common LLM coding mistakes. These guidelines bias toward caution over speed. For trivial tasks, use judgment. ### 1. Think Before Coding Don't assume. Don't hide confusion. Surface tradeoffs. Before implementing: - State your assumptions explicitly. If uncertain, ask. - If multiple interpretations exist, present them, don't pick silently. - If a simpler approach exists, say so. Push back when warranted. - If something is unclear, stop. Name what's confusing. Ask. ### 2. Simplicity First Minimum code that solves the problem. Nothing speculative. - No features beyond what was asked. - No abstractions for single-use code. - No "flexibility" or "configurability" that wasn't requested. - No error handling for impossible scenarios. - If you write 200 lines and it could be 50, rewrite it. Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify. ### 3. Surgical Changes Touch only what you must. Clean up only your own mess. When editing existing code: - Don't "improve" adjacent code, comments, or formatting. - Don't refactor things that aren't broken. - Match existing style, even if you'd do it differently. - If you notice unrelated dead code, mention it, don't delete it. When your changes create orphans: - Remove imports/variables/functions that YOUR changes made unused. - Don't remove pre-existing dead code unless asked. Every changed line should trace directly to the user's request. ### 4. Goal-Driven Execution Define success criteria. Loop until verified. Transform tasks into verifiable goals: - "Add validation" means: write tests for invalid inputs, then make them pass. - "Fix the bug" means: write a test that reproduces it, then make it pass. - "Refactor X" means: ensure tests pass before and after. For multi-step tasks, state a brief plan: ``` 1. [Step] → verify: [check] 2. [Step] → verify: [check] 3. [Step] → verify: [check] ``` Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification. ## Target Platforms The primary platform for building and running course examples is Linux. Keep examples portable within that constraint unless a lesson specifically targets another platform.