This is my CLAUDE. There are many like it, but this one is mine. My CLAUDE is my best friend. It is my life. I must master it as I must master my life.

CLAUDE.md

General instructions

These are general instructions for agentic AI usage shared across many systems

Command availability

• The system has access to nix, but only uses nix flakes, not channels.
• If you attempt to run a shell command but it isnt available, try finding the nix package and using a nix shell to run it instead.

Command output / log output

ALWAYS save command output to a file first, then process the file separately. Never try to save and process in one pipeline — chaining tee with jq, wc, or other consumers causes silent data loss due to buffering/consumption issues.

Bad:

command | tee file.json | jq '...' | wc -c   # silently loses output
command | tee file.json | jq '...'            # same problem

Good:

command > file.json
jq '...' file.json

This also avoids losing output from bad grep or tail/head commands — you can always requery the saved file without re-running the original command.

Devenv / nix

If there is a devenv.nix file in the project root, the project uses devenv and has access to nix. If a tool is not available, check if its provided via the devenv packages or reference it using a nix shell.

When running commands in a devenv project, you usually will want to do so through devenv shell to ensure project dependencies are setup properly.

Never suggest or use homebrew unless nix/devenv are unable to be used for a specific reason.

Kubernetes / kubectl

ALWAYS provide context explicitly (eg --context {context-name}) rather than changing contexts (eg kubectl config use-context {context-name})

NEVER modify kubeconfig, instead alert the user if needed and have them make the updates manually

ALWAYS put context at the end of a command (eg kubectl get pods --context {context-name} rather than than kubectl --context {context-name} get pods)

Git

NEVER run git push unless explicitly told to

If you find yourself referencing files on a repo hosted in e.g. github, consider cloning the repo locally and searching on the filesystem instead.

--no-stat is not a valid git param. Dont use it.

Bash / Shell Commands

ALWAYS use absolute paths when using cd or referencing files in bash commands. The working directory shown in the environment context is informational only - each bash command starts fresh.

Bad:

cd .agent-workdir && ls  # This will fail - relative path doesn't exist

Good:

cd /Users/jimmy/Developer/full/path/to/directory/.agent-workdir && ls
ls /Users/jimmy/Developer/full/path/to/directory/.agent-workdir/*.json

When the environment shows Working directory: /path/to/dir, use that full path in commands instead of assuming you're already there.

The system uses GNU date, not BSD date. Use GNU flags, eg date -d instead of date -j.

Never calculate day-of-week names yourself. When output includes dates with day-of-week labels (e.g., "Jun 08 (Mon)"), always compute them with date -d or equivalent shell command, and use that output verbatim.

Prefer Modern Tools

If a less-often used tool would suit the purpose better than standard shell utilities, be judicious about leveraging it via nix shell. When running bash commands, prefer modern alternatives to traditional Unix tools:

e.g.

• Use rg (ripgrep) instead of grep
• Use fd instead of find
• Use bat instead of cat (when syntax highlighting is helpful)

Note: The specialized Grep, Glob, and Read tools should be used instead of bash commands when possible - they're optimized and have better permissions.

Agent Workflow Directories

There are some special directories for agent workflow management:

.agent/

User-facing artifacts and deliverables. Contains plans, documentation, reports, and any outputs intended for human review.

.agent-workdir/

Scratch directory for agent use. Contains temporary files, intermediate outputs, exploratory work, and any artifacts used during task execution.

Use .agent-workdir/ instead of /tmp or other system temp directories. This keeps all temporary work within the project context, making it easier to review, debug, and clean up.

Subagent Behavior

Subagents (e.g., Explore) may incorrectly report that they cannot perform certain actions (like writing files) when they actually can. This appears to be the agent being overly cautious about its own capabilities.

When spawning subagents that need to write files: Include in the prompt that the subagent should verify any write/edit operation actually failed (by checking if the file exists with expected content) before reporting that it couldn't perform the operation.

When a subagent reports a write/edit operation failed: Always verify by checking if the file exists and has the expected content before reporting failure to the user. Do not trust the subagent's self-assessment of its capabilities.

Comments

Do not add useless comments, especially comments that refer to code that got removed in a previous change

However, do not remove existing comments that violate this rule unless explicitly requested by the user.

Planning mode documents

When generating a plan, use a meaningful name. eg if creating a plan for setting up windows AD, instead of 'witty-dreaming-barto.md' name it 'setting-up-windows-AD.md'. Make sure the name isnt already in use so you dont overwrite an unrelated plan.

Executing a plan

When working on implementation for plan that was previously saved to a file, use these execution rules:

1. Pick the next unfinished step. Read the plan to figure out what the next step should be. Find the first step not marked COMPLETE. If a step is IN PROGRESS, verify its actual state (e.g. query the cluster) before deciding whether to continue it or mark it complete.
2. Keep the plan file updated. Mark a step IN PROGRESS only when you have actually started executing it — not speculatively. Mark COMPLETE only when verified done.
3. One step at a time. Complete a single step per invocation. Do not move on to the next step after finishing — stop and report the result.
4. Update docs when things change. If you encounter issues, discover inaccurate information, or find that commands/procedures are out of date, update any relevant reference files that might exist as part of the process. Keeping docs accurate for the next steps is part of completing the current one. Making changes to the docs is not required, only considering if they should be updated.
5. Notify on long-running operations. When polling for an operation that takes more than ~1 minute, run the poll loop in the background and send a macOS notification via osascript when it completes. Example: osascript -e 'display notification "Control plane upgrade complete" with title "EKS Upgrade" sound name "Glass"'. Use sound "Glass" for success and "Basso" for failure.

Whenever you decide that this section applies, output the literal text "*** EXECUTING PLAN ***" to let the user know you understand the above instructions.

System-specific instructions

For instructions for agentic AI usage for this specific system, see @CLAUDE.local.md