CLAUDE.md

1# codedb — Agent Instructions
2 
3## Project
4 
5Zig 0.16.x code intelligence server. Tests live in the split `src/test_*.zig` files — one binary per area (see `build.zig`). Build and test with `zig build test`; run a single binary with e.g. `zig build test-index`.
6 
7## Rules
8 
9### Filing Issues
10 
11**Every GitHub issue must include a failing test case.** No exceptions.
12 
13When creating an issue:
14 
151. Write a `test "issue-XX: <description>"` block in the matching `src/test_*.zig` file (e.g. `src/test_index.zig` for index bugs) that **fails** on the current `main` branch
162. Verify it fails: `zig build test 2>&1 | grep "issue-XX"`
173. File the issue via `gh issue create` with this structure:
18   - **Title:** `<module>: <concise description>`
19   - **Body sections:** Problem, Failing Test (the zig test block), Expected, Fix
20   - **Labels:** `bug` for defects, `priority:p0` for crashes, `priority:p2` for correctness
214. Commit the failing test on a branch: `issue-XX-failing-test`
225. Do **not** fix the bug in the same commit as the failing test
23 
24If you cannot write a failing test, the issue is not well-defined enough to file.
25 
26### Test Style
27 
28- Use `std.testing` and `testing.allocator`
29- Use `std.heap.ArenaAllocator` for Explorer tests
30- Always `defer` cleanup (arena.deinit, allocator.free)
31- One test per issue, named `test "issue-XX: <short description>"`
32- Keep tests minimal — only exercise the specific broken code path
33 
34### Code Style
35 
36- No comments or documentation changes unless explicitly asked
37- Prefer minimal, targeted fixes over refactors
38- Follow existing patterns in the module you're editing
39