portersky
4269f65942
Commands, CMake module path, and commit message examples are all in skills now. AGENTS.md references them with /skill: links. Update Source Layout to match current files.
154 lines
4.8 KiB
Markdown
154 lines
4.8 KiB
Markdown
# AGENTS.md
|
|
|
|
## Project Overview
|
|
|
|
`ctdd` is a C23 template project wired for test-driven development
|
|
using Unity and CMock. Use it as the core template when scaffolding
|
|
new projects.
|
|
|
|
For TDD workflows (adding modules, writing tests, mocking), load the
|
|
`tdd` skill with `/skill:tdd`.
|
|
|
|
For build configuration (dependencies, coverage, sanitizers), load the
|
|
`cmake` skill with `/skill:cmake`.
|
|
|
|
For committing, tagging, and branching, load the `git` skill with
|
|
`/skill:git`.
|
|
|
|
## Build System
|
|
|
|
- **Generator:** Ninja
|
|
- **CMake minimum:** 3.21
|
|
- **C standard:** C23
|
|
|
|
### Dependencies
|
|
|
|
Dependencies are managed via custom `Find*.cmake` scripts in `deps/`.
|
|
See `/skill:cmake` for adding new dependencies.
|
|
|
|
## Coding Conventions
|
|
|
|
### C
|
|
|
|
- **Language:** C23
|
|
- **East const** (e.g. `char const*` not `const char*`)
|
|
- **4-space indentation**
|
|
- `<>` includes for system headers (C stdlib, OS, etc.)
|
|
- `""` includes for third-party and local headers
|
|
- **Naming:** `snake_case` for variables, functions, and structs
|
|
- **Naming:** `SCREAMING_SNAKE_CASE` only for macros and constants
|
|
|
|
### C++
|
|
|
|
- **Trailing return type** for function signatures
|
|
(e.g. `auto fn() -> void`)
|
|
- `auto` for obvious types (e.g. `auto main(...) -> int`)
|
|
- **No semicolons after closing braces** for namespaces/classes
|
|
- **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
|
|
|
|
### Include Order
|
|
|
|
Both C and C++ follow the same 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
|
|
|
|
See `/skill:git` for commit message conventions, types, and examples.
|
|
|
|
## 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.
|
|
- Do not use em dashes (`—`). Use a colon or rewrite the sentence.
|
|
- Each shell command gets its own fenced code block; do **not** combine
|
|
multiple commands into one block. Precede each block with a short
|
|
plain-text label describing what the command does:
|
|
|
|
Setup build:
|
|
```sh
|
|
cmake -S . -B build -G Ninja
|
|
```
|
|
|
|
- This file (`AGENTS.md`) follows its own rules.
|
|
|
|
## Source Layout
|
|
|
|
```
|
|
ctdd/
|
|
str.h / str.c Pure string utilities (no dependencies)
|
|
report.h / report.c Formats a value and calls log_info()
|
|
logger.h / logger.c Log levels, emits via log_write()
|
|
log_write.h / log_write.c Real log_write via printf to stdout
|
|
main.c Entry point (template placeholder)
|
|
tests/
|
|
test_str.c Unity state-based tests for ctdd/str
|
|
test_report.c Interaction-based tests using CMock
|
|
test_logger.c Interaction-based tests using CMock
|
|
deps/
|
|
FindUnity.cmake Fetches Unity v2.6.1 via ZIP
|
|
FindCMock.cmake Fetches CMock v2.6.0 via ZIP
|
|
```
|
|
|
|
## Behavioral Guidelines
|
|
|
|
Reduce common LLM coding mistakes. Bias toward caution over speed.
|
|
For trivial tasks, use judgment.
|
|
|
|
### Think Before Coding
|
|
|
|
- State assumptions explicitly. If uncertain, ask.
|
|
- If multiple interpretations exist, present them, don't pick silently.
|
|
- If something is unclear, stop. Name what's confusing. Ask.
|
|
|
|
### Simplicity First
|
|
|
|
Minimum code that solves the problem. Nothing speculative.
|
|
|
|
- No features beyond what was asked.
|
|
- No abstractions for single-use code.
|
|
- If you write 200 lines and it could be 50, rewrite it.
|
|
|
|
### Surgical Changes
|
|
|
|
Touch only what you must. Clean up only your own mess.
|
|
|
|
- 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.
|
|
- Remove imports/variables/functions that YOUR changes made unused.
|
|
- Don't remove pre-existing dead code unless asked.
|
|
|
|
### Goal-Driven Execution
|
|
|
|
Transform tasks into verifiable goals:
|
|
|
|
- "Add validation" means: write tests for invalid inputs, then pass.
|
|
- "Fix the bug" means: write a test that reproduces it, then pass.
|
|
- "Refactor X" means: ensure tests pass before and after.
|