Skip to content

Claude Code usage

INVA engineering is largely operated by Claude Code (and Codex as a controlled specialist). Automation is preferred; consequential actions require explicit human approval. Autonomy is bounded by three mechanisms below.

Instruction levels

Instructions layer from machine-wide to repo to session; where levels overlap, the stricter rule wins. Each repo carries CLAUDE.md (project instructions), RULES.md (human-readable rule index), SECURITY.md, and .claude/rules/ path-scoped rules. Machine-wide policy lives at /etc/claude-code/CLAUDE.md.

Permission levels P0–P5

Actions are classified by risk: P0 observe → P1 local edit → P2 reversible local change → P3 privileged/external (push, merge, installs, deploys, DNS/IAM, secret retrieval) → P4 destructive/irreversible → P5 prohibited. P3/P4 require a per-action approval stating action, reason, target, impact, data affected, downtime, security implications, rollback and post-action validation. Enforcement lives in .claude/settings.json (permission rules and hooks), CI, and — for services — policy code and tests.

Multi-session coordination

Sessions share one filesystem, so overlap is prevented by:

  • The task queue (inva-infrastructure/queue/): durable file-per-task store with POSIX-atomic O_EXCL leases + TTL reaping, a strict schema, and a done-invariant (done ⇔ verified + reviewed + merged). Claim a lease before working a task.
  • Isolated worktrees/branches for parallel work, recorded per task.
  • Recovery anchors / handoff notes updated at every milestone so a disconnected session loses nothing.

Cross-host claiming is intentionally gated off until its arbitration remediations land — keep to a single host.

Memory & context hygiene

Durable project memory is committed and changes only by PR (MEMORY.md), with a source on every claim. Session/auto memory is kept lean — one fact per file, a one-line index — and a periodic guardrail flags index bloat, oversized memory files and large stale transcripts. Compress and start fresh sessions when context grows; never let token spend balloon on an over-long session.

Delegation to Codex

Codex is used as a governed specialist: read-only by default, workspace-write only in an approved worktree, with explicit sandbox and approval policy set per task. Claude owns architecture, decomposition, acceptance criteria and the final review; secrets never appear in prompts or results.