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](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
  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.