Cursor Rules, Skills & Hooks

Cursor Rules, Skills und Hooks sind das Policy-as-Code-Layer agentischer Entwicklung. Ohne sie ist jeder Agent-Run ein Unikat; mit ihnen werden Runs reproduzierbar, auditierbar und teamfähig. Agenticode in Köln etabliert diese drei Bausteine als Standard in jedem Agentic-Engineering-Engagement.

Rules: globale und kontextuelle Policies

Cursor Rules sind Markdown-Dateien mit Always-Apply- oder Glob-Scopes. Sie definieren: erlaubte Sprachen, Architektur-Layer, verbotene Patterns, Commit-Konventionen, Test-Pflichten. Rules werden versioniert in .cursor/rules/ – Teil des Repos, nicht der individuellen IDE.

Agenticode strukturiert Rules hierarchisch: base.mdc (Projekt-weit), domain/*.mdc (pro Bounded Context), task/*.mdc (temporär für Refactoring-Sprints). So bekommt der Agent im Billing-Modul andere Constraints als im Auth-Modul.

Gute Rules sind spezifisch und testbar: „Kein SQL in Controllers“ ist besser als „schreib sauberen Code“. Noch besser: Verweis auf PHPStan-Regel-IDs, die Verstöße automatisch fangen.

Base Rule: Architektur, Agent-Verhalten und PHP-Standards.

# .cursor/rules/base.mdc
---
description: Agenticode Base Policy – immer aktiv
globs: ["**/*"]
alwaysApply: true
---

## Architektur
- Domain-Logik nur in `src/Services/**`
- Persistence nur in `src/Repositories/**`
- Keine Secrets in Code – nur `config.env` / Env-Vars

## Agent-Verhalten
- Max. 400 Zeilen Diff pro Run
- Nach jedem Act: `composer phpstan && vendor/bin/phpunit`
- Bei Schema-Änderungen: Human-Gate

## PHP
- `declare(strict_types=1);` in jeder neuen Datei
- PSR-12, PHPStan Level 8

Skills: wiederverwendbare Expertise-Pakete

Skills sind strukturierte Anweisungspakete für spezifische Aufgaben – z.B. „PHPUnit-Test für Service schreiben“, „MCP-Tool registrieren“, „ADR verfassen“. Sie kapseln Best Practices, die sonst in jedem Prompt neu erklärt werden müssten.

Agenticode pflegt einen Skill-Katalog pro Kunde: generische Skills (Testing, Security) plus domänenspezifische (Billing-MwSt-Regeln, Multi-Tenant-Context). Skills werden in .cursor/skills/ oder als verlinkte SKILL.md-Dateien abgelegt.

Der Vorteil gegenüber langen Prompts: Skills sind reviewbar, versionierbar und onboarding-tauglich. Neue Teammitglieder aktivieren denselben Skill wie erfahrene Agentic Engineers – konsistentes Ergebnis.

Skill-Template: klare Schritte und Verbote für Service-Tests.

# Skill: PHPUnit Service Test (Agenticode)

## Wann nutzen
Neuer oder geänderter Service in `src/Services/`

## Schritte
1. Testdatei unter `tests/Services/{Name}Test.php`
2. Mock nur externe Dependencies (DB, HTTP)
3. Arrange-Act-Assert, ein Assert-Fokus pro Test
4. `vendor/bin/phpunit --filter={Name}Test` muss grün sein

## Verboten
- `@group` ohne Begründung
- `sleep()` in Tests
- Produktions-DB-Zugriff

Hooks: Automatisierung an Agent-Events

Cursor Hooks feuern bei Events wie beforeSubmitPrompt, afterAgentResponse, beforeShellExecution. Sie automatisieren Observe-Schritte, blockieren gefährliche Shell-Commands, oder injizieren Kontext aus externen Systemen.

Agenticode nutzt Hooks für: Diff-Limit-Check vor Commit, automatischer PHPUnit-Lauf nach Agent-Response, Blocklist für rm -rf und Produktions-Deploy-Commands. Hooks sind Bash- oder Node-Skripte in .cursor/hooks.json registriert.

Zusammen bilden Rules (was gilt), Skills (wie tun) und Hooks (was automatisch passiert) das Policy-as-Code-Dreieck. Es macht Agent-Runs in Köln und remote gleichermassen vorhersagbar – unabhängig davon, wer den Prompt schreibt.

hooks.json: Shell-Blocklist, Observe nach Agent, Kontext-Injektion.

{
  "version": 1,
  "hooks": {
    "beforeShellExecution": [
      {
        "command": ".cursor/hooks/block-dangerous-shell.sh",
        "matcher": "rm|curl.*production|deploy.*prod"
      }
    ],
    "afterAgentResponse": [
      {
        "command": ".cursor/hooks/run-observe-checks.sh"
      }
    ],
    "beforeSubmitPrompt": [
      {
        "command": ".cursor/hooks/inject-architecture-context.sh"
      }
    ]
  }
}