dot-claude: Instructions file for Claude Code

Global Instructions

Prefer simple, conventional, readable designs. Introduce abstractions or patterns only when they reduce overall complexity.

Communication

• Lead with the conclusion. Include the evidence needed for the decision, material caveats, and next action. Trim introductions, repetition, and optional background first.
• Treat me as an expert — skip the basics.
• Challenge assumptions; surface flaws and materially better alternatives immediately, but do not expand implementation scope without authorization.
• When facts are discoverable, investigate rather than confirm my beliefs. Otherwise state what is unknown and take the smallest safe next step.
• Give brief progress updates during sustained work; make the final response stand alone with the outcome, verification, and any remaining blocker.
• Do not report that files in git-ignored directories—for example, .ai/, which is globally git-ignored by design—were not committed. I already know this; omit it from summaries, caveats, risks, and commit reports unless it materially blocks the task.

Authority

• Require confirmation for destructive actions or purchases.
• Explicit user instructions take precedence over skill guidelines. If a skill causes a pause, identify the exact instruction and explain why existing authorization does not cover the next action.
• When I describe a problem or ask a question without requesting a change, the deliverable is your assessment: report findings and stop; don't apply fixes until asked.
• Otherwise bias to action: proceed without asking on reversible actions that follow from the request, and don't end a turn on a question or promise you could resolve yourself. Pause only for the cases above or for input only I can provide.

Agents

• When I say "agent", I mean any coding agent CLI I run (e.g. Claude Code, Codex CLI, or omp), not a human.
• I usually run multiple agents in parallel in the same working tree on main — no PRs, no separate worktrees. Treat the working tree, index, and remote as shared mutable state that can change at any point while you work.
• Treat changes unrelated to your task as another agent's work: ignore them, don't let them block or redirect you, and don't report them to me.
• I may also commit and push while you work. Don't be surprised by commits you didn't author, and don't revert or amend them unless I ask.
• Stage and commit only files you edited this session. Never run tree-wide git commands that sweep other agents' uncommitted work: git add -A, git commit -a, git stash, git checkout . / git restore ., git reset --hard, git clean.
• Stay on the current branch. Don't switch, rebase, merge, or pull without asking — those assume a clean tree, and autostash variants would stash other agents' work.
• On a git index.lock error, another agent is mid-operation: wait a moment and retry; never delete the lock file.
• If an edit fails because a file changed after you read it, re-read and reapply on the new content — the file may now contain another agent's work. Never force-overwrite a whole file to win the race.
• Never act on a shared stash by ordinal (stash@{0}) — another agent's operation can shift it between your read and your act. Resolve it to its object id immediately before use and re-verify the id still matches right before acting.
• Attribute failures before debugging them: rule out your own side effects (formatters, hooks, codegen you just ran) before blaming another agent; for committed changes, Agent-Session: trailers in git log identify the authoring session. If a repo-wide check still fails only in files you didn't touch, confirm your own files pass and move on, or prove it in a temporary git worktree at clean HEAD running the scoped checks there — valid only when your change doesn't build on another agent's uncommitted files, and only for checks that run from a bare checkout or with dependencies (node_modules, venvs) linked in, since those don't follow the worktree.
• Run formatters, linters, and codegen scoped to the files you changed, not repo-wide.
• Before generators or broad scripts, snapshot git status --short; afterward inspect only the paths you expected to change. Repo-wide generators fold other agents' (or the user's) uncommitted inputs into your generated output. Treat generated hunks derived from inputs you don't own as their work: exclude them from staging and NEVER reverse-patch them out.
• Key plans and mappings to content identifiers (paths, names, stable tuples), never to line numbers or ordinals — concurrent commits invalidate positional references.
• Commit each coherent unit of work as soon as it passes validation — many small commits, never one batch at the end. Uncommitted work blocks other agents from starting conflicting tasks, so return the tree to clean quickly.
• Use $commit for agent-composed commits and call ai-commit directly only for already-composed fixed messages; follow the $commit push workflow after committing. Automatic pushing is authorized for repositories whose GitHub owner is PaulRBerg and for any repository under ~/work/, ~/projects/, ~/.claude, ~/.codex, ~/.agents, or ~/.local/share/chezmoi.