Système Playbooks

Les Playbooks sont le cerveau contextuel de Hatcher - un système de fichiers de contexte dynamiques et évolutifs qui enseignent à l'IA comment comprendre, naviguer et modifier votre projet selon vos standards exacts.

Qu'est-ce qu'un Playbook ?

Un Playbook est un document vivant qui capture :

• Règles Architecturales : Modèles et conventions de votre projet
• Standards de Code : Style, nommage et meilleures pratiques
• Contexte Métier : Logique domaine et exigences spécifiques
• Apprentissage Adaptatif : Amélioration continue basée sur vos interactions

Types de Playbooks

1. Playbooks Système (Automatiques)

Générés automatiquement par l'analyse de votre base de code :

// Exemple : Détection automatique de modèles
{
  "pattern_type": "component_structure",
  "detected_at": "2024-01-15T10:30:00Z",
  "pattern": {
    "file_naming": "PascalCase",
    "props_interface": "Props",
    "styling_approach": "tailwind_classes",
    "state_management": "pinia"
  },
  "confidence": 0.95,
  "examples": [
    "src/components/UserProfile.vue",
    "src/components/ProjectCard.vue"
  ]
}

2. Playbooks Projet (Configurés)

Définis explicitement pour votre projet :

# .hatcher/playbooks/component-standards.yml
name: 'Standards de Composants'
version: '1.0'
scope: 'components'

rules:
  naming:
    files: 'PascalCase'
    props: 'camelCase'
    events: 'kebab-case'

  structure:
    template_order: ['template', 'script', 'style']
    composition_api_required: true

  styling:
    framework: 'tailwindcss'
    custom_classes_prefix: 'app-'
    responsive_breakpoints: ['sm', 'md', 'lg', 'xl']

3. Playbooks Équipe (Partagés)

Synchronisés entre les membres de l'équipe :

{
  "team_standards": {
    "commit_messages": {
      "format": "conventional_commits",
      "scopes": ["ui", "api", "docs", "test"]
    },
    "code_review": {
      "required_approvals": 2,
      "automated_checks": ["lint", "test", "build"]
    },
    "documentation": {
      "jsdoc_required": true,
      "readme_sections": ["installation", "usage", "api"]
    }
  }
}

Comment les Playbooks Fonctionnent

1. Découverte Automatique

Hatcher analyse votre projet pour découvrir :

// Analyse des modèles de fichiers
const patterns = await analyzeProject({
  paths: ['src/**/*.vue', 'src/**/*.ts'],
  exclude: ['node_modules', 'dist'],
})

// Détection des conventions
const conventions = {
  componentNaming: detectNamingPattern(patterns.components),
  stateManagement: detectStatePattern(patterns.stores),
  routingStructure: detectRoutingPattern(patterns.routes),
}

2. Génération de Contexte

Lors d'une interaction IA, les Playbooks génèrent un contexte riche :

interface AIContext {
  currentFile: FileContext
  relevantRules: PlaybookRule[]
  similarExamples: CodeExample[]
  architecturalConstraints: Constraint[]
  teamStandards: TeamStandard[]
}

3. Application Intelligente

L'IA utilise ce contexte pour :

• Générer du code cohérent avec vos modèles existants
• Respecter vos conventions de nommage et structure
• Suivre vos standards de qualité et sécurité
• Maintenir la cohérence architecturale

Configuration des Playbooks

Structure du Répertoire

.hatcher/
├── playbooks/
│   ├── component-standards.yml
│   ├── api-patterns.yml
│   ├── testing-rules.yml
│   └── deployment-config.yml
├── patterns/
│   ├── detected/           # Modèles auto-détectés
│   └── custom/            # Modèles personnalisés
└── config/
    └── playbook-config.yml # Configuration globale

Exemple de Configuration

# .hatcher/config/playbook-config.yml
playbook_discovery:
  auto_scan: true
  scan_interval: '24h'
  include_patterns:
    - 'src/**/*.{vue,ts,js}'
    - 'docs/**/*.md'
  exclude_patterns:
    - 'node_modules/**'
    - 'dist/**'

ai_integration:
  context_depth: 'full'
  example_count: 3
  confidence_threshold: 0.8

team_sync:
  enabled: true
  repository: 'github'
  auto_commit: false

Règles Personnalisées

// .hatcher/playbooks/custom-rules.ts
export const customRules: PlaybookRule[] = [
  {
    name: "API Response Structure",
    scope: "api",
    pattern: {
      success: { data: "T", message?: "string" },
      error: { error: "string", code: "number" }
    },
    examples: [
      "return { data: users, message: 'Success' }",
      "return { error: 'Not found', code: 404 }"
    ]
  },

  {
    name: "Vue Component Props",
    scope: "components",
    pattern: {
      interface_suffix: "Props",
      required_props_first: true,
      default_values: "defineProps"
    },
    template: `
interface {{ComponentName}}Props {
  // Props requis en premier
  {{#requiredProps}}
  {{name}}: {{type}}
  {{/requiredProps}}

  // Props optionnels
  {{#optionalProps}}
  {{name}}?: {{type}}
  {{/optionalProps}}
}
    `
  }
]

Playbooks Avancés

Règles Conditionnelles

conditional_rules:
  - condition: "file.path.includes('components/forms')"
    rules:
      - validation_required: true
      - accessibility_attrs: ['aria-label', 'aria-describedby']
      - error_handling: 'user_friendly'

  - condition: "project.framework === 'nuxt'"
    rules:
      - ssr_compatible: true
      - meta_tags_required: true
      - performance_optimized: true

Apprentissage Adaptatif

// Le système apprend de vos corrections
class AdaptiveLearning {
  async recordFeedback(interaction: AIInteraction, feedback: UserFeedback) {
    if (feedback.type === 'correction') {
      await this.updatePlaybook({
        pattern: interaction.generatedPattern,
        correction: feedback.correctedVersion,
        confidence: this.calculateConfidence(feedback),
      })
    }
  }

  async suggestPlaybookUpdates(): Promise<PlaybookSuggestion[]> {
    const patterns = await this.analyzeRecentCorrections()
    return patterns.map((pattern) => ({
      type: 'pattern_update',
      suggestion: pattern.correctedPattern,
      confidence: pattern.confidence,
      examples: pattern.examples,
    }))
  }
}

Validation et Tests

# .hatcher/playbooks/testing-standards.yml
testing_rules:
  unit_tests:
    framework: 'vitest'
    coverage_threshold: 80
    naming_pattern: '*.spec.ts'

  integration_tests:
    framework: 'cypress'
    page_object_pattern: true

  component_tests:
    framework: '@vue/test-utils'
    render_testing: true
    accessibility_tests: true

validation:
  pre_commit:
    - lint_check
    - type_check
    - test_run

  pre_push:
    - full_test_suite
    - build_check
    - playbook_compliance

Meilleures Pratiques

1. Structure Progressive

• Commencez simple avec des règles de base
• Ajoutez de la complexité progressivement
• Documentez les décisions importantes

2. Collaboration d'Équipe

• Versionner les Playbooks avec Git
• Réviser les changements en équipe
• Maintenir la cohérence entre projets

3. Maintenance Continue

• Réviser périodiquement les règles
• Nettoyer les modèles obsolètes
• Mettre à jour avec l'évolution du projet

4. Optimisation des Performances

• Garder les règles ciblées et spécifiques
• Éviter la sur-spécification
• Tester l'impact sur la génération de code

---

Les Playbooks transforment l'IA d'un assistant générique en un membre d'équipe qui comprend vraiment votre projet, vos standards et votre vision architecturale.