zigdoc: Instructions file for Codex

AGENTS.md

Design Priorities

Prioritize correctness, simplicity, and developer experience, in that order. Prefer explicit control flow and the smallest abstraction that clearly models the domain.

Zig Development

Use zigdoc to discover current APIs for the Zig standard library and any third-party dependencies before coding.

Examples:

zigdoc std.fs
zigdoc std.posix.getuid

For imported dependencies, use the module name exposed by build.zig:

zigdoc <module>.<symbol>

Verification

• Run zig build test after code changes; it also checks formatting.
• Use zig build fmt when only a formatting check is needed.
• Run zig build readme when CLI usage or help text changes, and include the resulting README.md update.

Zig Style

• Use camelCase for functions and methods.
• Use lower-case snake_case for variables, parameters, and constants.
• Use PascalCase for types, structs, and enums.
• Prefer const foo: Type = .{ .field = value }; over const foo = Type{ .field = value };.
• Pass allocators explicitly; use errdefer for cleanup on error.
• Keep unit tests close to the code they cover. Ensure zig build test discovers and runs every test-bearing module.
• Avoid abbreviations unless they are established domain terms.
• Include units and qualifiers in names when values could otherwise be ambiguous, such as timeout_ms, buffer_size, or offset_bytes.
• Treat indexes, counts, and byte sizes as distinct concepts; name conversions between them explicitly.
• Use an options struct when positional arguments of the same type are easy to confuse.
• Make division semantics explicit with @divExact, @divFloor, or deliberate ceiling division when rounding affects correctness.

Files and Types

• Treat every .zig file as a namespace. Make the file itself a type only when its root represents one primary stateful abstraction with fields and methods.
• Name a file-backed type PascalCase.zig, import it directly with const Widget = @import("Widget.zig");, and begin it with an optional //! container doc followed by const Widget = @This();. Prefer the concrete type name over Self so signatures remain clear out of context.
• Use lower-case snake_case.zig for namespace modules: related free functions, constants, multiple peer types, or package facades. Export named types from these modules and import them as @import("widget.zig").Widget.
• Do not put a sole pub const Widget = struct { ... }; inside Widget.zig; the file root already provides that container. Conversely, do not create a file-backed type merely to enforce one-type-per-file organization.
• Preferred file start: //! container docs when needed, the file-backed type alias when applicable, imports and local aliases, then scoped logging declarations when needed.