# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Repository Purpose

Personal Claude Code configuration vault containing reusable skills, custom agents, and system instructions. Referenced via `systemPromptPath` in Claude Code settings.

## Structure

```
claude-vault/
├── skills/           # Modular skills (SKILL.md files)
│   ├── skill-creator/    # Meta-skill for generating new skills
│   ├── django-model/     # lp-django-model: Django 6 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/ # Socratic technical discussions
├── agents/           # Custom agent configurations
│   ├── 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
│   ├── preferences.md
│   └── anti-patterns/
├── memory/           # Learning & patterns
│   ├── log/              # Session logs
│   ├── snapshots/        # Status reports
│   └── patterns.md       # Distilled best practices
└── vault-index.md    # Navigation index (German)
```

## Configuration

Add to `~/.claude/settings.json`:
```json
{
  "global": {
    "systemPromptPath": "/path/to/claude-vault/system/global-instructions.md"
  }
}

# Erstelle einen Symlink für jeden Unterordner in deinem Vault-Skills-Verzeichnis
ln -s /Absoluter/Pfad/zu/deinem/claude-vault/skills/* ~/.claude/skills/
ln -s /Absoluter/Pfad/zu/deinem/claude-vault/agents/* ~/.claude/agents/
claude mcp add vault --scope user -- npx -y @modelcontextprotocol/server-filesystem /Absoluter/Pfad/zu/deinem/claude-vault
```

## Persistent Permissions

Claude Code speichert erteilte Berechtigungen projektspezifisch über Sessions hinweg:
- **Command permissions**: Einmal erlaubte Bash-Befehle werden für das Projekt gespeichert
- **File permissions**: Lese-/Schreibrechte für Dateien und Verzeichnisse bleiben erhalten
- Speicherort: `.claude/` im Projektverzeichnis
- Zurücksetzen: Permissions manuell in den Projekteinstellungen widerrufen oder `.claude/` löschen

## Skills Format

```yaml
---
name: skill-name                      # lowercase, hyphens only
description: Max 200 chars            # CRITICAL for auto-invocation
argument-hint: <required> [optional]
allowed-tools: Read, Write, Edit, Glob, Grep
---
```

- `description` determines when Claude auto-detects skill usage
- Invocation: `/skill-name`
- Location: `~/.claude/skills/[name]/SKILL.md`

## Agents Format

```yaml
---
name: agent-name
description: Multi-line description with usage examples
model: sonnet|opus|haiku
color: green|orange|blue
---
```

## Language Rules

- User interaction: German
- Code comments: English
- Style: Direct, no filler phrases, focus on code and facts

## Priority Hierarchy

1. Project-specific `CLAUDE.md` (highest)
2. Skills from `/skills`
3. `global-instructions.md`
4. General training (lowest)

## Key Workflows

### Vault Maintenance (`/vault-janitor`)
- Memory Distillation: Scan `/memory/log/`, extract patterns to `patterns.md`
- Skill Audit: Verify YAML frontmatter, check for conflicts
- Index Update: Keep `vault-index.md` current
- Integrity Check: Find orphaned files

### Skill Creation (`/skill-creator`)
```
/skill-creator [category] [technology] [skill-name]
```
Categories: `fullstack` (Django, React, Next.js, PostgreSQL, Celery, Redis) or `devops` (GitLab CI/CD, Docker, K3s, Hetzner, Prometheus, Grafana)

## League-Planner vs Generic Django

| Context | Agent | API Pattern |
|---------|-------|-------------|
| league-planner | `league-planner-architect` | `@api_view` function-based |
| Generic Django | `django-architect` | ViewSets + Routers |

**Important**: For league-planner projects, always use `@api_view` patterns, NOT ViewSets/Routers.