claude-home/CLAUDE.md

Home Lab Documentation System

Core Instructions

• You do not need to ask for permission to run tests. You always have permission.
• When new code is written, include checking for imports as part of the code review. We should never get NameErrors during testing.
• Always ask clarifying questions for complex configurations or multi-step tasks.
• Do what has been asked; nothing more, nothing less.
• If creating a temporary file will help achieve your goal, please create the file in the .claude/tmp/ directory and clean up when you're done.
• Prefer editing an existing file to creating a new one.
• Following a complex task or series of tasks, prompt the user to save any key learnings from the session.

Automatic Context Loading Rules

File Extension Triggers

When working with files, automatically load relevant documentation:

Python (.py, .pyx, .pyi)

• Load: patterns/python/
• Load: reference/python/
• If Django/Flask detected: Load examples/python/web-frameworks.md
• If requests/httpx detected: Load examples/python/api-clients.md

JavaScript/Node.js (.js, .mjs, .ts)

• Load: patterns/nodejs/
• Load: reference/nodejs/
• If package.json exists: Load examples/nodejs/package-management.md

Vue.js (.vue, vite.config., nuxt.config.)

• Load: patterns/vuejs/
• Load: reference/vuejs/
• Load: examples/vuejs/component-patterns.md

Shell Scripts (.sh, .bash, .zsh)

• Load: patterns/bash/
• Load: reference/bash/
• If systemd mentioned: Load examples/bash/service-management.md

Docker (Dockerfile, docker-compose.yml, .dockerignore)

• Load: patterns/docker/
• Load: reference/docker/
• Load: examples/docker/multi-stage-builds.md

Directory Context Triggers

When working in specific directories:

Docker-related directories (/docker/, /containers/, /compose/)

• Load: patterns/docker/
• Load: examples/docker/
• Load: reference/docker/troubleshooting.md

Database directories (/db/, /database/, /mysql/, /postgres/, /mongo/)

• Load: patterns/databases/
• Load: examples/databases/
• Load: reference/databases/

Network directories (/network/, /networking/, /nginx/, /traefik/)

• Load: patterns/networking/
• Load: examples/networking/
• Load: reference/networking/troubleshooting.md

VM directories (/vm/, /virtual/, /proxmox/, /kvm/)

• Load: patterns/vm-management/
• Load: examples/vm-management/
• Load: reference/vm-management/

Keyword Triggers

When user mentions specific terms, automatically load relevant docs:

Troubleshooting Keywords

• "debug", "error", "fail", "broken", "not working", "issue"
  • Load: reference/{relevant-tech}/troubleshooting.md
  • Load: examples/{relevant-tech}/debugging.md

Configuration Keywords

• "config", "configure", "setup", "install", "deploy"
  • Load: patterns/{relevant-tech}/
  • Load: examples/{relevant-tech}/configuration.md

Performance Keywords

• "slow", "performance", "optimize", "memory", "cpu"
  • Load: reference/{relevant-tech}/performance.md
  • Load: examples/{relevant-tech}/optimization.md

Security Keywords

• "secure", "ssl", "tls", "certificate", "auth", "firewall"
  • Load: patterns/networking/security.md
  • Load: reference/networking/security.md

Database Keywords

• "database", "db", "sql", "mysql", "postgres", "mongo", "redis"
  • Load: patterns/databases/
  • Load: examples/databases/

Container Keywords

• "docker", "container", "image", "compose", "kubernetes", "k8s"
  • Load: patterns/docker/
  • Load: examples/docker/

Network Keywords

• "network", "nginx", "proxy", "load balancer", "dns", "port", "firewall"
  • Load: patterns/networking/
  • Load: examples/networking/

SSH Keywords

• "ssh", "key", "authentication", "authorized_keys", "ssh-copy-id"
  • Load: patterns/networking/ssh-key-management.md
  • Load: examples/networking/ssh-homelab-setup.md
  • Load: reference/networking/ssh-troubleshooting.md

VM Keywords

• "virtual machine", "vm", "proxmox", "kvm", "hypervisor", "guest"
  • Load: patterns/vm-management/
  • Load: examples/vm-management/

Priority Rules

1. File extension triggers take highest priority
2. Directory context takes second priority
3. Keyword triggers are additive and load supplementary context
4. If multiple technologies detected, load all relevant patterns
5. Always prefer specific over general (e.g., vuejs/ over nodejs/)

Context Loading Behavior

• Load pattern files first for overview
• Load relevant examples for implementation details
• Load reference files for troubleshooting and edge cases
• Maximum of 3 documentation files per trigger to maintain efficiency
• If context becomes too large, prioritize most recent/specific files

Documentation Structure

/patterns/          # Technology overviews and best practices
/examples/          # Complete working implementations  
/reference/         # Troubleshooting, cheat sheets, fallback info

Each pattern file should reference relevant examples and reference materials.