mirror of
https://github.com/Xevion/dotfiles.git
synced 2026-01-31 12:24:08 -06:00
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/
This commit is contained in:
@@ -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<br>B) Import target→source |
|
||||
| "Edit CLAUDE.md" | Location unclear | A) ./CLAUDE.md (project)<br>B) home/dot_claude/CLAUDE.md.tmpl (user) |
|
||||
| "Update [managed file]" | Source of truth unclear | A) Apply from chezmoi<br>B) Import into chezmoi |
|
||||
| "Add [config] to opencode" | Location unclear | A) Project opencode.jsonc<br>B) User ~/.config/opencode/ |
|
||||
| "Show me the diff" | Comparison unclear | A) Source vs last commit<br>B) Source vs target<br>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
|
||||
|
||||
|
||||
@@ -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)**
|
||||
|
||||
@@ -0,0 +1,2 @@
|
||||
**/.claude/settings.local.json
|
||||
.serena/
|
||||
Reference in New Issue
Block a user