Claude Code instructions for the homelab infrastructure follow a distributed architecture pattern where CLAUDE.md files live with the code they document. This ensures instructions are version-controlled alongside the infrastructure they describe.
Each server has its own repository with server-specific CLAUDE.md:
Some servers don't have dedicated repositories and are managed through the central homelab-infrastructure repo:
- nas02 - Storage server (managed via Ansible)
- lucille5 - Development workstation (managed via Ansible)
- Work Mac Studio - Work development server (managed via Ansible)
- Family MacBook - Family shared device (managed via Ansible)
- Instructions evolve with the code they document
- Changes to infrastructure automatically include documentation updates
- No synchronization issues between code and documentation
- Each server repository is self-contained with its own instructions
- Claude Code can work on individual servers without needing the full infrastructure context
- Server-specific patterns and conventions are documented where they're used
- Server maintainers own both code and Claude instructions
- Pull requests include both infrastructure and documentation changes
- Easier to maintain consistency within each repository
When working on a specific server:
- Clone the server's repository
- Read the CLAUDE.md in the repository root
- Follow server-specific conventions and patterns
When working on orchestration or multi-server tasks:
- Use the homelab-infrastructure repository
- Read the master CLAUDE.md for overall patterns
- Reference individual server repositories as needed
When making infrastructure changes:
- Update the relevant CLAUDE.md alongside your code changes
- Ensure instructions reflect new patterns or conventions
- Include CLAUDE.md updates in your pull request
The wiki may contain reference copies or summaries of Claude instructions for convenience, but these are not authoritative. Always refer to the GitHub repositories for the current instructions.
Wiki pages that reference Claude instructions should include a note like:
Note: The authoritative CLAUDE.md instructions live with the code in the GitHub repository. This architectural pattern ensures Claude Code instructions are version-controlled alongside the infrastructure code they document.
- Single Source of Truth: GitHub repositories are the authoritative source
- Atomic Updates: Infrastructure and documentation changes happen together
- Branch Isolation: Different branches can have different instructions
- Pull Request Reviews: Documentation changes are reviewed with code
- Historical Context: Git history shows how instructions evolved with infrastructure