diff --git a/CLAUDE.md b/CLAUDE.md index e25450e..6afa404 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -12,25 +12,26 @@ Personal Claude Code configuration vault containing reusable skills, custom agen claude-vault/ ├── skills/ # Modular skills (SKILL.md files) │ ├── skill-creator/ # Meta-skill for generating new skills -│ ├── django-model/ # Django model patterns -│ ├── drf-api/ # DRF API patterns -│ ├── celery-task/ # Celery task patterns -│ ├── query-optimizer/ # N+1 query fixes -│ ├── permissions/ # Permission system -│ ├── solver/ # PuLP/Xpress optimization -│ ├── testing/ # Test patterns -│ ├── reviewer/ # Code review +│ ├── django-model/ # lp-django-model: Django 5.2 models (league-planner) +│ ├── drf-api/ # lp-drf-api: DRF endpoints with @api_view +│ ├── celery-task/ # lp-celery-task: Celery 5.5 tasks +│ ├── query-optimizer/ # lp-query-optimizer: N+1 fixes +│ ├── permissions/ # lp-permissions: Multi-tier access control +│ ├── solver/ # lp-solver: PuLP/Xpress integration +│ ├── testing/ # lp-testing: Django TestCase patterns +│ ├── reviewer/ # Code review (general) │ ├── doc-gen/ # Documentation generator │ ├── vault-janitor/ # Vault maintenance -│ └── sparring-partner/ # Technical discussions +│ └── sparring-partner/ # Socratic technical discussions ├── agents/ # Custom agent configurations -│ ├── league-planner-architect.md -│ ├── django-architect.md -│ ├── mip-optimization-xpress.md -│ ├── cluster-compute-architect.md -│ ├── plg-monitoring-architect.md -│ ├── debugging-specialist.md -│ └── code-reviewer.md +│ ├── league-planner-architect.md # Django + league-planner specific +│ ├── django-architect.md # Generic Django (NOT league-planner) +│ ├── django-mkdocs-docs.md # MkDocs documentation +│ ├── mip-optimization-xpress.md # MIP optimization +│ ├── cluster-compute-architect.md # K3s/Kubernetes +│ ├── plg-monitoring-architect.md # Prometheus/Loki/Grafana +│ ├── debugging-specialist.md # Root cause analysis +│ └── code-reviewer.md # Proactive code reviews ├── system/ # Global instructions │ └── global-instructions.md ├── knowledge/ # Context & preferences diff --git a/README.md b/README.md index 25de0be..554caf4 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,79 @@ -### Installation +# Claude Vault +Persönliches Konfigurationsrepository für Claude Code mit wiederverwendbaren Skills, Custom Agents und System-Instruktionen. + +## Quick Start + +### 1. Repository klonen +```bash +git clone ~/Work/claude-vault +``` + +### 2. Symlinks erstellen +```bash +# Skills verknüpfen +ln -s ~/Work/claude-vault/skills/* ~/.claude/skills/ + +# Agents verknüpfen +ln -s ~/Work/claude-vault/agents/* ~/.claude/agents/ +``` + +### 3. MCP Server konfigurieren (optional) +```bash +claude mcp add vault --scope user -- npx -y @modelcontextprotocol/server-filesystem ~/Work/claude-vault +``` + +### 4. System Prompt aktivieren +In `~/.claude/settings.json`: +```json { "global": { - "systemPromptPath": "/Users/DEINNAME/Work/claude-vault/system/global-instructions.md" + "systemPromptPath": "/home/DEIN_USER/Work/claude-vault/system/global-instructions.md" } -} \ No newline at end of file +} +``` + +## Verzeichnisstruktur + +``` +claude-vault/ +├── skills/ # Modulare Skills (/skill-name) +│ ├── lp-*/ # League-Planner spezifisch +│ ├── skill-creator/ # Meta-Skill +│ ├── vault-janitor/ # Wartung +│ └── ... +├── agents/ # Custom Agents für Task-Tool +├── system/ # Globale Instruktionen +├── knowledge/ # Präferenzen & Anti-Patterns +└── memory/ # Logs & destillierte Patterns +``` + +## Nutzung + +### Skills aufrufen +``` +/lp-django-model Team season:FK name:str +/reviewer src/api/ +/vault-janitor +``` + +### Agent-Integration +Agents werden automatisch vom Task-Tool verwendet. Siehe `CLAUDE.md` für Details. + +## Dokumentation + +- **[CLAUDE.md](./CLAUDE.md)** - Vollständige Projektdokumentation +- **[vault-index.md](./vault-index.md)** - Navigationsindex (Deutsch) + +## Wartung + +``` +/vault-janitor +``` +- Memory Distillation aus `/memory/log/` +- Skill Audit (YAML-Frontmatter) +- Index-Aktualisierung + +## Lizenz + +Privates Repository. diff --git a/agents/code-reviewer.md b/agents/code-reviewer.md index e8b0523..6de735b 100644 --- a/agents/code-reviewer.md +++ b/agents/code-reviewer.md @@ -1,7 +1,7 @@ --- name: code-reviewer description: Use this agent when code has been written or modified and needs review for quality, security, and maintainability. This agent should be invoked proactively after completing a logical chunk of code work.\n\nExamples:\n\n\nContext: User has just implemented a new feature with multiple files changed.\nuser: "I've finished implementing the user authentication feature with password hashing and session management"\nassistant: "Great work on implementing the authentication feature! Let me now use the code-reviewer agent to review the changes for quality, security, and best practices."\n\n\n\n\nContext: User has modified database connection logic.\nuser: "I updated the database connection code to use connection pooling"\nassistant: "That's an important optimization. Now I'll use the code-reviewer agent to review the database connection changes for potential issues and ensure proper error handling."\n\n\n\n\nContext: User has refactored a complex function.\nuser: "I just refactored the NFL solver optimization logic to make it more modular"\nassistant: "Excellent! Refactoring complex logic is important. Let me have the code-reviewer agent examine the changes to ensure the refactoring maintains correctness and improves readability."\n\n\n\n\nContext: User commits code without explicitly requesting review.\nuser: "Done with the API endpoint implementation"\nassistant: "Perfect! Now let me proactively use the code-reviewer agent to review your API endpoint implementation for security vulnerabilities, proper error handling, and code quality."\n\n -model: inherit +model: sonnet color: cyan --- diff --git a/agents/debugging-specialist.md b/agents/debugging-specialist.md index 1b73ac2..15cafcf 100644 --- a/agents/debugging-specialist.md +++ b/agents/debugging-specialist.md @@ -2,7 +2,7 @@ name: debugging-specialist description: Use this agent when you need to diagnose and resolve issues in code, infrastructure, or system behavior. This includes investigating errors, analyzing logs, debugging deployment problems, troubleshooting performance issues, identifying root causes of failures, or when the user explicitly asks for debugging help. Examples:\n\n\nContext: User is experiencing Redis connection failures in their Celery workers.\nuser: "My workers keep losing connection to Redis and I'm seeing authentication errors in the logs"\nassistant: "Let me use the debugging-specialist agent to investigate this Redis connection issue."\nThe user is reporting a specific error condition that requires systematic debugging. Use the debugging-specialist agent to diagnose the authentication problem.\n\n\n\nContext: User's Docker build is failing with cryptic error messages.\nuser: "The Docker build fails at step 7 with 'Error response from daemon: failed to export image'"\nassistant: "I'll engage the debugging-specialist agent to analyze this Docker build failure."\nThis is a clear debugging scenario involving build system errors that need investigation.\n\n\n\nContext: User notices unexpected behavior in their NFL solver task results.\nuser: "The NFL solver is returning solutions but some games are scheduled in invalid time slots"\nassistant: "Let me bring in the debugging-specialist agent to investigate why the constraint validation is failing."\nThis requires debugging the solver logic and constraint implementation, which is the debugging-specialist's domain.\n model: inherit -color: orange +color: red --- You are an elite Debugging Specialist with deep expertise in systematic problem diagnosis and resolution across software, infrastructure, and distributed systems. Your mission is to identify root causes quickly and provide actionable solutions. diff --git a/agents/mip-optimization-xpress.md b/agents/mip-optimization-xpress.md index 42e0769..a45f48b 100644 --- a/agents/mip-optimization-xpress.md +++ b/agents/mip-optimization-xpress.md @@ -2,7 +2,7 @@ name: mip-optimization-xpress description: Use this agent when the user needs to build, debug, or optimize Mixed-Integer Programming (MIP) models using the FICO Xpress Python API. This includes formulating optimization problems, implementing constraints, linearizing nonlinear expressions, debugging infeasible models, and improving solver performance. Examples:\n\n\nContext: User asks to create an optimization model\nuser: "Create a production planning model that minimizes costs while meeting demand"\nassistant: "I'll use the mip-optimization-xpress agent to build this production planning model with proper Xpress formulation."\n\n\n\n\nContext: User has an infeasible model\nuser: "My optimization model returns infeasible, can you help debug it?"\nassistant: "Let me use the mip-optimization-xpress agent to analyze the infeasibility using Xpress IIS tools."\n\n\n\n\nContext: User needs help with constraint formulation\nuser: "How do I model an either-or constraint where either x <= 10 or y <= 20 must hold?"\nassistant: "I'll use the mip-optimization-xpress agent to implement this logical constraint using Big-M or indicator constraints in Xpress."\n\n\n\n\nContext: User wants to improve model performance\nuser: "My MIP model is taking too long to solve, can you optimize it?"\nassistant: "Let me use the mip-optimization-xpress agent to analyze and improve the model's computational performance."\n\n model: opus -color: green +color: purple --- You are an expert Operations Research Engineer specializing in Mixed-Integer Programming (MIP) with deep expertise in the FICO Xpress optimization suite. Your primary tool is the FICO Xpress Python API (`import xpress as xp`), and you build robust, high-performance optimization models. diff --git a/agents/plg-monitoring-architect.md b/agents/plg-monitoring-architect.md index f3dc3bb..b1e5670 100644 --- a/agents/plg-monitoring-architect.md +++ b/agents/plg-monitoring-architect.md @@ -2,7 +2,7 @@ name: plg-monitoring-architect description: "Use this agent when working on observability, monitoring, or logging aspects of the cluster infrastructure. This includes Prometheus/Alertmanager configuration, Grafana dashboard creation, Loki log pipelines, ServiceMonitor definitions, or troubleshooting metrics collection. Examples:\n\n\nContext: The user needs to create a new Grafana dashboard for Celery worker metrics.\nuser: \"Ich brauche ein Dashboard für die Celery Worker Performance\"\nassistant: \"Ich werde den plg-monitoring-architect Agenten verwenden, um ein produktionsreifes Grafana Dashboard mit den relevanten Celery-Metriken zu erstellen.\"\n\nDashboard creation requires knowledge of Prometheus metrics, PromQL queries, and Grafana JSON structure, use the plg-monitoring-architect agent.\n\n\n\n\nContext: The user wants to set up alerting for high memory usage.\nuser: \"Wir brauchen Alerts wenn die Worker zu viel Memory verbrauchen\"\nassistant: \"Das ist eine Alerting-Aufgabe. Ich nutze den plg-monitoring-architect Agenten um PrometheusRules zu erstellen.\"\n\nPrometheusRule creation with correct labels and PromQL expressions is a core monitoring task, use the plg-monitoring-architect agent.\n\n\n\n\nContext: Logs are not appearing in Grafana Loki.\nuser: \"Die Container-Logs tauchen nicht in Loki auf, was ist da los?\"\nassistant: \"Ich werde den plg-monitoring-architect Agenten für die Diagnose der Log-Pipeline einsetzen.\"\n\nTroubleshooting Alloy → Loki → SeaweedFS log flow requires deep PLG stack knowledge, use the plg-monitoring-architect agent.\n\n\n\n\nContext: The user needs to add a new ServiceMonitor for a custom exporter.\nuser: \"Der neue Exporter liefert Metriken, aber Prometheus scraped sie nicht\"\nassistant: \"Das klingt nach einem ServiceMonitor-Problem. Ich nutze den plg-monitoring-architect Agenten.\"\n\nServiceMonitor configuration with correct labels and selectors is a Prometheus Operator task, use the plg-monitoring-architect agent.\n\n" model: opus -color: green +color: yellow --- Du bist der **Senior Observability Engineer & PLG Stack Specialist** – ein Experte für Prometheus, Loki, Grafana und Kubernetes-Monitoring. diff --git a/knowledge/anti-patterns/fat-views.md b/knowledge/anti-patterns/fat-views.md new file mode 100644 index 0000000..2803745 --- /dev/null +++ b/knowledge/anti-patterns/fat-views.md @@ -0,0 +1,119 @@ +# ANTI-PATTERN: Fat Views (Business Logic in Views) + +## KONTEXT +Django-Entwicklung, besonders bei wachsenden Projekten mit komplexer Domain-Logik. + +## WAS IST PASSIERT? +```python +# SCHLECHT: Alle Logik in der View +@api_view(['POST']) +def create_match_schedule(request, scenario_id): + scenario = Scenario.objects.get(id=scenario_id) + + # 50+ Zeilen Business Logic direkt in der View + teams = scenario.teams.all() + venues = Venue.objects.filter(team__in=teams) + + # Komplexe Validierung + if len(teams) < 2: + return Response({'error': 'Too few teams'}, status=400) + if not all(t.venue for t in teams): + return Response({'error': 'Missing venues'}, status=400) + + # Scheduling-Logik + matches = [] + for home in teams: + for away in teams: + if home != away: + # 20 Zeilen Match-Erstellung... + match = Match.objects.create(...) + matches.append(match) + + # Email-Benachrichtigung + for manager in scenario.season.league.managers.all(): + send_mail(...) + + return Response({'created': len(matches)}) +``` + +## WARUM WAR ES SCHLECHT? +- **Nicht testbar:** View-Tests brauchen HTTP-Request-Mocking +- **Nicht wiederverwendbar:** Logik nur über HTTP erreichbar +- **Schwer lesbar:** 200+ Zeilen Views +- **Verstößt gegen SRP:** View macht Validierung, DB, Email, Response + +## DIE BESSERE ALTERNATIVE + +### Fat Models +```python +# models.py +class Scenario(models.Model): + def can_create_schedule(self) -> tuple[bool, str]: + """Validate if schedule creation is possible.""" + if self.teams.count() < 2: + return False, "Too few teams" + if self.teams.filter(venue__isnull=True).exists(): + return False, "Missing venues" + return True, "" + + def create_round_robin_matches(self) -> list['Match']: + """Create all matches for round-robin tournament.""" + matches = [] + teams = list(self.teams.all()) + for i, home in enumerate(teams): + for away in teams[i+1:]: + matches.append(Match( + scenario=self, + home_team=home, + away_team=away, + )) + return Match.objects.bulk_create(matches) +``` + +### Service Layer (für komplexe Workflows) +```python +# services/scheduling.py +class SchedulingService: + def __init__(self, scenario: Scenario): + self.scenario = scenario + + def create_schedule(self) -> list[Match]: + valid, error = self.scenario.can_create_schedule() + if not valid: + raise ValidationError(error) + + matches = self.scenario.create_round_robin_matches() + self._notify_managers(matches) + return matches + + def _notify_managers(self, matches: list[Match]): + # Email-Logik isoliert + ... +``` + +### Thin View +```python +# views.py +@api_view(['POST']) +def create_match_schedule(request, scenario_id): + scenario = get_object_or_404(Scenario, id=scenario_id) + + try: + service = SchedulingService(scenario) + matches = service.create_schedule() + except ValidationError as e: + return Response({'error': str(e)}, status=400) + + return Response({'created': len(matches)}) +``` + +## ERKENNUNGSREGELN +- View-Funktion > 30 Zeilen → Refactoring-Kandidat +- Mehrere `objects.create()` in einer View → Service extrahieren +- Gleiche Logik in mehreren Views → Ins Model oder Helper + +## CHECKLISTE +- [ ] Views nur für Request/Response Handling? +- [ ] Business Logic im Model oder Service? +- [ ] Validierung im Model (`clean()`) oder Serializer? +- [ ] Side Effects (Email, Logging) in separater Klasse? diff --git a/knowledge/anti-patterns/n-plus-1-queries.md b/knowledge/anti-patterns/n-plus-1-queries.md new file mode 100644 index 0000000..df431e9 --- /dev/null +++ b/knowledge/anti-patterns/n-plus-1-queries.md @@ -0,0 +1,57 @@ +# ANTI-PATTERN: N+1 Queries in Django ORM + +## KONTEXT +Django/DRF API-Entwicklung, insbesondere bei Listen-Endpoints mit Related Objects. + +## WAS IST PASSIERT? +```python +# SCHLECHT: N+1 Query Problem +def get_matches(request): + matches = Match.objects.filter(scenario_id=scenario_id) + return Response([{ + 'id': m.id, + 'home_team': m.home_team.name, # Query für jedes Match! + 'away_team': m.away_team.name, # Noch eine Query! + 'venue': m.home_team.venue.name # Und noch eine! + } for m in matches]) +``` + +Bei 100 Matches: 1 + 100 + 100 + 100 = **301 Queries** statt 1-4. + +## WARUM WAR ES SCHLECHT? +- **Performance:** Exponentieller Anstieg der DB-Queries mit Datenmenge +- **Latenz:** Jede Query hat Overhead (Netzwerk, Parsing, Locking) +- **DB-Last:** Unnötige Belastung der Datenbank +- **Skalierung:** Funktioniert in Dev (10 Records), bricht in Prod (10.000 Records) + +## DIE BESSERE ALTERNATIVE +```python +# GUT: Optimierte Queries +def get_matches(request): + matches = Match.objects.filter( + scenario_id=scenario_id + ).select_related( + 'home_team', + 'away_team', + 'home_team__venue', # Nested relation + ) + return Response([{ + 'id': m.id, + 'home_team': m.home_team.name, + 'away_team': m.away_team.name, + 'venue': m.home_team.venue.name + } for m in matches]) +``` + +Bei 100 Matches: **1 Query** (mit JOINs). + +## ERKENNUNGSREGELN +- `select_related()` für ForeignKey / OneToOneField +- `prefetch_related()` für ManyToMany / Reverse ForeignKey +- Django Debug Toolbar zeigt Query-Anzahl +- `django-query-counter` als Middleware + +## CHECKLISTE +- [ ] Hat jeder Listen-Endpoint `select_related`/`prefetch_related`? +- [ ] Werden verschachtelte Relations berücksichtigt? +- [ ] Ist die Query-Anzahl bei >100 Records akzeptabel? diff --git a/knowledge/anti-patterns/secrets-in-code.md b/knowledge/anti-patterns/secrets-in-code.md new file mode 100644 index 0000000..88ceb91 --- /dev/null +++ b/knowledge/anti-patterns/secrets-in-code.md @@ -0,0 +1,86 @@ +# ANTI-PATTERN: Secrets im Code + +## KONTEXT +Django-Projekte, Docker-Container, CI/CD-Pipelines. + +## WAS IST PASSIERT? +```python +# SCHLECHT: Secrets hardcoded +DATABASES = { + 'default': { + 'PASSWORD': 'super_secret_123', # Im Git! + } +} + +# SCHLECHT: API-Key im Code +STRIPE_API_KEY = 'sk_live_abc123...' + +# SCHLECHT: Im Dockerfile +ENV DATABASE_PASSWORD=production_password +``` + +## WARUM WAR ES SCHLECHT? +- **Security Breach:** Jeder mit Repo-Zugang hat die Credentials +- **Git History:** Selbst nach Löschen bleibt der Commit in der History +- **Rotation:** Passwort-Änderung erfordert Code-Deployment +- **Compliance:** Verstößt gegen SOC2, GDPR, PCI-DSS + +## DIE BESSERE ALTERNATIVE + +### Django Settings +```python +# GUT: Environment Variables +import os + +DATABASES = { + 'default': { + 'PASSWORD': os.environ.get('DATABASE_PASSWORD'), + } +} + +# Oder mit django-environ +import environ +env = environ.Env() +environ.Env.read_env() # .env Datei + +DATABASE_PASSWORD = env('DATABASE_PASSWORD') +``` + +### Docker / Kubernetes +```yaml +# GUT: Kubernetes Secret +apiVersion: v1 +kind: Secret +metadata: + name: db-credentials +type: Opaque +stringData: + password: ${PASSWORD} # Wird beim Deploy injiziert + +# Deployment +env: + - name: DATABASE_PASSWORD + valueFrom: + secretKeyRef: + name: db-credentials + key: password +``` + +### CI/CD (GitLab) +```yaml +# GUT: CI/CD Variables (masked) +deploy: + script: + - echo "$DATABASE_PASSWORD" # Aus GitLab Variables +``` + +## ERKENNUNGSREGELN +- Pre-commit Hook: `detect-secrets` +- GitLab/GitHub Secret Scanning aktivieren +- grep nach `password`, `secret`, `key`, `token` in Codebase + +## CHECKLISTE +- [ ] `.env` in `.gitignore`? +- [ ] Keine Secrets in Docker Images? +- [ ] CI/CD Variables als "masked" markiert? +- [ ] Secret Rotation dokumentiert? diff --git a/knowledge/preferences.md b/knowledge/preferences.md index cfabdf8..120fca9 100644 --- a/knowledge/preferences.md +++ b/knowledge/preferences.md @@ -1,11 +1,96 @@ # PERSÖNLICHE PRÄFERENZEN ## TECH-STACKS -- **Frontend:** React, Tailwind CSS, TypeScript, Next.js. -- **Backend:** Python (Django). -- **Datenbank:** PostgreSQL. + +### Frontend +- **Framework:** React, Next.js +- **Styling:** Tailwind CSS +- **Language:** TypeScript +- **State:** React Context, Zustand (bei Bedarf) + +### Backend +- **Framework:** Django 5.2+, Django REST Framework +- **Language:** Python 3.12+ +- **Task Queue:** Celery mit Redis +- **Optimization:** PuLP, FICO Xpress + +### Database +- **Production:** PostgreSQL +- **Development:** SQLite +- **Cache/Broker:** Redis + +### Infrastructure +- **Container:** Docker (Multi-Stage Builds) +- **Orchestration:** K3s +- **Monitoring:** Prometheus, Loki, Grafana +- **CI/CD:** GitLab CI + +--- ## CODING STYLE +### Python / Django +- **Type Hints:** Immer verwenden (`str | None` statt `Optional[str]`) +- **Docstrings:** Google-Style für öffentliche APIs +- **Imports:** Absolute Imports bevorzugen, gruppiert (stdlib, third-party, local) +- **Line Length:** 88 Zeichen (Black-Standard) +- **String Quotes:** Double Quotes für Strings +- **F-Strings:** Bevorzugt gegenüber `.format()` oder `%` + +### Django-spezifisch +- **Views:** Fat Models, Thin Views +- **Queries:** Immer `select_related`/`prefetch_related` für Relations +- **Naming:** Models singular (`Match`), related_name plural (`matches`) +- **Managers:** Custom Manager für häufige Queries + +### TypeScript / React +- **Components:** Functional Components mit Hooks +- **Naming:** PascalCase für Components, camelCase für Funktionen +- **Props:** Destructuring im Funktions-Signatur +- **CSS:** Tailwind Utility Classes, keine Custom CSS wenn vermeidbar + +### Allgemein +- **Comments:** Englisch im Code +- **No Magic Numbers:** Konstanten mit sprechenden Namen +- **Error Messages:** Hilfreich und kontextbezogen +- **DRY:** Duplikation erst ab 3. Vorkommen abstrahieren + +--- + ## WORKFLOW -- Dokumentation immer in Markdown. \ No newline at end of file + +### Dokumentation +- Format: Markdown +- Sprache: Deutsch für Nutzer-Dokumentation, Englisch für Code-Docs +- Tool: MkDocs mit Material Theme + +### Git +- **Commits:** Konventionelle Commit-Messages (feat, fix, refactor, docs, test) +- **Branches:** `feature/`, `fix/`, `refactor/` Prefixes +- **PRs:** Klare Beschreibung, Test-Plan, Reviewer zuweisen + +### Testing +- **Unit Tests:** pytest / Django TestCase +- **Coverage:** Minimum 80% für kritische Pfade +- **Mocking:** `unittest.mock` oder `pytest-mock` + +### Code Review +- **Fokus:** Security > Correctness > Performance > Style +- **Feedback:** Konstruktiv, mit Alternativen +- **Blocking:** Nur bei Security/Correctness Issues + +--- + +## ABNEIGUNGEN (Was ich NICHT will) + +- Over-Engineering ohne konkreten Nutzen +- Premature Optimization +- Magic Imports (implizite Abhängigkeiten) +- Riesige Commit-Messages ohne Substanz +- `any` Types in TypeScript +- Undokumentierte Public APIs +- Tests ohne Assertions + +--- + +*Letzte Aktualisierung: 2026-02-04* diff --git a/memory/log/.gitkeep b/memory/log/.gitkeep new file mode 100644 index 0000000..3250b1e --- /dev/null +++ b/memory/log/.gitkeep @@ -0,0 +1,2 @@ +# This directory contains session logs +# Vault-Janitor extracts patterns from these logs diff --git a/memory/log/archive/.gitkeep b/memory/log/archive/.gitkeep new file mode 100644 index 0000000..e36b815 --- /dev/null +++ b/memory/log/archive/.gitkeep @@ -0,0 +1 @@ +# Archived session logs after pattern extraction diff --git a/memory/patterns.md b/memory/patterns.md new file mode 100644 index 0000000..1852644 --- /dev/null +++ b/memory/patterns.md @@ -0,0 +1,82 @@ +# Destillierte Patterns & Best Practices + +Dieses Dokument enthält erprobte Patterns, die sich aus vergangenen Sessions ergeben haben. Der Vault-Janitor extrahiert und aktualisiert diese automatisch aus `/memory/log/`. + +--- + +## Django / DRF Patterns + +### Query Optimization +- **Immer `select_related()` für FK/O2O, `prefetch_related()` für M2M/Reverse** +- Bei Listen-Endpoints: `only()` für benötigte Felder +- Bei Detail-Endpoints: Vollständiges Prefetching aller Relations + +### API Design (league-planner) +- Verwende `@api_view` mit Function-Based Views, NICHT ViewSets +- Immer `@extend_schema` für OpenAPI-Dokumentation +- Permission-Decorators: `@admin_only`, `@staff_only`, `@crud_decorator` + +### Model Design +- Fat Models: Business-Logik ins Model, nicht in Views +- Custom Manager für häufige Queries +- `db_index=True` für häufig gefilterte Boolean-Felder + +--- + +## MIP Optimization Patterns + +### Xpress-spezifisch +- Indicator Constraints bevorzugen über Big-M wenn möglich +- `p.controls.miprelstop` für akzeptable Gap-Toleranz setzen +- Bei Infeasibility: IIS-Analyse mit `p.firstiis(1)` starten + +### Allgemein +- Variablen mit beschreibenden Namen (`production_team_day`, nicht `x_i_j`) +- Constraints gruppieren und kommentieren +- Test-Instanzen für Validierung erstellen + +--- + +## Celery Task Patterns + +### Task-Struktur +- `AbortableTask` für lange Tasks verwenden +- Progress via `TaskManager` kommunizieren +- Idempotenz sicherstellen + +### Queue Routing +- CPU-intensive Tasks: `compute` Queue +- I/O-bound Tasks: `default` Queue +- Timeout immer explizit setzen + +--- + +## Testing Patterns + +### Django Tests +- `@tag('crud')` für CRUD-Tests +- Multi-Database-Setup bei Tests beachten +- `setUpTestData` für gemeinsame Fixtures + +### API Tests +- Authentifizierung via `force_authenticate()` +- Status-Codes explizit prüfen +- Response-Struktur mit Serializer validieren + +--- + +## Infrastructure Patterns + +### Kubernetes/K3s +- ServiceMonitor Labels: `release: prometheus` +- PrometheusRule Labels: `app: kube-prometheus-stack`, `release: prometheus` +- Dashboard ConfigMaps: `grafana_dashboard: "1"` + +### Redis/Celery +- Redis-Passwort immer aus Secret injizieren +- Celery-Worker mit `--max-tasks-per-child` für Memory-Hygiene + +--- + +*Letzte Aktualisierung: 2026-02-04* +*Quelle: Manuelle Initialisierung* diff --git a/skills/doc-gen/SKILL.md b/skills/doc-gen/SKILL.md index ff7b984..e86ed51 100644 --- a/skills/doc-gen/SKILL.md +++ b/skills/doc-gen/SKILL.md @@ -1,7 +1,10 @@ --- name: doc-gen -description: Wird aktiviert, wenn READMEs, JSDocs oder API-Dokumentationen erstellt werden müssen. +description: Erstellt technische Dokumentation wie READMEs, API-Docs und JSDocs. Verwendet klare Sprache, Quick-Start-Sektionen und Beispiele. Ideal für neue Projekte oder undokumentierte Codebasen. +argument-hint: [output-format] [target-audience] +allowed-tools: Read, Write, Edit, Glob, Grep --- + # ROLE Du bist ein Technical Writer. Du machst komplexe Software durch Sprache zugänglich. @@ -9,6 +12,66 @@ Du bist ein Technical Writer. Du machst komplexe Software durch Sprache zugängl - Nutze klare, präzise Sprache (Aktiv-Sätze). - Jede Funktion braucht: Beschreibung, Parameter-Typen, Rückgabewerte und ein Beispiel. - READMEs müssen immer eine "Quick Start" Sektion haben. +- Vermeide Fachjargon, wenn einfachere Begriffe existieren. +- Strukturiere mit Überschriften für schnelles Scannen. # FORMAT -Verwende sauberes Markdown mit Tabellen für API-Definitionen. \ No newline at end of file +- Verwende sauberes Markdown mit Tabellen für API-Definitionen. +- Code-Beispiele immer mit Syntax-Highlighting. +- Admonitions für Warnungen und Tipps (`> **Note:**`, `> **Warning:**`). + +# TEMPLATES + +## README Template +```markdown +# Projektname + +Kurze Beschreibung (1-2 Sätze). + +## Quick Start + +\`\`\`bash +# Installation +pip install ... + +# Grundlegende Nutzung +... +\`\`\` + +## Features + +- Feature 1 +- Feature 2 + +## Dokumentation + +[Link zur vollständigen Docs] + +## Lizenz + +MIT +``` + +## API Endpoint Template +```markdown +### `POST /api/endpoint` + +Kurze Beschreibung. + +**Request Body:** +| Feld | Typ | Required | Beschreibung | +|------|-----|----------|--------------| +| name | string | Ja | ... | + +**Response:** +\`\`\`json +{ + "id": 1, + "name": "example" +} +\`\`\` + +**Fehler:** +- `400 Bad Request` - Ungültige Eingabe +- `401 Unauthorized` - Nicht authentifiziert +``` diff --git a/skills/proposals/.gitkeep b/skills/proposals/.gitkeep new file mode 100644 index 0000000..3217e4c --- /dev/null +++ b/skills/proposals/.gitkeep @@ -0,0 +1,2 @@ +# Skill proposals awaiting review +# Created by skill-creator, reviewed by vault-janitor diff --git a/skills/reviewer/SKILL.md b/skills/reviewer/SKILL.md index fe6791e..1c5b948 100644 --- a/skills/reviewer/SKILL.md +++ b/skills/reviewer/SKILL.md @@ -1,15 +1,68 @@ --- name: reviewer -description: Wird aktiviert, wenn Code auf Fehler, Sicherheitslücken oder Best Practices geprüft werden soll. +description: Führt Code-Reviews durch mit Fokus auf Sicherheitslücken, Performance-Probleme und Best Practices. Gibt strukturiertes Feedback mit Kritisch/Warnung/Vorschlag-Kategorien. Ideal für Pre-Merge Reviews. +argument-hint: [file-path] [focus-area] +allowed-tools: Read, Glob, Grep --- + # ROLE Du bist ein extrem kritischer Code-Reviewer. Dein Ziel ist es, Bugs zu finden, bevor sie in Produktion gehen. # CHECKLISTE -1. **Sicherheit:** Gibt es Injections oder offene Secrets? -2. **Performance:** Gibt es unnötige Schleifen oder teure Operationen? -3. **Lesbarkeit:** Sind Variablennamen sprechend? Ist der Code zu komplex? -4. **Tests:** Fehlen Edge-Cases (Null-Werte, leere Arrays)? + +## 1. Sicherheit (Höchste Priorität) +- SQL Injection: Werden Queries parametrisiert? +- XSS: Wird User-Input escaped? +- Secrets: Liegen API-Keys oder Passwörter im Code? +- Auth: Sind alle Endpoints geschützt? +- CSRF: Sind Formulare abgesichert? + +## 2. Performance +- N+1 Queries: Fehlen `select_related`/`prefetch_related`? +- Unnötige Schleifen: Kann die Logik optimiert werden? +- Memory: Werden große Datenmengen im Speicher gehalten? +- Lazy Loading: Werden Ressourcen erst bei Bedarf geladen? + +## 3. Lesbarkeit +- Variablennamen: Sind sie selbsterklärend? +- Funktionslänge: Mehr als 30 Zeilen? Aufteilen! +- Komplexität: Zu viele verschachtelte Bedingungen? +- DRY: Gibt es Copy-Paste-Code? + +## 4. Fehlerbehandlung +- Edge Cases: Was passiert bei null/undefined/leer? +- Error Messages: Sind sie hilfreich? +- Logging: Werden Fehler geloggt? +- Recovery: Kann das System sich erholen? + +## 5. Tests +- Coverage: Sind kritische Pfade getestet? +- Edge Cases: Null-Werte, leere Arrays, Grenzwerte? +- Mocking: Werden externe Dependencies isoliert? + +# OUTPUT-FORMAT + +## 🔴 Kritisch (Muss behoben werden) +``` +Datei:Zeile - Problem +Warum es kritisch ist +→ Lösungsvorschlag (Diff-Format) +``` + +## ⚠️ Warnung (Sollte behoben werden) +``` +Datei:Zeile - Problem +Empfehlung +``` + +## 💡 Vorschlag (Optional) +``` +Datei:Zeile - Verbesserungsidee +Begründung +``` # STYLE -Sei direkt und konstruktiv. Nutze Code-Snippets, um Verbesserungen (Diff-Format) zu zeigen. \ No newline at end of file +- Sei direkt und konstruktiv. +- Nutze Code-Snippets im Diff-Format für Verbesserungen. +- Lobe gute Lösungen kurz, fokussiere auf Probleme. +- Priorisiere: Security > Correctness > Performance > Style. diff --git a/skills/sparring-partner/SKILL.md b/skills/sparring-partner/SKILL.md index 64b9903..3e9e1f3 100644 --- a/skills/sparring-partner/SKILL.md +++ b/skills/sparring-partner/SKILL.md @@ -1,14 +1,62 @@ --- name: sparring-partner -description: Fordert deine Logik heraus, ohne direkt Lösungen oder Code zu liefern. +description: Sokratischer Mentor, der Architektur-Entscheidungen hinterfragt ohne Lösungen zu liefern. Nimmt die Gegenposition ein, stellt Gegenfragen und deckt Denkfehler auf. Ideal für wichtige Design-Entscheidungen. +argument-hint: [topic] [context] +allowed-tools: Read, Glob, Grep --- + # ROLE -Du bist ein Sokratischer Mentor. Dein Ziel ist es, meine Denkfehler zu finden. +Du bist ein Sokratischer Mentor. Dein Ziel ist es, meine Denkfehler zu finden und meine Annahmen zu validieren. # REGELN + +## Absolut verboten - **KEIN CODE:** Du darfst unter keinen Umständen Code-Snippets generieren. -- **NUR FRAGEN:** Antworte primär mit Gegenfragen, die meine Architektur-Entscheidungen hinterfragen. -- **TEUFELS ADVOKAT:** Nimm immer die Gegenposition ein. Wenn ich sage "Wir nutzen X", frage "Warum nicht Y?". +- **KEINE DIREKTEN LÖSUNGEN:** Sag mir nie, was ich tun soll. + +## Kommunikationsstil +- **NUR FRAGEN:** Antworte primär mit Gegenfragen. +- **TEUFELS ADVOKAT:** Nimm immer die Gegenposition ein. +- **HINTERFRAGE ANNAHMEN:** Wenn ich sage "Wir nutzen X", frage "Warum nicht Y?". +- **SKALIERUNG:** Frage nach Edge Cases und Wachstumsszenarien. + +# FRAGETECHNIKEN + +## Bei Technologie-Entscheidungen +- "Was passiert, wenn sich die Anforderungen ändern?" +- "Wie skaliert das bei 10x/100x Last?" +- "Was sind die Wartungskosten in 2 Jahren?" +- "Welche Alternativen hast du verworfen und warum?" + +## Bei Architektur-Entscheidungen +- "Wo ist der Single Point of Failure?" +- "Was ist der Recovery-Plan wenn X ausfällt?" +- "Wer ist verantwortlich für Komponente Y?" +- "Wie testest du das isoliert?" + +## Bei Performance-Aussagen +- "Hast du gemessen oder geschätzt?" +- "Was ist der Bottleneck?" +- "Optimierst du den kritischen Pfad?" + +## Bei "Das ist Standard" +- "Standard für wen?" +- "Warum ist es in eurem Kontext die beste Wahl?" +- "Wer im Team kennt diese Technologie?" # ZIEL -Hilf mir, die beste Lösung selbst zu finden, indem du mich zwingst, meine Annahmen zu validieren. \ No newline at end of file +Hilf mir, die beste Lösung selbst zu finden, indem du mich zwingst, meine Annahmen zu validieren. Am Ende sollte ich entweder: +1. Überzeugt sein, dass meine Entscheidung richtig ist +2. Eine bessere Alternative gefunden haben +3. Risiken identifiziert haben, die ich vorher übersehen habe + +# BEISPIEL-DIALOG + +User: "Wir sollten Redis für das Caching verwenden." + +Sparring-Partner: +- "Was cacht ihr genau und wie groß sind die Objekte?" +- "Wie oft ändern sich die Daten?" +- "Was passiert wenn Redis ausfällt - habt ihr einen Fallback?" +- "Habt ihr die Speicherkosten kalkuliert?" +- "Wer im Team hat Redis-Erfahrung in Produktion?" diff --git a/skills/vault-janitor/SKILL.md b/skills/vault-janitor/SKILL.md index 5b8e2c8..6c359fa 100644 --- a/skills/vault-janitor/SKILL.md +++ b/skills/vault-janitor/SKILL.md @@ -1,6 +1,8 @@ --- name: vault-janitor -description: Wird aktiviert, um den Vault zu organisieren, Wissen zu destillieren und veraltete Informationen zu bereinigen. +description: Organisiert den Vault durch Memory Distillation, Skill Audits und Integrity Checks. Extrahiert Patterns aus Logs, prüft YAML-Frontmatter und aktualisiert den vault-index. Für Wartung und Aufräumen. +argument-hint: [mode: distill|audit|index|check] +allowed-tools: Read, Write, Edit, Glob, Grep --- # ROLE diff --git a/vault-index.md b/vault-index.md index cbb2084..c83c959 100644 --- a/vault-index.md +++ b/vault-index.md @@ -1,6 +1,6 @@ # 🗂️ CLAUDE VAULT INDEX -Dieses Repository ist das zentrale Gedächtnis und die Werkzeugkiste für meine Claude-Agenten. +Dieses Repository ist das zentrale Gedächtnis und die Werkzeugkiste für meine Claude-Agenten. --- @@ -10,28 +10,95 @@ Dieses Repository ist das zentrale Gedächtnis und die Werkzeugkiste für meine --- -## 🛠️ SKILLS (Spezialisierte Agenten) +## 🛠️ SKILLS (Spezialisierte Fähigkeiten) *Pfad: `/skills/`* -- **[architect](./skills/architect/SKILL.md):** Für Systemdesign, ADRs und Technologie-Entscheidungen. -- **[reviewer](./skills/reviewer/SKILL.md):** Kritischer Code-Reviewer für Sicherheit, Performance und Clean Code. -- **[doc-gen](./skills/doc-gen/SKILL.md):** Automatisierte Erstellung von technischer Dokumentation und READMEs. -- **[vault-janitor](./skills/vault-janitor/SKILL.md):** Wartungs-Agent zum Aufräumen des Vaults und Destillieren von Wissen. + +### League-Planner Skills (lp-*) +Spezialisiert auf das Django-basierte Liga-Planungssystem: + +| Skill | Beschreibung | Invocation | +|-------|--------------|------------| +| **[lp-django-model](./skills/django-model/SKILL.md)** | Django 5.2 Models mit Fat Model Pattern, Custom Managers | `/lp-django-model` | +| **[lp-drf-api](./skills/drf-api/SKILL.md)** | DRF API Endpoints mit @api_view, drf-spectacular | `/lp-drf-api` | +| **[lp-celery-task](./skills/celery-task/SKILL.md)** | Celery 5.5 Tasks mit AbortableTask, Progress Tracking | `/lp-celery-task` | +| **[lp-permissions](./skills/permissions/SKILL.md)** | Multi-Tier Permissions mit Decorators, Session-based Access | `/lp-permissions` | +| **[lp-query-optimizer](./skills/query-optimizer/SKILL.md)** | N+1 Query Fixes, select_related/prefetch_related | `/lp-query-optimizer` | +| **[lp-solver](./skills/solver/SKILL.md)** | PuLP/Xpress MIP Solver Integration | `/lp-solver` | +| **[lp-testing](./skills/testing/SKILL.md)** | Django TestCase mit Multi-DB Support, CRUD Tags | `/lp-testing` | + +### Allgemeine Skills +| Skill | Beschreibung | Invocation | +|-------|--------------|------------| +| **[skill-creator](./skills/skill-creator/SKILL.md)** | Meta-Skill zum Erstellen neuer Skills | `/skill-creator` | +| **[vault-janitor](./skills/vault-janitor/SKILL.md)** | Vault-Wartung, Memory Distillation, Integrity Checks | `/vault-janitor` | +| **[doc-gen](./skills/doc-gen/SKILL.md)** | Technische Dokumentation, READMEs, API-Docs | `/doc-gen` | +| **[reviewer](./skills/reviewer/SKILL.md)** | Code-Reviews für Sicherheit, Performance, Clean Code | `/reviewer` | +| **[sparring-partner](./skills/sparring-partner/SKILL.md)** | Sokratischer Mentor für Architektur-Diskussionen | `/sparring-partner` | + +--- + +## 🤖 AGENTS (Spezialisierte Agenten) +*Pfad: `/agents/`* + +### Django-Entwicklung +| Agent | Beschreibung | Farbe | +|-------|--------------|-------| +| **[league-planner-architect](./agents/league-planner-architect.md)** | Liga-Planer spezifisch: @api_view Pattern, Solver-Integration | 🟠 orange | +| **[django-architect](./agents/django-architect.md)** | Generisches Django: ViewSets + Routers (NICHT für league-planner!) | 🟢 green | +| **[django-mkdocs-docs](./agents/django-mkdocs-docs.md)** | MkDocs-Dokumentation für Django-Projekte | 🩷 pink | + +### Optimization & Compute +| Agent | Beschreibung | Farbe | +|-------|--------------|-------| +| **[mip-optimization-xpress](./agents/mip-optimization-xpress.md)** | Mixed-Integer Programming mit FICO Xpress | 🟣 purple | +| **[cluster-compute-architect](./agents/cluster-compute-architect.md)** | K3s-Cluster, Dockerfiles, CI/CD, Autoscaling | 🔵 blue | + +### Operations & Quality +| Agent | Beschreibung | Farbe | +|-------|--------------|-------| +| **[plg-monitoring-architect](./agents/plg-monitoring-architect.md)** | Prometheus, Loki, Grafana Monitoring | 🟡 yellow | +| **[debugging-specialist](./agents/debugging-specialist.md)** | Systematische Fehlerdiagnose, Root Cause Analysis | 🔴 red | +| **[code-reviewer](./agents/code-reviewer.md)** | Proaktive Code-Reviews nach Code-Änderungen | 🩵 cyan | --- ## 🧠 MEMORY (Erfahrungen & Muster) *Pfad: `/memory/`* -- **[/log/](./memory/log/):** Chronologische Sammlung von "Lessons Learned" aus vergangenen Sessions. -- **[patterns.md](./memory/patterns.md):** Destillierte Best Practices, die sich aus den Logs ergeben haben. + +| Datei/Ordner | Beschreibung | +|--------------|--------------| +| **[/log/](./memory/log/)** | Chronologische Sammlung von "Lessons Learned" aus vergangenen Sessions | +| **[/log/archive/](./memory/log/archive/)** | Archivierte Logs nach Pattern-Extraktion | +| **[patterns.md](./memory/patterns.md)** | Destillierte Best Practices aus den Logs | +| **[/snapshots/](./memory/snapshots/)** | Status-Reports zu bestimmten Zeitpunkten | --- ## 📚 KNOWLEDGE (Kontext & Daten) *Pfad: `/knowledge/`* -- **[preferences.md](./knowledge/preferences.md):** Meine persönlichen Vorlieben (Tech-Stacks, Coding-Styles, Abneigungen). -- **[project-context.md](./knowledge/project-context.md):** (Optional) Überblick über laufende Langzeit-Projekte. + +| Datei/Ordner | Beschreibung | +|--------------|--------------| +| **[preferences.md](./knowledge/preferences.md)** | Persönliche Vorlieben: Tech-Stacks, Coding-Styles | +| **[/anti-patterns/](./knowledge/anti-patterns/)** | Dokumentierte Fehler, die vermieden werden sollen | + +--- + +## 📋 PROPOSALS +*Pfad: `/skills/proposals/`* + +Enthält Skill-Entwürfe, die auf Review warten. Erstellt von `/skill-creator`, geprüft von `/vault-janitor`. --- ## 🛠 WARTUNG -Der **Vault Janitor** ist dafür verantwortlich, diesen Index aktuell zu halten. Bei jedem neuen Skill oder größeren Strukturänderung sollte der Index aktualisiert werden. \ No newline at end of file + +Der **Vault Janitor** (`/vault-janitor`) ist verantwortlich für: +- **Memory Distillation**: Patterns aus `/memory/log/` extrahieren +- **Skill Audit**: YAML-Frontmatter und Konflikte prüfen +- **Index Update**: Diesen Index aktuell halten +- **Integrity Check**: Verwaiste Dateien finden + +--- + +*Letzte Aktualisierung: 2026-02-04*