root/claude_settings
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
ab74911cb92291b43527931500adde898a78bd31
claude_settings/CLAUDE.md

11 KiB
Raw Blame History

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.

Infrastruktur-Dokumentationssystem

Organisation pro Kunde

Gitea-Struktur:

├── Vinos/                       ← Organisation für Kunde "vinos"
│   ├── infrastructure.git       ← Landkarte für vinos
│   ├── zabbix.git               ← System-Repo
│   └── [weitere].git            ← Dienst-/System-Repos
│
└── Egonetix/                    ← Organisation für Kunde "egonetix"
    ├── infrastructure.git       ← Landkarte für egonetix
    └── [weitere].git

Lokale Struktur:

~/Nextcloud/
├── vinos/                       ← Kunde vinos
│   ├── infrastructure/          ← Landkarte (dependencies.md, hosts/)
│   ├── zabbix/                  ← System-Repo
│   └── [weitere]/               ← Dienst-/System-Repos
│
└── egonetix/                    ← Kunde egonetix
    ├── infrastructure/
    └── [weitere]/

Repo-Typen

Repo-Typ Gitea-Ort Inhalt
Infrastructure [Kunde]/infrastructure.git Landkarte, Abhängigkeiten, Host-Übersichten
System-Repo [Kunde]/[system].git README, Konfig-Dateien, Troubleshooting
Dienst-Repo [Kunde]/[dienst].git docker-compose.yml, Code, Workflows

Automatische Erkennung (Hook-gesteuert)

Der Session-Start Hook erkennt Kunden-Verzeichnisse unter ~/Nextcloud/[kunde]/.

Wenn du <REPO_SETUP_REQUIRED> in der Hook-Ausgabe siehst:

  1. Frage den User:

    "Ich habe erkannt, dass für dieses Repo noch Setup erforderlich ist. Soll ich das automatisch durchführen?"

  2. Bei Zustimmung - führe alle fehlenden Schritte aus:

    # Git initialisieren (falls nicht vorhanden)
git init
git branch -M main

# Template aus infrastructure/_templates/ kopieren

  3. Repo auf Gitea erstellen (API):

    curl -X POST -H "Authorization: token $GITEA_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"repo-name","description":"..."}' \
  https://gitea.egonetix.de/api/v1/orgs/[Kunde]/repos

  4. Remote hinzufügen und pushen:

    git remote add origin ssh://git@gitea.egonetix.de:222/[Kunde]/[repo-name].git
git push -u origin main

Gitea Remote-Konfiguration

URL-Format:

ssh://git@gitea.egonetix.de:222/[Kunde]/[repo-name].git

Beispiele:

Kunde Repo Remote URL
Vinos infrastructure ssh://git@gitea.egonetix.de:222/Vinos/infrastructure.git
Vinos zabbix ssh://git@gitea.egonetix.de:222/Vinos/zabbix.git
Egonetix infrastructure ssh://git@gitea.egonetix.de:222/Egonetix/infrastructure.git

Wichtig: Das Repo muss auf Gitea ZUERST erstellt werden (API oder Web-UI).

Workflow: Neues System-/Dienst-Repo anlegen

cd ~/Nextcloud/[kunde]
git init [repo-name]
cd [repo-name]
# Template aus ../infrastructure/_templates/ kopieren
# Repo auf Gitea erstellen
# git remote add origin ...
# git push -u origin main

Dokumentations-Verifikation (PFLICHT)

Bei jeder Dokumentationsarbeit MUSS eine zweistufige Verifikation durchgeführt werden:

  • Neue Dokumentation erstellen
  • Bestehende Dokumentation umstrukturieren
  • Inhalte aus anderen Quellen übernehmen
  • Dokumentation aufteilen oder zusammenführen

Schritt 1: Erstvergleich

Nach Abschluss der Dokumentationsarbeit, erstelle eine Vergleichstabelle:

| Abschnitt (Original) | Neue Datei | Status |
|---------------------|------------|--------|
| [Abschnitt 1] | [datei.md:zeilen] | ✅/❌ |
| [Abschnitt 2] | [datei.md:zeilen] | ✅/❌ |
...
  • Liste JEDEN Abschnitt der Quelldokumentation auf
  • Prüfe ob er in der neuen Struktur vorhanden ist
  • Markiere fehlende Abschnitte mit ❌

Schritt 2: Fehlende Inhalte ergänzen

  • Ergänze alle mit ❌ markierten Abschnitte
  • Committe die Änderungen

Schritt 3: Erneute Verifikation (PFLICHT)

Nach dem Ergänzen MUSS eine erneute, vollständige Prüfung erfolgen:

  1. Lies alle neuen Dateien nochmals
  2. Erstelle eine finale Checkliste mit Zeilennummern:
| # | Abschnitt | Datei:Zeilen | Status |
|---|-----------|--------------|--------|
| 1 | [Name] | README.md:15-18 | ✅ |
| 2 | [Name] | hosts.md:5-8 | ✅ |
...
  1. Bestätige: "X/X Abschnitte vollständig dokumentiert. Keine Inhalte wurden vergessen."

Dieser Prozess ist nicht optional. Dokumentationsverlust durch unvollständige Arbeit ist inakzeptabel.

Skills-Referenz

Skill Zweck
/troubleshoot-host Strukturierter Troubleshooting-Workflow
/session-end Session beenden, Commits erstellen
/new-project Neues Projekt anlegen
Reference in New Issue View Git Blame Copy Permalink