Gerüst für KI-Agenten im Projekt einrichten

Projektstruktur für leistungsstarke AI-Agenten

KI-Agenten profitieren von klarer, konsistenter Projektstruktur. Eine gut durchdachte Grundlage ermöglicht es Agenten, die Architektur zu verstehen, Tests durchzuführen und mit der Umgebung zu interagieren – ohne ständige Nachhilfe. Diese Prinzipien gelten für Tools wie Claude Code, Cursor und andere.

Kernregeln konfigurieren

Beginnen Sie mit einer einzigen Datei im Projektstamm – CLAUDE.md oder deren Äquivalent für Ihren Agenten. Beschreiben Sie dort die Verzeichnisstruktur, zentrale Befehle und allgemeine Entwicklungsrichtlinien. Vermeiden Sie detaillierte Implementierungshinweise: Der Code selbst wird zur Dokumentation.

Beispiel-Grunddatei:

## Struktur
├── src/           — Service-Code
├── tests/         — Test-Suite
├── migrations/    — Alembic-Datenbank-Migrationen
└── notebooks/     — Ad-hoc-Skripte

## Befehle
- Tests: `pytest tests/ -x`
- Linter: `ruff check . --fix`
- Migrationen: `alembic upgrade head`
- Ausführen: `docker compose up`

Diese Einrichtung vermeidet wiederholte Erklärungen zur Architektur und Routinetätigkeiten. Setzen Sie Code-Standards über Skripte durch – nicht über Handbücher.

Wenn ein Agent Fehler macht – analysieren Sie den Kontext. Falls er Methoden dupliziert oder Klassen falsch platziert, ergänzen Sie modulare Regel-Dateien.

``

something-cool/

├── CLAUDE.md # Allgemeine Regeln

├── src/

│ ├── auth/

│ │ ├── CLAUDE.md # SSO-Regeln

│ │ └── ...

│ ├── billing/

│ │ ├── CLAUDE.md # Vertragsbasierte Änderungen

│ │ └── ...

``

Anzeichen einer unvollständigen Einrichtung:

• Der Agent sucht manuell nach Modulen.
• Begeht grundlegende Fehler bei Abhängigkeiten oder Registrierung.

Umgebungsintegration über Skills

Agenten arbeiten nicht nur mit Code – sie interagieren mit Logs, Metriken und Datenbanken. Nutzen Sie Skills, um externe Dienste zu integrieren: definieren Sie Funktionen und stellen ausführbare Skripte bereit.

Struktur eines Skills:

.claude/
└── skills/
    ├── logs/
    │   ├── SKILL.md
    │   └── search_logs.py
    ├── metrics/
    │   ├── SKILL.md
    │   └── query_grafana.py
    ├── database/
    │   ├── SKILL.md

Beispiel SKILL.md für Logs:

---
name: logs
description: Suche und Analyse von Anwendungslogs
allowed-tools: Bash, Read
---

Verwenden Sie dieses Skript, um Logs zu durchsuchen:
python .claude/skills/logs/search_logs.py --query "error" --since "1h"
python .claude/skills/logs/search_logs.py --trace-id "abc123"

Nun kann der Agent eigenständig Erkenntnisse gewinnen und Probleme beheben.

Kompatibilität zwischen Repositories und Teams

Teilen Sie Skills zwischen Projekten über öffentliche Marktplätze oder interne Lösungen. Das senkt die Einstiegshürde für Kollegen.

Um verschiedene Agenten innerhalb eines Teams abzustimmen, nutzen Sie Rulesync – ein CLI-Tool, das aus einer Quelle Anweisungsdateien für über 25 Tools generiert.

Rulesync-Struktur:

.rulesync/rules/
├── overview.md          # root: true
├── auth.md              # globs: ["src/auth/**"]
└── billing.md           # globs: ["src/billing/**"]

Markdown-Dateien mit Frontmatter:

---
root: false
globs: ["src/auth/**"]
targets: "*"
description: Regeln für SSO-Integration
---
Regeln hier einfügen

Generierung:

• rulesync generate --targets "claudecode"
• rulesync generate --targets "cursor"
• rulesync generate --targets "copilot"

Ergebnis: CLAUDE.md, .cursorrules, copilot-instructions.md werden korrekt platziert.

Hintergrund-Agenten für Überwachung

Fügen Sie Hintergrund-Agenten hinzu, um Stil, Struktur und toten Code zu überwachen:

``

claude -p "Prüfe Stil: Benennung, Struktur, toter Code" \

--allowedTools "Read,Grep,Glob"

``

Das automatisiert Code-Reviews.

Wichtige Erkenntnisse

• Modulare Regeln: Platzieren Sie CLAUDE.md in Unterverzeichnissen für bessere Kontextklarheit.
• Umgebungsskills: Skripte + Anleitungen für Zugriff auf Logs, Metriken, Datenbanken.
• Rulesync: Einheitliche Quelle für mehrfache Agenten-Konsistenz.
• Evolution: Erweitern Sie Regeln, sobald Fehler auftreten.
• Minimalismus: Konzentrieren Sie sich ausschließlich auf Struktur und Befehle – keine Implementierungsdetails.

— Editorial Team