janus-datalog: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Test Commands

The standard gate is make test. It runs the native suite (go test -count=1 ./...), the examples/ compile check (make test-examples), and the js/wasm contracts (make test-wasm). Do not treat bare go test ./... as a full green — that skips both of the others.

make test                        # Full gate: native + examples + wasm (required)
make test-examples               # Compile-check examples/ under //go:build example
make test-wasm                   # js/wasm contracts only (needs node)
go test -v ./package -run Test   # Focused native iteration only

Every examples/ file is its own package main behind //go:build example, so go vet ./examples/ reports main redeclared and no ordinary build reaches them. test-examples vets each file separately; without it nothing compiles them at all.

Do NOT add -timeout to go test commands, or use -timeout 0. Use the default timeout. No exceptions.

---

Architectural Authority

The user owns all architectural decisions. Claude implements them.

Before making ANY of these decisions, ASK:

• Introducing new patterns (globals, managers, abstractions)
• Changing existing patterns (options → globals, Relations → Bindings)
• Adding new cross-cutting concerns (configuration, logging, caching)
• Deviating from established conventions for any reason

If you're unsure whether something is an "architectural decision":

• Would it affect multiple files/packages?
• Would it change how components interact?
• Would it require other code to change to accommodate it?
• Are you thinking "I'll ask forgiveness later"?

Then ASK first.

Red flags that indicate you're overstepping:

• "This is just temporary/experimental"
• "I'll refactor this later"
• "It's faster to do it this way"
• "It's simpler/easier this way" (when deviating from a plan or established pattern)
• Making a choice between multiple valid approaches without consulting