Regelsysteme & Verhaltenssteuerung

Regeldateien sind Markdown-Dokumente, die festlegen, wie sich Verdent während Coding-Sitzungen verhält und reagiert. Sie steuern das Verhalten des KI-Agents, die Ausgabeformatierung, Entscheidungsfindung und die Einhaltung von Projektstandards.

Zweck: Regeln ermöglichen es Ihnen, das Verhalten von Verdent anzupassen, ohne Code oder Einstellungen zu ändern. Sie legen Coding-Konventionen, bevorzugte Muster, Kommunikationsstil und Präferenzen für die Aufgabenausführung fest, die über Sitzungen hinweg bestehen bleiben.

Wie Regeln funktionieren: Verdent bezieht sich während Gesprächen fortlaufend auf Regeldateien und wendet die Richtlinien auf Codegenerierung, Analyse, Dokumentation und Entscheidungsfindung an. Regeln beeinflussen jede Antwort des Agents, um Konsistenz mit den Präferenzen des Nutzers zu gewährleisten.

Drei Kategorien:

• Globale Präferenzen (VERDENT.md) – Persönlicher Coding-Stil, Sprachpräferenzen
• Projektspezifische Standards (AGENTS.md) – Teamkonventionen, Architekturmuster
• Plananpassung (Plan.md) – Ausgabeformat und Inhalt von Plan Mode

Regelpriorität: Bei widersprüchlichen Regeln wendet Verdent folgende Priorität an: AGENTS.md (höchste) → VERDENT.md (mittel) → Standardeinstellungen (niedrigste)

Nutzerregeln (VERDENT.md)

VERDENT.md legt globale Präferenzen fest, die für alle Projekte und Sitzungen gelten. Sie definiert persönlichen Coding-Stil, bevorzugte Werkzeuge, Kommunikationspräferenzen und Standardverhalten.

Speicherort und Geltungsbereich

Speicherort der Datei: ~/.verdent/VERDENT.md

Geltungsbereich: Global für alle Projekte

Zugriff:

• Einstellungen → Regeln → Nutzerregeln
• Direkte Dateibearbeitung unter ~/.verdent/VERDENT.md

Wirksamwerden von Änderungen: Regeln gelten sofort in neuen Gesprächen und beeinflussen auch Antworten im laufenden Gespräch.

Anwendungsfälle

Format und Syntax

VERDENT.md verwendet einfaches Markdown-Format mit Aufzählungspunkten oder nummerierten Listen.

Struktur:

# User Rules

## Code Style Preferences
- Always use TypeScript strict mode
- Prefer functional components in React
- Include JSDoc comments for exported functions

## Documentation
- Add JSDoc comments for all exported functions
- Include usage examples in component documentation

## Communication
- Provide explanations before showing code
- Highlight breaking changes explicitly

Schreibstil:

