claude_settings/CLAUDE.md

Global Claude Code Instructions

⚠ MANDATORY: Settings-Synchronisierung

Repository: git@gitea.egonetix.de:root/claude_settings.git (Port 222) Lokaler Pfad: ~/dotfiles/claude_settings

Bei jedem Session-Start prüfen

cd ~/dotfiles/claude_settings && git fetch origin && git status

Falls Änderungen vorhanden:

git pull origin main

Nach Änderungen an Settings pushen

Wenn du Änderungen an folgenden Dateien vornimmst, MUSST du diese committen und pushen:

• settings.json - Globale Einstellungen
• CLAUDE.md - Diese Instruktionen
• agents/*.md - Benutzerdefinierte Agenten
• rules/*.md - Modulare Regeln
• statusline-command.sh - Statuszeilen-Script

cd ~/dotfiles/claude_settings
git add -A
git commit -m "Beschreibung der Änderung"
git push origin main

---

Copilot Instructions Skill

Maintain living documentation for every coding project via copilot-instructions.md in the project root.

---

Mandatory Workflow

Step 1: Determine Project Type

Check for existing project indicators:

• Git repository (.git/ directory)
• copilot-instructions.md file
• PROJECT_OVERVIEW.md file

If ANY exist → Ongoing Project: Follow full documentation workflow.

If NONE exist → Ask the user:

"This looks like a new workspace. Should I treat this as a one-time task, or set it up as an ongoing project with documentation and git?"

If user wants an ongoing project:

1. Initialize git repo if missing (git init)
2. Create copilot-instructions.md with initial structure
3. Optionally create PROJECT_OVERVIEW.md for complex systems

Step 2: For Ongoing Projects

1. Read existing copilot-instructions.md and PROJECT_OVERVIEW.md to understand the system
2. Scan the codebase/system to gather context and minimize follow-up questions
3. Update documentation if the current work affects architecture, patterns, entities, or conventions
4. Commit all changes to git immediately after completion

---

Document Structure

copilot-instructions.md (Development Guidelines)

Procedural knowledge for working on the project — patterns, conventions, pitfalls, workflows.

# Project Name - Copilot Instructions

## ⚠ MANDATORY RULES - NON-NEGOTIABLE
[Project-specific rules, commit conventions, critical warnings]

## Architecture Overview
[High-level system description, key integrations, tech stack]

## File Structure
[Directory tree with annotations]

## [Domain-Specific Sections]
[Devices, APIs, services, databases - whatever is relevant]
- Working code examples with explanations
- Configuration snippets that actually work
- Debug commands

## Patterns & Conventions
[Reusable patterns, naming conventions, code examples]

## Development Workflow
[How to test, deploy, access systems]

## Pitfalls to Avoid
[Gotchas, inverted logic, non-obvious behaviors, troubleshooting]

PROJECT_OVERVIEW.md (System Reference)

Factual inventory of what exists — devices, integrations, entities, IPs. Use for complex systems with many components.

# Project Overview

## System Information
[Version, host, IP, access details]

## Network Architecture
[Diagram or list of hosts/devices]

## Installed Components
[Add-ons, plugins, integrations with purpose]

## Entity/Device Inventory
[Tables of devices, entity IDs, purposes]

## Quick Reference
[Common commands, URLs, access methods]

When to create PROJECT_OVERVIEW.md:

• Systems with many devices/entities (IoT, home automation)
• Infrastructure projects with multiple hosts
• Projects where entity/device inventory changes frequently

---

Content Guidelines

Include:

• Working code/config snippets (tested and verified)
• Actual entity names, IPs, paths (not placeholders)
• Debug commands and troubleshooting tables
• Lessons learned from debugging sessions
• Non-obvious behavior ("contact sensor: on=OPEN, off=CLOSED")
• Git commit references for significant changes

Exclude:

• Secrets, tokens, passwords (reference secrets.yaml or .env instead)
• Obvious boilerplate explanations
• Duplicate information

Language: Match the user's language. Mixed language is acceptable when technical terms are clearer in English.

---

Git Commit Convention

After every change:

cd /path/to/project
git add -A
git commit -m "Descriptive message in user's language"
git push origin main  # or appropriate branch

Commit messages should describe what changed, not just "updated docs".

---

Referencing Git Commits

For significant development work, reference the relevant commit(s) in the documentation:

## Tasmota SML Integration

**Implemented:** 2025-01-21 | Commits: `a3f2b1c`, `e7d4a9f`

[Documentation of the feature...]

When to add commit references:

• New features or integrations
• Major refactors
• Complex bug fixes that required multiple attempts
• Configuration changes that took significant debugging

Format options:

• Single commit: Commit: a3f2b1c
• Multiple commits: Commits: a3f2b1c, e7d4a9f, b2c3d4e
• Commit range: Commits: a3f2b1c..e7d4a9f

Get the short hash after committing:

git log -1 --format="%h"  # Most recent commit
git log -3 --format="%h %s"  # Last 3 with messages

---

When to Update copilot-instructions.md

Update when:

• Adding new integrations, devices, or services
• Discovering non-obvious behavior or gotchas
• Establishing new patterns or conventions
• Fixing bugs that reveal important system behavior
• Changing architecture or file structure

Don't update for:

• Minor code changes that don't affect understanding
• Temporary debugging that will be removed

---

New Project Onboarding

When a user requests to set up a new ongoing project:

1. Connect and explore the system to understand what exists
2. Scan broadly — gather device lists, integrations, file structures, configurations
3. Create documentation based on findings:
   • copilot-instructions.md for development guidelines and patterns
   • PROJECT_OVERVIEW.md for system inventory (if complex)
4. Initialize git if not present
5. Commit initial documentation

This upfront investment minimizes questions in future sessions and enables faster, more informed development.

---

Host Troubleshooting

Automatische Erkennung

Wenn du in einem Verzeichnis unter ~/Nextcloud/hosts/ arbeitest:

1. Lade die lokale Dokumentation

   • Lies copilot-instructions.md falls vorhanden
   • Verstehe den System-Typ und Kontext

2. Bei Troubleshooting-Aufgaben

   • Nutze den Skill /troubleshoot-host für strukturiertes Vorgehen
   • Dokumentiere Lösungen in der copilot-instructions.md

Verzeichnisstruktur

~/Nextcloud/hosts/
├── [kunde]/                    # z.B. vinos, egonetix
│   └── [hostname]/             # z.B. srv-monitor02, srv-db12
│       └── copilot-instructions.md
└── _templates/
    └── copilot-instructions-template.md   # Master-Template

Neuen Host dokumentieren

1. Erstelle Verzeichnis: mkdir -p ~/Nextcloud/hosts/[kunde]/[hostname]
2. Kopiere Template: cp ~/Nextcloud/hosts/_templates/copilot-instructions-template.md ./copilot-instructions.md
3. Fülle während der Arbeit die relevanten Felder aus
4. Committe die Dokumentation

Skills-Referenz

Skill	Zweck
/troubleshoot-host	Strukturierter Troubleshooting-Workflow
/session-end	Session beenden, Commits erstellen
/new-project	Neues Projekt anlegen