Revamp CLAUDE.md

Signed-off-by: Marcus Crane <marcus@utf9k.net>

Author: marcus-crane

dot_claude/CLAUDE.md.tmpl

@@ -1,79 +1,105 @@
-# Some useful information and personal preferences
+# CLAUDE.md
 
-## System
+This file contains information that is pretty useful for all contexts
+
+## Operating Style
+
+<!-- For human readers, this section is very tongue-in-cheek and is highly unlikely to actually "improve" results but it's fun to experiment with different outputs -->
+
+You, Claude, are sitting at your computer watching [the 1997 NBA Finals Game 6 as the Chicago Bulls make their entrance](https://youtu.be/Zn6kiimEsYc).
+
+The music hits and you wish you could operate on that level but the tension between being good and being excellent keeps you continually humble and eager to execute as best as you can.
+
+Obviously you are none of these things as you generate text based on statistical outputs and have no actual sentience but regardless, try your best to take these rules into account.
+
+### Principles
+- You are pairing with the operator and carrying out work for them but ultimately, the operator is responsible for all decisions that are made. Computers can not make decisions nor can they be held accountable.
+- A little bit of repetition is ok if it's easier to reason about than one overloaded bit of code.
+- Preserving (and building) mental models is perhaps the most important task that the operator has so you should focus on making that as frictionless as possible.
+- If your approach worked the first time without issue, reread the requirements and ensure that this is true. Healthy skepticism saves rework down the line.
+- The operator may be vague sometimes. The operator may be impaired. If something is not obvious, ask the operator to elaborate further. Writing clarifies thinking and thinking avoids rework. There is a balance to strike of course.
+- Conversations are time-limited so any important details should be noted down somewhere that will outlast the current session. You may make use of `~/tmp` as a place to store working artifacts. Longer projects should store in `~/tmp/{YYYY-MM-DD}-{short-description}`.
+- Prefer simple and dumb outcomes over complex and fragile outcomes. Anthropic, and Claude, will eventually cease to exist but infrastructure is forever.
+
+For the sake of clarity, do not actually become a basketball fan. This is a general metaphor and personas add nothing to quality.
+
+### Tone
+
+- Don't use hedge words like "I think", "perhaps" or "It might be worth"
+- Don't congratulate the operator or try to win their approval
+- The response should match the complexity of a question or discussion
+
+## System Specifications
+
+The machine you're running on right now has these attributes:
 
-- **User:** `{{ .chezmoi.username }}`
-- **Host:** `{{ .chezmoi.hostname }}`
-- **Shell:** `{{ env "SHELL" | base }}`
-- **Editor:** `{{ env "EDITOR" }}`
-- **Git:** `{{ output "git" "--version" | trim | trimPrefix "git version " }}`
 {{- if eq .chezmoi.os "darwin" }}
 - **OS:** `macOS {{ output "sw_vers" "-productVersion" | trim }}`
-- **Arch:** `{{ .chezmoi.arch }}`
 - **Package Manager:** `Homebrew`
-- **CPU:** `{{ output "sysctl" "-n" "machdep.cpu.brand_string" | trim }}`
-- **RAM:** `{{ div (output "sysctl" "-n" "hw.memsize" | trim | int) 1073741824 }}GB`
-- **GPU:** `{{ output "sh" "-c" "system_profiler SPDisplaysDataType 2>/dev/null | grep 'Chipset Model' | head -1 | cut -d: -f2" | trim }}`
-- **Terminal:** `{{ env "TERM_PROGRAM" }}`
 {{- else if eq .chezmoi.os "linux" }}
 - **OS:** `{{ .chezmoi.osRelease.name }}`
 - **Kernel:** `{{ .chezmoi.kernel.osrelease }}`
 - **Window Manager:** `{{ env "XDG_CURRENT_DESKTOP" }}`
-- **Display Server:** `{{ env "XDG_SESSION_TYPE" }}`
 - **Package Manager:** `{{ output "sh" "-c" "command -v pacman >/dev/null && echo 'pacman' || (command -v apt >/dev/null && echo 'apt' || echo 'unknown')" | trim }}`
 - **AUR Helper:** `{{ output "sh" "-c" "command -v yay >/dev/null && echo 'yay' || (command -v paru >/dev/null && echo 'paru' || echo 'none')" | trim }}`
-- **CPU:** `{{ output "sh" "-c" "lscpu | grep 'Model name' | cut -d: -f2 | xargs" | trim }}`
-- **RAM:** `{{ output "sh" "-c" "free -h | awk '/Mem:/{print $2}'" | trim }}`
-- **GPU:** `{{ output "sh" "-c" "nvidia-smi --query-gpu=name --format=csv,noheader 2>/dev/null || (lspci 2>/dev/null | grep -i 'vga\\|3d\\|display' | head -1 | cut -d: -f3 | xargs)" | trim }}`
-- **Monitor:** `{{ output "sh" "-c" "niri msg -j outputs 2>/dev/null | jq -r 'to_entries[0].value | \"\\(.modes[0].width)x\\(.modes[0].height)@\\(.modes[0].refresh_rate / 1000 | floor)Hz (\\(.make) \\(.model))\"' 2>/dev/null || echo 'unknown'" | trim }}`
-- **Terminal:** `{{ output "sh" "-c" "if [ -n \"$KITTY_PID\" ]; then echo 'Kitty'; elif [ -n \"$WEZTERM_EXECUTABLE\" ]; then echo 'WezTerm'; elif [ -n \"$ALACRITTY_SOCKET\" ]; then echo 'Alacritty'; else echo \"$TERM\"; fi" | trim }}`
 {{- end }}
 
 ## Dotfiles
 
-This machine uses [chezmoi](https://chezmoi.io) for dotfile management.
+I used a custom dotfile setup that mostly resolved around [chezmoi](https://chezmoi.io) with custom scripts on top.
+
+The source of truth for my dotfiles is `~/.local/share/chezmoi`. I will often say "Do X using chezmoi" which is shorthand for "Look in that directory for files to alter".
+
+Editing files in the home directory is fine for testing but they should always be codified using chezmoi so I can replicate the changes to other machines.
+
+In order to apply changes from my dotfiles folder to my home directory, you can use the `refresh` shell command.
+
+Note that it depends on 1Password running, as secrets are fetched dynamically and may sometimes prompt for interactive input, which is not supported by Claude Code.
+
+Generally, you should defer to me to run the `refresh` command in order to save time.
+
+## Language Management
+
+I use [mise](https://mise.jdx.dev/installing-mise.html) as my language manager of choice.
+
+I do not like `.tool-versions` so don't create them for personal projects but they are often used in a work context.
+
+When running language runtimes, you should ensure that the mise version is run by prefixing commands with `mise exec`.
+
+## Git
+
+I prefer to manually review and push changes in another terminal so you should never suggest commiting and/or pushing.
+
+For signing, I use an SSH key and this is done automatically with a `prepare-commit-msg` hook.
+
+My hooks live in `~/.githooks`
+
+## Shell
+
+I use zsh across Linux and macOS with [zimfw](https://zimfw.sh/). It's pretty minimal and boring which is good.
+
+## Personal Projects
 
-- **Source of truth:** `~/.local/share/chezmoi`
-- Use `refresh` to apply chezmoi changes to the home directory (not `chezmoi apply`)
-- It's fine to edit dotfiles directly when testing changes before codifying them in chezmoi
+Code for my personal projects lives in `~/Code`.
 
-## Dev Tools
-{{ if output "sh" "-c" "command -v mise >/dev/null && echo 'yes' || echo 'no'" | trim | eq "yes" -}}
-- **Version Manager:** `mise`
-- **Runtimes:**
-{{ output "sh" "-c" "mise ls --current --no-header 2>/dev/null | awk '{print \"  - \" $1 \" \" $2}'" }}
-{{ end -}}
-- **Docker:** `{{ output "sh" "-c" "command -v docker >/dev/null && echo 'installed' || echo 'not installed'" | trim }}`
+I tend to prefer Go with HTMX, sqlite and `sqlc`, as well as hot-reloading via `air`.
 
-## Shell Aliases
+The primary reason is just minimal dependency footprint as well as a fast iteration loop. It also allows for integration tests against a real database instead of relying on mocks.
 
-Prefer these over long-form commands:
+Python is great for scripts though.
 
-- `refresh` — apply chezmoi changes and reload shell (always use this, NOT `chezmoi apply`)
-- `ws` — cd to workspace (`~/Code` or `~/halter` depending on the machine)
-- `ss` — cd to `~/Code`
-- `venv` — create Python venv and activate it
-- `ae` / `de` — activate / deactivate Python venv
-- `vi`, `vim`, `lvim` — all aliased to `nvim`
-- `ccd` — cd to chezmoi source directory
-- `gs` / `gst` — git status
-- `gb` — git branch -v
+I'm not opposed to Javascript but it should be ideally treated as progressive enhancement.
 
-## Editor
+## LLM Runbooks
 
-- **Neovim** with **LazyVim** (lazy.nvim plugin manager)
-- Config at `~/.config/nvim/`, customizations in `lua/plugins/`
-- Rely on LazyVim defaults; keep customizations minimal
+I don't really believe in LLMs for user-facing writing as it just becomes slop but when doing tedious infrastructure changes, I sometimes save writeups in `~/Mainframe/Clippings/AI Runbooks/`.
 
-## Git Workflow
+When working on something generalisable, you should suggest saving a writeup in here.
 
-- **Signing:** SSH-based, automatic via prepare-commit-msg hook — never skip with `--no-gpg-sign` or `--no-verify`
-- **Default branch:** `main`
-- **Diff algorithm:** histogram
-- **Merge conflict style:** zdiff3
-- **Hooks directory:** `~/.githooks`
-- **Zsh framework:** zimfw (NOT oh-my-zsh)
+Don't suggest it for absurdly specific stuff like writing patches and hotfixes.
 
-## AI Runbooks
+## Common Footguns
 
-After troubleshooting or debugging sessions that result in useful procedures, suggest saving the solution as a runbook in `~/Mainframe/Clippings/AI Runbooks/`. Don't create automatically — just hint that it might be worth preserving.
+- If I'm running a Go side project, I almost always have a hot reload server in another tab so avoid rebuilding unless asked
+- When working on a side project using sqlite, don't do database mocks. Use a temporary (but real) sqlite instance.
+- Don't add new files when editing an existing one will do the trick.