my-claude-code-setup/AGENTS.md

ALWAYS START WITH THESE COMMANDS FOR COMMON TASKS

Task: "List/summarize all files and directories"

fd . -t f           # Lists ALL files recursively (FASTEST)
# OR
rg --files          # Lists files (respects .gitignore)

Task: "Search for content in files"

rg "search_term"    # Search everywhere (FASTEST)

Task: "Find files by name"

fd "filename"       # Find by name pattern (FASTEST)

Directory/File Exploration

# FIRST CHOICE - List all files/dirs recursively:
fd . -t f           # All files (fastest)
fd . -t d           # All directories
rg --files          # All files (respects .gitignore)

# For current directory only:
ls -la              # OK for single directory view

BANNED - Never Use These Slow Tools

• ❌ tree - NOT INSTALLED, use fd instead
• ❌ find - use fd or rg --files
• ❌ grep or grep -r - use rg instead
• ❌ ls -R - use rg --files or fd
• ❌ cat file | grep - use rg pattern file

Use These Faster Tools Instead

# ripgrep (rg) - content search 
rg "search_term"                # Search in all files
rg -i "case_insensitive"        # Case-insensitive
rg "pattern" -t py              # Only Python files
rg "pattern" -g "*.md"          # Only Markdown
rg -1 "pattern"                 # Filenames with matches
rg -c "pattern"                 # Count matches per file
rg -n "pattern"                 # Show line numbers 
rg -A 3 -B 3 "error"            # Context lines
rg " (TODO| FIXME | HACK)"      # Multiple patterns

# ripgrep (rg) - file listing 
rg --files                      # List files (respects •gitignore)
rg --files | rg "pattern"       # Find files by name 
rg --files -t md                # Only Markdown files 

# fd - file finding 
fd -e js                        # All •js files (fast find) 
fd -x command {}                # Exec per-file 
fd -e md -x ls -la {}           # Example with ls 

# jq - JSON processing 
jq. data.json                   # Pretty-print 
jq -r .name file.json           # Extract field 
jq '.id = 0' x.json             # Modify field

Search Strategy

1. Start broad, then narrow: rg "partial" | rg "specific"
2. Filter by type early: rg -t python "def function_name"
3. Batch patterns: rg "(pattern1|pattern2|pattern3)"
4. Limit scope: rg "pattern" src/

INSTANT DECISION TREE

User asks to "list/show/summarize/explore files"?
  → USE: fd . -t f  (fastest, shows all files)
  → OR: rg --files  (respects .gitignore)

User asks to "search/grep/find text content"?
  → USE: rg "pattern"  (NOT grep!)

User asks to "find file/directory by name"?
  → USE: fd "name"  (NOT find!)

User asks for "directory structure/tree"?
  → USE: fd . -t d  (directories) + fd . -t f  (files)
  → NEVER: tree (not installed!)

Need just current directory?
  → USE: ls -la  (OK for single dir)