Zig Best Practices

CLAUDE.md の型優先、関数型、エラーハンドリングパターンに従います。このスキルは Zig 固有のイディオムのみを扱います。

型システムパターン

相互に排他的な状態のためのタグ付きユニオン — 複数の nullable フィールドを持つ構造体では許可されない無効な組み合わせを防ぎます:

const RequestState = union(enum) {
    idle,
    loading,
    success: []const u8,
    failure: anyerror,
};

明示的なエラーセット — 正確に何が失敗する可能性があるかを文書化します。anyerror は失敗モードを隠します:

const ParseError = error{ InvalidSyntax, UnexpectedToken, EndOfInput };
fn parse(input: []const u8) ParseError!Ast { ... }

ドメイン ID のための個別型 — コンパイラが異なる ID 型の混合を防ぎます:

const UserId = enum(u64) { _ };
const OrderId = enum(u64) { _ };

Comptime 検証 — 実行時ではなくコンパイル時に無効な構成を検出します:

fn Buffer(comptime size: usize) type {
    if (size == 0) @compileError("buffer size must be greater than 0");
    return struct { data: [size]u8 = undefined, len: usize = 0 };
}

メモリ管理

• アロケータを明示的にすべてのアロケーション関数に渡します。グローバルアロケータ状態を使用しません。
• defer resource.deinit() を取得の直後に配置します — クリーンアップを作成と共存させます。
• エラーパスのクリーンアップには errdefer を使用し、無条件のクリーンアップには defer を使用します。
• バッチ/一時作業にはアリーナアロケータを使用します。すべてを一度に解放できます。
• テストでは std.testing.allocator を使用します — スタックトレース付きリーク報告を行います。

fn createResource(allocator: std.mem.Allocator) !*Resource {
    const resource = try allocator.create(Resource);
    errdefer allocator.destroy(resource);  // runs only on error
    resource.* = try initializeResource();
    return resource;
}

キー規約

• var より const を優先します。生ポインタより スライスを優先します。
• anytype より comptime T: type を優先します。明示的な型はより明確なエラーを生成します。anytype は本当にポリモーフィックなケース (コールバック、std.debug.print スタイル) のみに使用します。
• 網羅的な switch: 本当に不可能なケースについて else を含めてエラーまたは unreachable を返します。
• std.log.scoped(.module_name) を名前空間付きログに使用します。モジュールレベルの const log 定数を定義します。
• より大きな凝集力のあるファイルがイディオム的です — テストは実装の隣、comptime ジェネリクスはファイルスコープにあります。

高度なトピック

• ジェネリックコンテナ (キュー、スタック、ツリー): GENERICS.md を参照
• C ライブラリ相互運用 (raylib、SDL、curl): C-INTEROP.md を参照
• メモリリークのデバッグ (GPA、スタックトレース): DEBUGGING.md を参照

ツーリング

zigdoc — 標準ライブラリと依存関係ドキュメントを閲覧:

zigdoc std.mem.Allocator   # std lib symbol
zigdoc vaxis.Window        # project dependency
zigdoc @init               # create AGENTS.md with API patterns

ziglint — .ziglint.zon 構成による静的解析:

ziglint                    # lint current directory
ziglint --ignore Z001      # suppress specific rule

参考資料

• Language Reference: https://ziglang.org/documentation/0.15.2/
• Standard Library: https://ziglang.org/documentation/0.15.2/std/
• Zig Guide: https://zig.guide/