Documentation-Driven Development

The documentation in docs/ is the single source of truth. Code must conform to documented contracts.

Rule: If a module exists in code, it must have documentation. If documentation exists, it must have code.

Adding a File

1. Write the documentation first — define the contract in a .mdx file
2. Implement the code — conform to the documented contract
3. Update the Makefile — add the new source file
4. Build and verify — make clean && make

Code Style

• C11 standard — no GNU extensions, no compiler-specific builtins
• All warnings enabled — -Wall -Wextra -Wpedantic -Werror
• No global mutable state — all state in structs
• No dynamic dispatch except through the RHI function table
• Explicit resource management — every create has a destroy
• No TODO placeholders — if it's not done, don't commit it

Documentation Style

Follow the musikell documentation conventions:

• Every .mdx file has YAML frontmatter: title, description, slug, author, date, tags
• Section indices (architecture.mdx) link to child pages (architecture/*.mdx)
• Use tables for structured data
• Use code blocks with language tags
• Use active voice and precise technical language

1:1 Documentation-Code Mapping

docs/reference/rhi.mdx          ↔  src/rhi/
docs/reference/backend-cpu.mdx  ↔  src/backend/cpu/
docs/reference/viewport.mdx     ↔  src/viewport/
docs/reference/math.mdx         ↔  src/math/

Commit Messages

Prefix with the affected module:

rhi: add texture handle to backend table
cpu: fix edge function winding for CW triangles
docs: add Vulkan backend contract

Testing

Run the example to verify rendering output:

make run

The example writes frame.ppm, frame_resized.ppm, and frame_wireframe.ppm. Inspect visually or diff against reference images.