• Verwenden Sie klare, direktive Sprache („Verwende immer...", „Bevorzuge...", „Niemals...")
• Gliedern Sie in logische Abschnitte mit Überschriften
• Aufzählungspunkte für einzelne Regeln
• Seien Sie konkret zum gewünschten Verhalten

Beispiele nach Entwicklertyp

# User Rules

## TypeScript Preferences
- Use strict mode in tsconfig.json
- Prefer interfaces over type aliases for object shapes
- Include return types on all functions
- Use const assertions where appropriate

## Code Organization
- One component per file
- Named exports instead of default exports
- Organize imports: external, internal, types

## Documentation
- TSDoc comments for public APIs
- Include @param and @returns tags

# User Rules

## Python Style
- Follow PEP 8 conventions
- Use type hints for function signatures
- Prefer list comprehensions over map/filter

## Data Analysis
- Use pandas for data manipulation
- Include DataFrame.head() after transformations
- Document assumptions about data

## Output Format
- Show shape and info() after operations
- Include visualization examples

# User Rules

## JavaScript Preferences
- Use ES6+ features (arrow functions, destructuring)
- Async/await over promises
- Template literals for string interpolation

## Testing
- Jest for unit tests
- Include test cases for edge conditions
- Aim for 80%+ code coverage

## Code Review
- Flag potential performance issues
- Suggest security improvements

# User Rules

## Communication
- Always respond in French
- Use technical English terms when no French equivalent exists
- Provide French variable/function names when appropriate

## Code Comments
- Write comments in French
- Documentation in both French and English

# User Rules

## Code Style
- Minimal comments - code should be self-documenting
- Short, focused functions (< 20 lines)
- Avoid unnecessary abstractions

## Output Preferences
- Brief explanations
- Show code first, explain after
- No verbose documentation unless requested

Erstellen und Bearbeiten

Projektregeln (AGENTS.md)

AGENTS.md legt projektspezifische Regeln fest, die das Verhalten des Agents im aktuellen Projekt steuern. Sie definiert Team-Coding-Standards, Architekturmuster, Testanforderungen und projektspezifische Entwicklungsworkflows.

Speicherort und Geltungsbereich

Speicherort der Datei: Projektstammverzeichnis

Geltungsbereich: Nur aktuelles Projekt

Versionskontrolle: Kann für die teamweite Weitergabe in git eingecheckt werden

Zugriff:

• Einstellungen → Regeln → Projektregeln
• Direkte Bearbeitung unter <project-root>/AGENTS.md

Anwendungsfälle

Teamzusammenarbeit: AGENTS.md wird im Projektstammverzeichnis gespeichert und kann in die Versionskontrolle eingecheckt werden, sodass alle Teammitglieder mit einem konsistenten Agentenverhalten arbeiten.

Format und Syntax

AGENTS.md verwendet Markdown-Format mit strukturierten Abschnitten und Aufzählungspunkten, ähnlich wie VERDENT.md, jedoch mit Fokus auf projektspezifische Anforderungen.

Struktur:

# AGENTS.md

## Dev environment tips
- Command for navigating workspace
- Installation commands
- Environment setup instructions

## Testing instructions
- Test execution commands
- Coverage requirements
- CI/CD integration details

## PR instructions
- Title format requirements
- Pre-commit checklist
- Review guidelines

Schreibstil:

• Direktive, anweisende Sprache
• Gegliedert nach Workflow-Bereich (Entwicklung, Tests, Deployment)
• Konkrete Befehle und Verfahren
• Teamweite Standards, keine persönlichen Präferenzen

Beispiele nach Projekttyp

# AGENTS.md

## Dev environment tips
- Use `pnpm dlx turbo run where <project_name>` to jump to a package
- Run `pnpm install --filter <project_name>` to add package to workspace
- Check the name field in package.json to confirm the right name

## Testing instructions
- Run `pnpm turbo run test --filter <project_name>` for all checks
- From package root: `pnpm test`
- Focus on one test: `pnpm vitest run -t "<test name>"`
- Fix all errors before merge

## PR instructions
- Title format: [<project_name>] <Title>
- Always run `pnpm lint` and `pnpm test` before committing

# AGENTS.md

## Code Standards
- Use functional components with hooks
- TypeScript strict mode required
- Named exports only (no default exports)
- PropTypes or TypeScript interfaces for all components

## File Organization
- One component per file
- Components in `src/components/`
- Hooks in `src/hooks/`
- Utils in `src/utils/`

## Testing
- Jest + React Testing Library
- Test all user interactions
- 80%+ coverage required

# AGENTS.md

## API Standards
- All endpoints include input validation
- Use async/await for asynchronous operations
- Consistent error format: { error: string, code: number }
- Rate limiting on public endpoints

## Security
- Never log sensitive data (passwords, tokens, PII)
- Parameterized queries only (prevent SQL injection)
- Validate and sanitize all inputs

## Testing
- Unit tests for all business logic
- Integration tests for API endpoints
- Test success and error cases

# AGENTS.md

## Platform Support
- iOS 14+ and Android API 26+
- React Native 0.72+
- Test on both platforms before PR

## State Management
- Use Redux Toolkit
- Async operations with Redux Thunk
- Normalize state shape

## Performance
- Images: WebP format, max 500KB
- Bundle size: monitor with bundle analyzer
- FlatList for long lists (>20 items)

# AGENTS.md

## Django Conventions
- Follow Django best practices and PEP 8
- Class-based views preferred
- Django ORM for database operations
- Migrations: never edit generated files

## Testing
- pytest-django for all tests
- Factory Boy for test fixtures
- Coverage must be 90%+

## Deployment
- Docker compose for local development
- Environment variables in .env (never committed)
- Run migrations before deployment

Unterschiede zu VERDENT.md

Geltungsbereich:

• VERDENT.md: Persönliche Präferenzen für alle Projekte
• AGENTS.md: Teamstandards nur für das jeweilige Projekt

Priorität:

• AGENTS.md: Höhere Priorität – überschreibt Nutzerregeln zugunsten der Projektkonsistenz
• VERDENT.md: Niedrigere Priorität – gilt, wenn keine projektspezifische Regel im Widerspruch steht

Inhaltlicher Fokus:

• VERDENT.md: Individueller Coding-Stil, Kommunikationspräferenzen, persönliche Werkzeuge
• AGENTS.md: Teamkonventionen, Projektarchitektur, gemeinsame Workflows, Technologie-Stack

Versionskontrolle:

• VERDENT.md: Nicht geteilt – bleibt auf dem Rechner der einzelnen Person
• AGENTS.md: In git eingecheckt – mit dem gesamten Team geteilt

Speicherort:

• VERDENT.md: ~/.verdent/VERDENT.md (global)
• AGENTS.md: Projektstammverzeichnis (projektspezifisch)

Beispiel für Konfliktlösung:

VERDENT.md: "I prefer 2-space indentation"
AGENTS.md: "This project uses 4-space indentation"
→ Result: 4-space indentation (team standard wins)

Wann welche Datei verwenden:

• VERDENT.md: Persönliche Präferenzen, die Sie für alle Projekte wünschen
• AGENTS.md: Standards, die das gesamte Team für dieses Projekt befolgen muss

Planregeln (Plan.md)

Plan.md passt den Inhalt und das Format der in Plan Mode generierten Pläne an. Sie steuert das Detailniveau des Plans, enthaltene Abschnitte, Formatierungspräferenzen und angezeigte Informationen.

Speicherort und Geltungsbereich

Speicherort der Datei: ~/.verdent/plan_settings.json

Geltungsbereich: Global für alle Projekte

Anwendung: Wird nur während Plan Mode bei der Generierung von Plänen angewendet

Zugriff:

• Einstellungen → Regeln → Planregeln
• Direkte Dateibearbeitung unter ~/.verdent/plan_settings.json

Anwendungsfälle

Format und Syntax

Plan.md verwendet Markdown-Format mit Abschnitten, die die gewünschte Planstruktur und den Inhalt beschreiben.

Struktur:

---
name: Plan Rules
version: 1.0.0
last_updated: 2025-11-26
---

## Plan Structure
- Start with brief summary (2-3 sentences)
- Include estimated time for each major step
- List prerequisites before implementation steps
- Identify potential risks

## Level of Detail
- Break tasks into subtasks of 15-30 minutes
- Include specific file paths for modifications
- List functions/components to create/modify

## Format
- Use numbered lists for sequential steps
- Use bullet points for options
- Include code snippets for complex changes

Beispiele nach Planungsstil

---
name: Detailed Technical
version: 1.0.0
last_updated: 2025-11-26
---

## Plan Structure
- Executive summary (2-3 sentences)
- Prerequisites and dependencies
- Numbered implementation steps
- Testing and verification strategy
- Rollback procedures

## Level of Detail
- Break into 20-30 minute tasks
- Specific file paths for all modifications
- Function signatures for new code
- Database schema changes with migration steps

## Format
- Numbered lists for sequence
- Code blocks for complex logic
- Diagrams for architecture changes (describe verbally)

---
name: High-Level Strategic
version: 1.0.0
last_updated: 2025-11-26
---

## Plan Structure
- Brief overview (1 paragraph)
- Major phases only (3-5 high-level steps)
- Key decisions and trade-offs
- Success criteria

## Level of Detail
- High-level phases (1-2 hours each)
- Avoid implementation specifics
- Focus on approach and strategy

## Format
- Bullet points for flexibility
- Minimal code examples
- Emphasize "why" over "how"

---
name: Time-Conscious
version: 1.0.0
last_updated: 2025-11-26
---

## Plan Structure
- Time estimates for each step
- Total project duration estimate
- Parallel tasks identified
- Critical path highlighted

## Level of Detail
- Tasks sized to 30-minute increments
- Dependencies clearly marked
- Blocking operations identified

## Format
- Include time estimates inline
- Mark parallel tasks
- Highlight critical path with bold

---
name: Risk-Focused
version: 1.0.0
last_updated: 2025-11-26
---

## Plan Structure
- Risk assessment for each phase
- Mitigation strategies included
- Rollback procedures defined
- Testing requirements emphasized

## Level of Detail
- Identify potential failure points
- Document error handling approach
- Include recovery procedures

## Format
- Risk levels: low, medium, high
- Separate "Risks" section for each phase
- Mitigation steps in sub-bullets

---
name: Team Collaboration
version: 1.0.0
last_updated: 2025-11-26
---

## Plan Structure
- Role assignments for each task
- Coordination points identified
- Review checkpoints included
- Communication requirements

## Level of Detail
- Specify who handles each component
- List integration points between team members
- Include pair programming opportunities

## Format
- Use mentions for role assignments
- Mark collaboration points
- Include "Review required" markers

Wann werden Planregeln angewendet?

Anwendung von Planregeln:

• Zeitpunkt: Wird nur während Plan Mode bei der Generierung von Plänen angewendet
• Geltungsbereich: Steuert Planformat und -inhalt, nicht die Codegenerierung
• Unabhängigkeit: Steht nicht im Konflikt mit VERDENT.md oder AGENTS.md

Anwendung anderer Regeltypen:

• VERDENT.md: Wird fortlaufend in allen Modi angewendet (Agent, Plan, Chat)
• AGENTS.md: Wird fortlaufend in allen Modi für projektspezifisches Verhalten angewendet

Beispiel für das Zusammenspiel:

Plan Mode activated:
1. VERDENT.md: "Use TypeScript" → Applied to code in plan
2. AGENTS.md: "Follow project conventions" → Applied to approach
3. plan_rules.md: "Include time estimates" → Applied to plan format
→ Result: Plan shows TypeScript code following project conventions with time estimates

Modusspezifisches Verhalten:

• Agent Mode: VERDENT.md + AGENTS.md angewendet (keine plan_rules.md)
• Plan Mode: VERDENT.md + AGENTS.md + Plan.md werden alle angewendet
• Chat Mode: VERDENT.md + AGENTS.md angewendet (kein Plan.md)

Regelpriorität und Konfliktlösung

Bei widersprüchlichen Regeln wendet Verdent eine Priorität an, um ein konsistentes Verhalten zu gewährleisten.

Prioritätsreihenfolge

1. Projektregeln (AGENTS.md) – Höchste Priorität Projektspezifische Regeln überschreiben globale Präferenzen. Teamstandards haben Vorrang vor individuellen Präferenzen im Sinne der Konsistenz.

2. Nutzerregeln (VERDENT.md) – Mittlere Priorität Globale Präferenzen gelten, wenn keine projektspezifische Regel im Widerspruch steht.

3. Standardverhalten – Niedrigste Priorität Die integrierten Standardeinstellungen von Verdent gelten, wenn keine Regeln festgelegt sind.

Beispiel für Konfliktlösung:

VERDENT.md: "Use 2-space indentation"
AGENTS.md: "Use 4-space indentation for this project"
→ Result: Verdent uses 4-space indentation (project rules win)

Planregeln: Plan.md wird während Plan Mode unabhängig angewendet und steht nicht im Konflikt mit Nutzer- oder Projektregeln. Sie steuert das Planformat, während VERDENT.md und AGENTS.md den Codestil innerhalb des Plans steuern.

Fehlerbehebung bei Regelkonflikten

Wenn Sie ein unerwartetes Verhalten beobachten, das einer Regel widerspricht, folgen Sie dieser Debug-Strategie:

Schritt 1: Konflikt identifizieren

1. Beobachten Sie unerwartetes Verhalten, das einer Regel widerspricht
2. Prüfen Sie, welche Regeln auf die Situation zutreffen könnten
3. Suchen Sie nach Widersprüchen zwischen den Regeldateien

Schritt 2: Regelpriorität prüfen

AGENTS.md (highest) → VERDENT.md (medium) → defaults (lowest)

Projektregeln überschreiben persönliche Präferenzen.

Schritt 3: Isoliert testen

VERDENT.md deaktivieren: Datei vorübergehend umbenennen oder leeren, prüfen, ob sich der Konflikt löst

Ohne AGENTS.md testen: Im Projekt ohne AGENTS.md arbeiten, um das Verhalten der Nutzerregeln zu isolieren

Neues Gespräch: Eine neue Sitzung starten, um den Einfluss des Gesprächskontexts auszuschließen

Häufige Konfliktszenarien

Szenario 1: Formatierungskonflikt

VERDENT.md: "Use 2-space indentation"
AGENTS.md: "Use 4-space indentation"
→ Resolution: AGENTS.md wins (project standard)
→ Fix: Accept project standard or discuss with team

Szenario 2: Widersprüchliche Regeln in derselben Datei

AGENTS.md:
- "Prefer functional components"
- "Use class components for complex state"
→ Resolution: Verdent interprets based on context
→ Fix: Clarify when each rule applies

Beispielhafte Lösung:

- Prefer functional components for simple UI
- Use functional components with hooks for complex state
- Only use class components for legacy code maintenance

Szenario 3: Regel zu vage

"Write good tests"
→ Problem: What is "good"?
→ Fix: "Generate unit tests with 80%+ coverage, include edge cases"

Debug-Strategie

1. Expliziter Test: Fragen Sie Verdent: „Welcher Regel folgst du für [spezifisches Verhalten]?"

Beispiel:

You: "Which rule are you following for indentation?"
Verdent: "I'm using 4-space indentation from AGENTS.md (line 12),
which overrides your VERDENT.md preference for 2-space indentation."

2. Schrittweise Verfeinerung: Fügen Sie mehrdeutigen Regeln zusätzliche Konkretisierung hinzu

Vorher:

- Use appropriate error handling

Nachher:

- Wrap async operations in try/catch blocks
- Return error objects with message and code fields
- Log errors with context (function name, input parameters)

3. Prioritätsmarkierungen: Verwenden Sie „CRITICAL:" oder „REQUIRED:" für nicht verhandelbare Regeln

## Security Rules
- **CRITICAL:** Never log passwords, API keys, or tokens
- **REQUIRED:** All user inputs must be validated and sanitized
- Preferred: Use parameterized queries for database operations

Best Practices für das Schreiben von Regeln

Seien Sie konkret und direktiv:

• Verwenden Sie klare, imperative Sprache („Verwende immer...", „Niemals...", „Bevorzuge...")
• Vermeiden Sie mehrdeutige Formulierungen („Versuche..." → „Immer...")
• Legen Sie genau fest, was Sie wollen, nicht was Sie nicht wollen

Gut:

- Use async/await for asynchronous operations
- Include JSDoc comments for all exported functions

Vermeiden:

- Try to use modern JavaScript features
- Add comments when necessary

Logisch organisieren:

• Gruppieren Sie zusammengehörige Regeln unter Abschnittsüberschriften
• Trennen Sie Belange (Stil, Tests, Dokumentation, Sicherheit)
• Verwenden Sie eine konsistente Struktur über alle Regeldateien hinweg

Regeln wartbar halten:

• Schreiben Sie prägnante Regeln (ein Konzept pro Aufzählungspunkt)
• Überprüfen und aktualisieren Sie Regeln, während sich das Projekt weiterentwickelt
• Entfernen Sie veraltete Regeln zeitnah

Wichtige Regeln priorisieren:

• Platzieren Sie kritische Regeln zuerst in jedem Abschnitt
• Nutzen Sie Hervorhebungen für nicht verhandelbare Standards („NIEMALS Zugangsdaten committen")
• Konzentrieren Sie sich auf Regeln, die Bugs oder Sicherheitsprobleme verhindern

Wirksamkeit der Regeln testen:

• Überprüfen Sie, ob Verdent die Regeln in der Praxis befolgt
• Starten Sie ein neues Gespräch, um die Regelanwendung zu testen
• Verfeinern Sie Regeln basierend auf dem tatsächlichen Verhalten des Agents

Detailgrad und Flexibilität ausbalancieren:

• Zu konkret → starres Verhalten, das sich nicht anpasst
• Zu vage → inkonsistentes Verhalten
• Streben Sie klare Anweisungen mit Spielraum für kontextangemessene Entscheidungen an

Team-Überlegungen (AGENTS.md):

• Beziehen Sie das Team in die Regelerstellung ein
• Dokumentieren Sie die Begründung für nicht offensichtliche Regeln
• Konzentrieren Sie Teamregeln auf gemeinsame Standards, nicht auf persönliche Präferenzen

Siehe auch