diff --git a/CLAUDE.md b/CLAUDE.md
index bef8c76..fff02e4 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -122,6 +122,15 @@ _This table is intentionally empty. Populate it as crate decisions are made duri
 
 </chosen-crates>
 
+<shell-conventions>
+
+### Shell & Scripting
+
+- **Never use `python3`** in CLI commands — use shell-native tools or Rust instead.
+- **Always use `jq`** when processing JSON in shell commands or scripts.
+
+</shell-conventions>
+
 </common-patterns>
 
 <secrets-and-configuration>