snapcrab: Instructions file for Codex

General guidelines

This document captures code conventions for the snapcrab project. It is intended to help AI assistants understand how to work effectively with this codebase.

Inspired by nextest's AGENTS.md.

For humans

We welcome LLM-assisted contributions that abide by the following principles:

• Aim for excellence. Use LLMs as a quality multiplier. Invest the time savings in improving rigor beyond what you'd do alone. Refactor for clarity. Tackle the tedious parts. Aim for zero bugs.
• Review like a mentor. Treat LLM output as you would code from someone you're mentoring. Read every line, question design decisions, and find ways to break it.
• Write tests. Use LLMs to produce thorough tests — edge cases, boundary conditions, failure modes. Tests are where AI assistance pays off the most.
• Improve docs and errors. Use LLMs to write clear documentation and actionable error messages. Users should never be left wondering what went wrong or what to do next.
• Your code is your responsibility. Do not submit a first draft. If your PR shows signs of not being reviewed, we may decline it outright.

For LLMs

Correctness over convenience

• Model the full error space. No shortcuts or simplified error handling.
• Handle edge cases, including platform differences and overflow conditions.
• Use the type system to encode correctness constraints.
• Prefer compile-time guarantees over runtime checks where possible.

Production-grade engineering

• Test comprehensively, including edge cases and boundary conditions.
• Pay attention to what test facilities already exist and reuse them.
• Getting the details right is really important.

Documentation

• Keep documentation concise. Provide relevant information without overwhelming the reader — don't repeat yourself.
• Doc comments (///) must start with a brief one-line summary. This first line is the title — keep it short and descriptive.
• Use inline comments to explain "why," not just "what."
• Don't add narrative comments in function bodies. Only comment what is non-obvious or needs a deeper "why" explanation.
  • Consider pulling the code to a separate function if it becomes too complex.
• Module-level documentation (//!) should explain purpose and responsibilities.
• Always use periods at the end of code comments.