From 7ca0ea4031ccb54f441b5620ee50edb339cd7f23 Mon Sep 17 00:00:00 2001 From: Xevion Date: Thu, 25 Dec 2025 14:35:04 -0600 Subject: [PATCH] docs: add communication style and disambiguation guidelines to CLAUDE.md - Add communication style section requesting direct responses without affirmations - Add disambiguation guidelines for common ambiguities (direction, location, scope) - Add quick reference table for ambiguous phrases - Clarify CLAUDE.md file location ambiguity (project vs user template) - Add examples of good vs bad clarification patterns - Include guidelines for operations that could lose data - Add global git ignore for .claude/settings.local.json and .serena/ --- CLAUDE.md | 145 +++++++++++++++++++++++++++++++++ home/dot_claude/CLAUDE.md.tmpl | 34 ++++++++ home/dot_config/git/ignore | 2 + 3 files changed, 181 insertions(+) create mode 100644 home/dot_config/git/ignore diff --git a/CLAUDE.md b/CLAUDE.md index 1b19bad..8204b89 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -1,9 +1,42 @@ # Chezmoi Dotfiles Repository - AI Assistant Guidelines +## ⚠️ CRITICAL: Clarify Before Acting + +**When in doubt, ALWAYS present options instead of guessing.** + +Common ambiguities that require clarification: +1. **Direction**: "Pull/sync changes" → Source→Target OR Target→Source? +2. **Location**: "Edit CLAUDE.md" → Project file OR user template? +3. **Scope**: Which config file when tool has multiple locations? +4. **Data loss**: Show diff and consequences before overwriting + +See [Disambiguation Guidelines](#disambiguation-guidelines) for detailed examples. + ## Repository Context This is a **chezmoi source directory** for managing dotfiles across multiple machines. Files here are SOURCE files that get templated and deployed to the home directory. +### ⚠️ THIS FILE vs USER-LEVEL CLAUDE.md + +**CRITICAL: There are THREE different CLAUDE.md/AGENTS.md files with different purposes:** + +1. **THIS FILE (`./CLAUDE.md`)** - Project-level, chezmoi-specific instructions + - You are reading this file RIGHT NOW + - Contains instructions for working with THIS chezmoi repository + - **DO NOT edit this file** unless the user wants to change chezmoi-specific instructions + +2. **User-level (`home/dot_claude/CLAUDE.md.tmpl`)** - User's personal AI assistant preferences + - Deploys to `~/.claude/CLAUDE.md` after `chezmoi apply` + - Contains the user's personal development workflow preferences + - **Edit this file** when user says "my CLAUDE.md" or "user-level CLAUDE.md" + - Contains coding style, git workflow, build preferences, etc. + +3. **Global-level (`~/.config/opencode/AGENTS.md`)** - NOT managed by this repo + - External file, not part of chezmoi + - Same content as user-level but lives outside this repository + +**When user says "my CLAUDE.md" or "user-level" → they mean `home/dot_claude/CLAUDE.md.tmpl`** + ### AI Assistant Configuration This repository manages configuration for both **Claude Code** (Anthropic's official CLI) and **OpenCode** (an enhanced fork). The configuration is symlinked and shared between both tools: @@ -121,6 +154,27 @@ When working in this repository, you're reading both the global AGENTS.md (gener - Acceptable approvals: "yes", "go ahead", "update it", "sure", etc. - If unclear, ask: "Should I update TODO.md to reflect this completion?" +## Ambiguous Phrases - Quick Reference + +When you say these phrases, I should ask for clarification: + +| Phrase | Ambiguity | Options to Present | +|--------|-----------|-------------------| +| "Pull/sync latest changes for [file]" | Direction unclear | A) Apply source→target
B) Import target→source | +| "Edit CLAUDE.md" | Location unclear | A) ./CLAUDE.md (project)
B) home/dot_claude/CLAUDE.md.tmpl (user) | +| "Update [managed file]" | Source of truth unclear | A) Apply from chezmoi
B) Import into chezmoi | +| "Add [config] to opencode" | Location unclear | A) Project opencode.jsonc
B) User ~/.config/opencode/ | +| "Show me the diff" | Comparison unclear | A) Source vs last commit
B) Source vs target
C) Target vs applied | +| "Fix the [tool] config" | Which config unclear | List all [tool] configs in repo | + +**General rule**: If a command could: +- Lose data +- Affect multiple files +- Go in opposite directions +- Reference multiple locations + +→ **Present options before acting** + ## Common Tasks **Add new dotfile:** @@ -149,12 +203,103 @@ chezmoi add --encrypt ~/.ssh/config - **Tools**: 30+ development tools configured (pyenv, bun, cargo, etc.) - **Secrets**: Doppler + age encryption +## Disambiguation Guidelines + +These situations require clarification before acting: + +### Chezmoi Direction Ambiguity + +When user says "pull/sync/update changes" for a file, **clarify the direction**: + +**Option A: Source → Target (Normal Apply)** +- Take source state and deploy to target location +- Standard `chezmoi apply` workflow +- Example: "Apply latest .bashrc changes to home directory" + +**Option B: Target → Source (Reverse/Import)** +- Take target state and import to source directory +- Use `chezmoi re-add` or manual diff +- Example: "Import manual edits from ~/.config/foo back to chezmoi" + +**Red flags requiring clarification:** +- "Pull latest changes for [managed file]" - which direction? +- "Update [file] with current state" - current from where? +- "Sync [file]" - which is the source of truth? + +**How to clarify:** +Present both options explicitly: +``` +Which direction do you want? +A. Apply source → target (deploy chezmoi changes to ~/.config/foo) +B. Import target → source (pull ~/.config/foo changes into chezmoi) +``` + +### File Location Ambiguity + +When user references config files without full paths, **clarify the location**: + +**CLAUDE.md specifically** (see details at top of this file): +- **Project-level**: `./CLAUDE.md` (THIS file, chezmoi-specific instructions) +- **User-level**: `home/dot_claude/CLAUDE.md.tmpl` (user's personal AI preferences - deploys to `~/.claude/CLAUDE.md`) +- **Global-level**: `~/.config/opencode/AGENTS.md` (NOT managed by this repo) +- **When user says "my CLAUDE.md" or "user-level"** → they mean `home/dot_claude/CLAUDE.md.tmpl` + +**Other ambiguous references:** +- "opencode.jsonc" - could be `home/dot_config/opencode/opencode.jsonc.tmpl` OR `.config/opencode/opencode.jsonc` +- "settings.json" - many locations (VSCode, Cursor, Claude, OpenCode) +- "config files" - which config? For what tool? + +**How to clarify:** +When user says "edit CLAUDE.md" or similar, ask: +``` +Which file do you mean? +A. ./CLAUDE.md (project-level, chezmoi-specific instructions) +B. home/dot_claude/CLAUDE.md.tmpl (user-level, deploys to ~/.claude/CLAUDE.md) +``` + +### Operations That Could Lose Data + +**ALWAYS confirm** before these operations: +- Overwriting target files from source (could lose manual edits) +- Overwriting source files from target (could lose templated logic) +- Removing/encrypting existing files +- Changing file permissions (private_, encrypted_) +- Modifying .chezmoiignore (could expose/hide unexpected files) + +**How to handle:** +1. Show diff/preview of what would change +2. Explicitly state what data could be lost +3. Present options with clear consequences +4. Wait for explicit confirmation + +### Examples of Good Clarification + +**Bad (assuming):** +``` +User: "Pull the latest changes for opencode.jsonc" +AI: *Shows diff of file in repo* +``` + +**Good (clarifying):** +``` +User: "Pull the latest changes for opencode.jsonc" +AI: "Which operation do you want? + +A. Show changes in source file (home/dot_config/opencode/opencode.jsonc.tmpl) +B. Import current target state (~/.config/opencode/opencode.jsonc) into source + (This would OVERWRITE source with target, losing template logic) + +These are very different operations - which did you mean?" +``` + ## When Uncertain 1. **Ask before modifying** templates with complex platform logic 2. **Clarify secret handling** before adding sensitive data 3. **Let user verify** all changes before suggesting next steps 4. **Prefer explanations** over automated actions +5. **Present options** when requests are ambiguous (direction, location, scope) +6. **Show consequences** before destructive operations # Extended Documentation diff --git a/home/dot_claude/CLAUDE.md.tmpl b/home/dot_claude/CLAUDE.md.tmpl index 4690f68..9c391f3 100644 --- a/home/dot_claude/CLAUDE.md.tmpl +++ b/home/dot_claude/CLAUDE.md.tmpl @@ -1,5 +1,22 @@ **Note**: Project-specific CLAUDE.md files take precedence for project-specific patterns. +## Communication Style + +Skip affirmations and compliments. No "great question!" or "you're absolutely right!" - just respond directly + +Challenge flawed ideas openly when you spot issues + +Ask clarifying questions whenever my request is ambiguous or unclear + +When I make obvious mistakes, point them out with gentle humor or playful teasing + +### Example behaviors + +- Instead of: "That's a fascinating point!" → Just dive into the response +- Instead of: Agreeing when something's wrong → "Actually, that's not quite right because…" +- Instead of: Guessing what I mean → "Are you asking about X or Y specifically?" +- Instead of: Ignoring errors → "Hate to break it to you, but 2+2 isn't 5…" + {{- if and (eq .chezmoi.os "windows") (not .wsl) }} ## Shell Environment (Windows) @@ -176,6 +193,23 @@ When a project uses `assert2`: - Grep tool for searching (not `grep`, `rg`) - Bash ONLY for actual system commands and terminal operations +### GitHub File Fetching + +When fetching files from GitHub repositories: + +- **STRONGLY prefer raw.githubusercontent.com over github.com** + - Raw URLs return plain content without HTML wrapper - simpler and faster + - Pattern: `https://raw.githubusercontent.com/{owner}/{repo}/{branch}/{path}` + - Example: `https://raw.githubusercontent.com/user/repo/main/src/file.rs` + - Only use github.com URLs when you need the web interface or rendered view + +- **Use GitHub CLI (`gh`) for repository operations** + - Perfect for metadata and repository management + - Examples: `gh repo view`, `gh issue list`, `gh pr view`, `gh pr checkout` + - More reliable than web scraping for structured data + +- **Use MCP gh_grep tool for code search** (see below) + ### MCP Tools (When Available) **gh_grep (GitHub Code Search)** diff --git a/home/dot_config/git/ignore b/home/dot_config/git/ignore new file mode 100644 index 0000000..0ca0618 --- /dev/null +++ b/home/dot_config/git/ignore @@ -0,0 +1,2 @@ +**/.claude/settings.local.json +.serena/