Zig Project Rules

zigsystemslow-level

Enforces Zig conventions including explicit allocator usage, comptime patterns, error handling, and memory management for safe low-level systems programming.

Целевые файлы

Файл	Формат
.cursorrules	plaintext
CLAUDE.md	markdown

Содержимое

## Zig Project Rules ### Memory & Allocators - Never allocate memory with a global allocator — accept an `std.mem.Allocator` as a parameter - Functions that allocate must document the allocator used and who is responsible for freeing - Pair every allocation with a `defer allocator.free(memory)` or `defer resource.deinit()` - Use `std.heap.ArenaAllocator` for short-lived batches of allocations with a single free - Use `std.heap.GeneralPurposeAllocator(.{})` with leak detection in tests and debug builds - Prefer stack allocation for small, fixed-size data; avoid heap allocation in hot paths ### Error Handling - All fallible functions return error unions: `fn open(path: []const u8) !std.fs.File` - Use `try` to propagate errors up the call stack: `const file = try std.fs.cwd().openFile(path, .{})` - Use `catch` to handle specific errors or provide fallback values: `const n = parseInt(s) catch 0` - Define error sets explicitly with `const MyError = error{ NotFound, InvalidInput }` - Merge error sets with `||`: `const Error = FileError || ParseError` - Do not use `unreachable` to silence error handling — handle or propagate every error ### Comptime - Use `comptime` for generic functions instead of runtime type checking - Pass types as `comptime` parameters to create type-safe generic containers - Use `@TypeOf`, `@typeInfo`, `std.meta` for compile-time type reflection - Generate repetitive code with `comptime` blocks and `inline for` over types - Keep `comptime` logic readable — extract complex comptime logic to named `comptime` functions - Use `@import` with comptime string literals to conditionally import platform-specific code ### Slices & Pointers - Use slices (`[]T`) instead of pointer + length pairs — slices carry their length safely - Use `[]const T` for read-only slices; `[]T` only when mutation is needed - Use `[*]T` (many-item pointers) only when interoperating with C APIs - Validate slice bounds explicitly when indexing — never assume bounds are correct - Use `std.mem.eql` for slice equality — never compare slices with `==` ### Structs & Enums - Use `packed struct` only for hardware registers and C ABI compatibility - Use `extern struct` for C-compatible structs - Define `init()` and `deinit()` methods for structs that manage resources - Use tagged unions (`union(enum)`) for type-safe variant types - Use `std.EnumArray` and `std.EnumMap` for enum-keyed collections ### Naming Conventions - Types (structs, unions, enums): `PascalCase` - Functions, variables, fields: `camelCase` - Constants: `UPPER_SNAKE_CASE` for true compile-time constants; `camelCase` for comptime-known values - Module-level declarations follow the same conventions as their type ### Testing - Write tests with `test "description" { ... }` blocks in the same file as the code under test - Use `std.testing.expect`, `std.testing.expectEqual`, `std.testing.expectError` - Always test error paths — use `std.testing.expectError(error.NotFound, failingFn())` - Run tests with `zig test` and enable leak detection via `GeneralPurposeAllocator` - Test every public function; test edge cases like empty slices, max values, and allocation failures ### Build System - Define build steps in `build.zig` using `b.addExecutable`, `b.addStaticLibrary`, etc. - Use `b.addOptions()` for compile-time build options passed from `zig build` - Use `b.dependency()` for external dependencies managed via `build.zig.zon` - Define separate test and run steps in `build.zig` ### C Interop - Use `@cImport` and `@cInclude` for including C headers - Wrap C APIs in Zig-idiomatic wrappers with proper error handling - Use `c_int`, `c_char`, `c_void` types for C interop; translate with `@intCast`, `@ptrCast` explicitly - Never pass a Zig slice to a C function expecting a pointer — pass `.ptr` and `.len` separately ### Anti-patterns - Do not use `std.debug.panic` for expected errors — reserve it for programming errors (invariant violations) - Do not use optional pointers (`?*T`) when a slice or error union expresses intent better - Do not ignore the return value of functions that return error unions — use `_ = try fn()` if intentional - Do not hardcode allocator choices in library code — always accept `std.mem.Allocator` as a parameter

CLI

npx mindaxis apply zig-rules --target cursor --scope project

Используется в паках

Не используется ни в одном паке

← Правила