AGENTS.md

Agent Development Guide

A file for guiding coding agents.

Commands

• Build: zig build
• Test (Zig): zig build test
• Test filter (Zig): zig build test -Dtest-filter=<test name>
• Formatting (Zig): zig fmt .
• Fetching New Dependencies zig fetch --save git+https://...

Python Package

• Build native extension: zig build python-bindings -Doptimize=ReleaseSafe
• Build wheel: python -m build --wheel --no-isolation python/
• Dev install: pip install --no-build-isolation -e python/
• Run tests: python python/tests/test_dataloader.py

Directory Structure

• Shared Zig code: *.zig
• Python ABI3 bindings: python/
• Lua LSP type stubs: lua-types/
• Webapp, zig version: ultar_httpd/

Zig documentation and std are authoritative

• Primary sources:
  • Language reference: Zig Language Reference
  • Standard library: Zig std reference
• Rule: Prefer these docs over blogs or search results. Do not use external search engines for topics covered by the official docs.
• Canon: When choosing patterns or idioms, follow approaches demonstrated in std documentation and examples.

Usage guidance

• Look up before coding: Read the relevant language/stdlib section end-to-end before implementing.
• API usage: Cross-check function signatures, error semantics, allocation patterns, and iterators in the std reference.
• Ambiguity: If docs appear ambiguous, re-read the surrounding sections and prefer idioms showcased in std docs/examples.
• Versioning: Assume code targets the docs linked above unless the repository pins a different Zig version.

Zig evolves quickly; keeping to official docs and std patterns ensures correctness and idiomatic style.