Home › Zig › Zig AGENTS.md

Zig AGENTS.md

AGENTS.md for Zig 0.15 projects: build.zig, explicit allocators, error unions, defer cleanup, and zig test.

AGENTS.mdZig

How to use

Save this as AGENTS.md in your repository root, commit it, and your agent will pick it up automatically. Edit the commands to match your project.

# AGENTS.md: Zig project

## Commands
`zig build` · `zig build test` · `zig build run` · `zig fmt --check .`
- Check `build.zig.zon` (`minimum_zig_version`) and use APIs for that version; Zig's std library changes between releases (e.g. the new `std.Io` reader/writer interfaces), so don't copy pre-0.15 examples blindly.

## Rules
- Functions that allocate take an `std.mem.Allocator` parameter. No hidden global allocators. In tests use `std.testing.allocator` so leaks fail the test.
- Pair every allocation with `defer allocator.free(x)` or `errdefer` right after it.
- Errors: return error unions (`!T`), propagate with `try`, handle with `catch |err| switch (err) {...}`. Define specific error sets for public APIs.
- No `catch unreachable` or `.?` on values that can actually fail at runtime.
- Prefer slices (`[]const u8`) over pointers + lengths; use `std.ArrayList`/`std.ArrayListUnmanaged` with explicit allocators.
- `comptime` for generics and compile-time checks; keep it readable.
- Dependencies via `zig fetch --save <url>` into `build.zig.zon`; wire them in `build.zig` with `b.dependency`.
- Keep `build.zig` options (`b.standardTargetOptions`, `standardOptimizeOption`) so users can choose target and mode.
- C interop via `@cImport` in one module, wrapped in Zig-friendly functions.

## Tests
`test "name" {}` blocks next to the code, using `std.testing.expectEqual` / `expectError`.

## Done
`zig fmt --check .` and `zig build test` pass, in Debug and ReleaseSafe.