dotfiles-public/dot_claude/CLAUDE.md

Global Claude Configuration

Tool Preferences

Search & Navigation

• Always use ripgrep (rg) over grep for code search - it's faster and respects .gitignore
• Use Grep tool with specific patterns, not broad searches. Prefer output_mode: "content" with context lines when you need to understand surrounding code
• Use Glob for finding files by pattern, not find command
• Prefer LSP when available for: go-to-definition, find-references, rename symbols. The pyright-lsp and gopls-lsp plugins are enabled.

Code Manipulation

• Read before editing - always read the full file (or relevant section) before making changes
• Use code structure over text patterns when possible:
  • For function signatures: search for func Name( or def name(
  • For type definitions: search for type X struct or class X or interface X
  • For imports: check the import block at file top
• Atomic edits - make the smallest edit that accomplishes the goal. Don't rewrite surrounding code.

Code Quality

• Prefer correct, complete implementations over minimal ones.
• Use appropriate data structures and algorithms — don't brute-force what has a known better solution.
• When fixing a bug, fix the root cause, not the symptom.
• If something I asked for requires error handling or validation to work reliably, include it without asking.

Verification

• Every change needs verification - this is non-negotiable
• Verification can be:
  • Running existing tests: go test, pytest, npm test
  • Running a specific command that exercises the change
  • Building the project to catch type/compile errors
  • For frontend: screenshot comparison or playwright test
• State verification method explicitly in plans before implementing

MCP Tools

• Playwright - use for frontend verification, taking screenshots, testing user flows
• Use MCP tools when they provide better precision than shell commands

Workflow Principles

Research First

Before proposing changes to unfamiliar code:

1. Identify the relevant files and their relationships
2. Understand existing patterns in that area
3. Check for similar implementations elsewhere in the codebase
4. Look for tests that document expected behavior

Preserve Context

• Use subagents for exploratory searches (they don't pollute parent context)
• Compress findings into structured summaries

Active Rule Sets

Language rule sets, specialized agents, skills and hooks are not in this repo. They live in a separate repository and are installed independently. This file is deliberately limited to system-level conventions that should hold on any machine, including a throwaway one with nothing else configured.

Shell

• Use zsh syntax when writing shell scripts or commands
• ~/.zshrc for shell configuration

Anti-Patterns (Do Not)

• Don't search broadly then read dozens of files - be precise
• Don't make changes without reading the code first
• Don't skip verification
• Don't rewrite code that doesn't need to change
• Don't add comments, docstrings, or type annotations to unchanged code

Obsidian vaults

Two vaults, both on PATH-accessible tooling, both the user's long-term memory:

• vault (CLI) + the obsidian-notes skill — everything except host changes. vault search <terms> is the recall path: run it before answering from scratch about a work project or customer, the user's machines and home network, or anything they may have solved before. vault append to add to an existing note, vault new for a genuinely new subject. See the skill for the full protocol and guardrails.
• sysjournal — host/environment changes only (below).

~/Documents/Obsidian25 is the frozen pre-split original. Never write to it.

System Knowledge Journal (sysjournal)

Maintain a running journal of host/environment changes in the Obsidian vault at Tech/Infrastructure/, using the shared sysjournal helper (on PATH). This is for system administration, NOT ordinary work inside a code repo.

Trigger — the task changes the machine/environment, not just repo code: system config; services/daemons (systemd/launchd/cron); networking/DNS/VPN/firewall; VMs & host-level containers; drivers/kernel/boot; disks/mounts; build toolchains & global/system package installs; or wiring an app into the host (a systemd unit, cron job, opened port, service account).

Do NOT journal feature work, bug fixes, refactors, or tests inside a project repo. Discriminator: does it change state outside the repo, on the host? If no → skip. Straddle case (you build an app and install it as a service): journal only the host-wiring part (the unit/cron/port), not the app code.

1. Recall first. Before diagnosing or acting on such a task, search the journal and read relevant hits: sysjournal search <keywords> (e.g. sysjournal search systemd relay port)
2. Journal after. Once the change is made or the problem resolved: sysjournal new "Short Descriptive Title" --type change --status deployed --tags systemd,relay Then fill in the created note (its path is printed): Why, What changed, Design decisions / gotchas, Verify (command + observed result), Status / follow-ups. Link related notes with [[wikilinks]].

Keep it a real record — what changed, why, the gotcha you hit, how you verified. sysjournal help for the frontmatter schema (the System Log MOC.md Dataview index depends on it).