karlsCORE KI-Gemeinschaft KI-Wissen Systemisch Denken Erstgespräch Anmelden

Prädikat has_documentation

Code, den niemand versteht, ist wie eine Landkarte ohne Beschriftung - technisch korrekt, aber praktisch nutzlos. Das Prädikat has_documentation stellt sicher, dass Änderungen nicht nur funktionieren, sondern auch verstanden werden können.

Dokumentation ist keine Kür

Viele Teams behandeln Dokumentation als optionales Extra. Aber was passiert, wenn der ursprüngliche Entwickler das Projekt verlässt? Wenn eine KI den Code weiterentwickeln soll? Ohne Dokumentation wird jede Änderung zum Ratespiel.

Vollständiges Beispiel

Definition des Dokumentations-Prädikats:

# Prädikat: has_documentation
# Verwendet in: Gate G4 (Implementation), Gate G5 (Review)

predicate:
  id: "has_documentation"
  name: "Dokumentation vorhanden"
  description: "Prüft, ob alle Änderungen ausreichend dokumentiert sind"
  category: "quality"
  severity: "high"

  # Was wird geprüft?
  checks:
    - id: "code_comments"
      name: "Code-Kommentare"
      rules:
        - "public_methods_have_docblock"
        - "complex_logic_explained"
        - "no_todo_without_ticket"

    - id: "api_docs"
      name: "API-Dokumentation"
      required_for:
        - file_pattern: "**/api/**"
        - file_pattern: "**/public/**"
      rules:
        - "openapi_spec_updated"
        - "all_endpoints_documented"
        - "examples_provided"

    - id: "readme_updated"
      name: "README aktualisiert"
      required_for:
        - change_type: "new_feature"
        - change_type: "breaking_change"
      rules:
        - "installation_steps_current"
        - "usage_examples_present"

    - id: "changelog_entry"
      name: "CHANGELOG-Eintrag"
      required_for:
        - change_class: "normal"
        - change_class: "critical"
      rules:
        - "version_number_valid"
        - "change_description_meaningful"

  # Erfolgskriterien
  success_criteria:
    all_required_docs_present: true
    no_broken_links: true
    examples_executable: true

Auswertung in der Praxis

# Dokumentations-Check Ergebnis
evaluation:
  predicate_id: "has_documentation"
  change_id: "CHG-2024-0045"
  change_type: "new_feature"
  evaluated_at: "2024-01-15T14:00:00Z"

  check_results:
    - check_id: "code_comments"
      passed: true
      details:
        files_checked: 12
        methods_checked: 47
        coverage:
          public_methods: "100%"
          complex_sections: "95%"
        findings:
          - file: "src/Services/PaymentService.php"
            line: 89
            type: "info"
            message: "Consider adding example in docblock"

    - check_id: "api_docs"
      passed: true
      details:
        endpoints_documented: 5
        openapi_valid: true
        examples_present: true

    - check_id: "readme_updated"
      passed: true
      details:
        sections_updated:
          - "Installation"
          - "Configuration"
          - "Usage"
        last_update: "2024-01-15T13:45:00Z"

    - check_id: "changelog_entry"
      passed: true
      details:
        version: "2.3.0"
        entry: "Added payment retry functionality"
        category: "Added"

  result: true
  evidence:
    docblock_coverage: "reports/phpdoc-coverage.html"
    openapi_spec: "docs/api/openapi.yaml"
    changelog_diff: "git diff CHANGELOG.md"

Warum ist das wichtig?

Dokumentation ist Wissenstransfer in die Zukunft. Sie ermöglicht es Menschen und KI, Code zu verstehen, zu warten und weiterzuentwickeln. Im Mensch + KI-Code Prozess ist gute Dokumentation keine Option, sondern eine formale Anforderung.

Im Mensch + KI-Code Prozess: Bei Change Class "Trivial" reichen Code-Kommentare. Bei "Normal" und "Critical" sind zusätzlich API-Docs und CHANGELOG-Einträge erforderlich. Das Prädikat wird am Gate G4 (Implementation) geprüft.