cppcourse/AGENTS.md

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 (<chrono>, <vector>, etc.)
  2. (blank line)
  3. C standard library headers (<stdlib.h>, <string.h>, 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 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

cppcourse/
  AGENTS.md         # This file
  README.md         # Project docs
  .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.