From c4ff9b137c9a2cb8daf7a1cf6b708dc4b0011659 Mon Sep 17 00:00:00 2001
From: Lion - dapplion <35266934+dapplion@users.noreply.github.com>
Date: Tue, 17 Feb 2026 20:26:06 -0700
Subject: [PATCH] Add critical instructions and hooks for Claude Code (#8715)

Co-Authored-By: dapplion <35266934+dapplion@users.noreply.github.com>
---
 .claude/settings.json | 15 +++++++++++++++
 .githooks/pre-commit  |  5 +++++
 CLAUDE.md             |  8 ++++++++
 Makefile              |  6 ++++++
 4 files changed, 34 insertions(+)
 create mode 100644 .claude/settings.json
 create mode 100755 .githooks/pre-commit

diff --git a/.claude/settings.json b/.claude/settings.json
new file mode 100644
index 0000000000..ae426dd254
--- /dev/null
+++ b/.claude/settings.json
@@ -0,0 +1,15 @@
+{
+  "hooks": {
+    "PostToolUse": [
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "echo '\n[Reminder] Run: cargo fmt --all && make lint-fix'"
+          }
+        ]
+      }
+    ]
+  }
+}
diff --git a/.githooks/pre-commit b/.githooks/pre-commit
new file mode 100755
index 0000000000..42a5ca79e0
--- /dev/null
+++ b/.githooks/pre-commit
@@ -0,0 +1,5 @@
+#!/bin/sh
+# Pre-commit hook: runs cargo fmt --check
+# Install with: make install-hooks
+
+exec cargo fmt --check
diff --git a/CLAUDE.md b/CLAUDE.md
index 441c8e4274..79ed344e35 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -2,6 +2,14 @@
 
 This file provides guidance for AI assistants (Claude Code, Codex, etc.) working with Lighthouse.
 
+## CRITICAL - Always Follow
+
+After completing ANY code changes:
+1. **MUST** run `cargo fmt --all && make lint-fix` to format and fix linting issues
+2. **MUST** run `cargo check` to verify compilation before considering task complete
+
+Run `make install-hooks` if you have not already to install git hooks. Never skip git hooks. If cargo is not available install the toolchain.
+
 ## Quick Reference
 
 ```bash
diff --git a/Makefile b/Makefile
index 0995a869f4..9786c17cc9 100644
--- a/Makefile
+++ b/Makefile
@@ -361,3 +361,9 @@ clean:
 	cargo clean
 	make -C $(EF_TESTS) clean
 	make -C $(STATE_TRANSITION_VECTORS) clean
+
+# Installs git hooks from .githooks/ directory
+install-hooks:
+	@ln -sf ../../.githooks/pre-commit .git/hooks/pre-commit
+	@chmod +x .githooks/pre-commit
+	@echo "Git hooks installed. Pre-commit hook runs 'cargo fmt --check'."