Zum Hauptinhalt springen

Wo lebt das V-Modell bei Softwareentwicklung?

Wenn dein Produkt Software enthält, ist das V-Modell die Referenz dafür, wie Anforderungen bis zur Implementierung hinunterfließen und über Verifikation und Validierung wieder hinauf. Die Frage, die sich die meisten Teams stellen, lautet: Welche Teile dieses Modells gehören nach CertHub, und welche bleiben in der Engineering-Umgebung?

Die kurze Antwort: Die V-Modell-Records leben in CertHub. Implementierung und Test-Ausführung leben außerhalb. Das ist keine CertHub-Konvention. So trennen Design Controls im Medizinproduktbereich bereits eine Traceability-Matrix kontrollierter Artefakte vom letzten Schritt in den Quellcode.

Zwei Aufgaben, nicht ein Annotationsschema​

Einsteiger fragen oft: Wenn ich Systemanforderungen synchronisieren muss, warum steht dann nicht SYSREQ an jeder Funktion? Weil das zwei verschiedene Aufgaben sind.

Aufgabe 1 — QMS / technische Dokumentation. ISO 13485 verlangt, dass du Methoden dokumentierst, um die Rückverfolgbarkeit der Design- und Entwicklungs-Outputs zu den Design- und Entwicklungs-Inputs sicherzustellen (ISO 13485:2016 Abschnitt 7.3.2(e); derselbe Text steht in den USA jetzt in der QMSR über 21 CFR 820). Diese Methode ist eine bidirektionale Matrix von Records: Benutzeranforderungen, Design-Inputs, Design-Outputs, Verifikation, Validierung. Auditoren gehen diese Matrix durch. Sie greppen nicht dein Repository nach Anforderungs-IDs.

Aufgabe 2 — dieser Git-Stand. Die FDA-General Principles of Software Validation (GPSV, 2002) §5.2.4 verlangen eine Source-Code-Traceability-Analyse: Module und Funktionen lassen sich auf ein Element der Software-Design-Spezifikation zurückführen, und Tests auf dieselbe Spezifikation. Die Design-Spezifikation ist ein Design Output, keine Systemanforderung.

Zusammen:

CertHub (Aufgabe 1)                     Engineering (Aufgabe 2)
UREQ → SYSREQ → DOUT ───────────────►  Quellcode mit DOUT markiert
              ↘ VERIF ──────────────►  Test mit VERIF markiert
UREQ → VALID                           (manuell / Zweckbestimmung — keine Unit-Tests)

Du synchronisierst die linke Seite, damit die Matrix in deinen Tools existiert. Du markierst nur die rechte Seite, weil GPSV genau diesen Schritt für den Quellcode benennt. SYSREQ an Funktionen zu setzen würde die Design-Output-Schicht überspringen, gegen die Verifikation definiert ist (ISO 13485 7.3.6: Verifikation soll bestätigen, dass der Design Output die Design-Input-Anforderungen erfüllt; 21 CFR 820.30(f)).

IEC 62304 sagt dasselbe in der Planungssprache: Der Software-Entwicklungsplan soll TRACEABILITY zwischen SYSTEM-Anforderungen, Software-Anforderungen, SOFTWARE-SYSTEM-Test und in Software umgesetzten RISK-CONTROL-Maßnahmen behandeln (IEC 62304:2006+A1:2015 5.1.1(c)). Diese Traces leben zwischen kontrollierten Records. Quellcode-Kommentare sind eine Engineering-Methode für den letzten Schritt, kein Ersatz für die Matrix.

Die empfohlene Aufteilung​

Records — in CertHub pflegen​

Halte Folgendes als kontrollierte, prüfbare Records, einschließlich der Traces dazwischen:

  • Benutzeranforderungen (User Needs)
  • System- / Software-Anforderungen (Design Inputs)
  • Komponenten- und Unit-Anforderungen, falls du diese Schichten nutzt
  • Design Outputs (die Software-Design-Spezifikation und zugehörige Spezifikationen)
  • Verifikation (die kontrollierte Definition der Aktivität — und, wenn du sie ablegst, das Ergebnis)
  • Validierung (die kontrollierte Definition der Aktivität zur Zweckbestimmung)
  • die Tracer-Kanten, die die Matrix bidirektional machen

Das ist die Sicht auf die technische Dokumentation, die QM und RA brauchen, um zu prüfen, zu verteidigen und freizugeben. Genau dafür ist CertHub gebaut.

Design Output gehört hierher als Record. ISO 13485 7.3.4 verlangt, dass Outputs in einer Form dokumentiert sind, die sich gegen Inputs verifizieren lässt, Annahmegrenzen enthalten oder referenzieren und vor der Freigabe genehmigt werden. Die Quelldatei, die einen Output umsetzt, ersetzt diesen Record nicht.

Ausführung — deine Engineering-Umgebung​

Alles, was ein Build, ein Lauf oder ein generierter Report ist, bleibt dort, wo das Engineering-Team arbeitet:

  • Code und Implementierung
  • Unit- und Integrationstest-Ausführung
  • Dashboards und generierte Evidenzpakete pro Commit
  • Build-Artefakte und CI-Pipelines

Wie du den letzten Schritt (Aufgabe 2) umsetzt, ist deine Engineering-Entscheidung: Kommentare im CodeLinks-Stil, Doorstop, Doxygen, ein kleines Skript gegen die API. Das Muster schreibt keine bestimmte Toolchain vor. Siehe Working example.

CertHub muss nicht zu deiner IDE oder deinem CI-System werden.

Warum du Schichten synchronisierst, die du nie im Code markierst​

Exportiere das gesamte V-Modell, das du pflegst, nicht nur die IDs, die in Kommentaren stehen.

  • Vollständigkeit ist der Sinn von 7.3.2(e). Ein Input ohne Output ist eine fallen gelassene Anforderung. Ein Output ohne Input ist Scope Creep. Wenn der Engineering-Export unverbundene Zeilen weglässt, versteckst du den Befund, den die Matrix zeigen soll.
  • Fremdprodukt- oder Alttext ist ein Problem des Systems of Record. Bereinige ihn in CertHub. Streiche kein Knowledge Topic aus dem Sync, nur weil einige Zeilen keinen Code haben.
  • Validierung ist eine andere Frage als Verifikation. 21 CFR 820.30(g) und ISO 13485 7.3.7 fragen, ob das Produkt Benutzeranforderungen und Zweckbestimmung erfüllt, typischerweise unter realer oder simulierter Nutzung. Das ist nicht „hat der Unit-Test bestanden?“. Synchronisiere Validierungsprotokolle; tu nicht so, als würde pytest sie schließen.
  • Es darf Zeilen ohne Software geben. Verfahrens-Design-Outputs, Kennzeichnungsspezifikationen oder Hardware-Outputs bleiben im Katalog. Sie haben einfach keinen Source-Marker. Das ist korrekt, kein unvollständiges Tagging.

AAMI TIR45:2023 (von der FDA anerkannt, Recognition Number 13-143) ist die übliche Referenz, das in einem Agile-Team zu tun: Traces sind Lifecycle-Outputs, die laufend gepflegt werden, kein Kommentar-Schema erst zum Release.

Was diese Aufteilung nicht behauptet: IEC 62304 5.1.1(c) nennt auch Risk-Control-Maßnahmen. Die bleiben in der Risikodatei (ISO 14971) in CertHub, sofern du sie nicht explizit exportierst. Quellcode-Kommentare sind eine Methode für den letzten GPSV-Schritt; die Norm verlangt die Traces, keine bestimmte Marker-Syntax.

Zwei Richtungen, nicht eine​

Diese Aufteilung erzeugt zwei Datenbewegungen, und die meisten Teams brauchen beide.

1. Export: V-Modell-Records gehen hinaus​

Deine Engineering-Tools brauchen die kontrollierten Records und die Traces. Exportiere sie über die API aus CertHub, damit Git, Jira, Sphinx, Azure DevOps oder ein interner Service sie nutzen können.

Das ist eine Leseoperation. CertHub bleibt das System of Record. Deine Tools bekommen eine synchronisierte Kopie der Matrix — einschließlich Zeilen, die du nie im Quellcode markieren wirst.

2. Zurückschreiben: ausgewählte Nachweise kommen zurück​

Wenn dein Engineering-Prozess ein Ergebnis produziert, das für die technische Dokumentation relevant ist, schreibe einen kurzen Nachweis-Record zurück nach CertHub.

Das ist typischerweise ein Record auf Release-Ebene, keine Kopie jedes Testlaufs. Ein praktisches Minimum ist:

  • eine Versionsnummer
  • ein Commit- oder Build-Bezeichner
  • ein Zeitstempel
  • eine URL, die auf den vollständigen Nachweis verweist (zum Beispiel ein CI-Lauf oder ein Report in deinem Artefakt-Store)
  • eine kurze Zusammenfassung des Gate-Ergebnisses

Der komplette Build-Baum, die vollständige JUnit-Ausgabe, die generierten HTML-Dashboards — die bleiben in deinem CI- oder Artefakt-Store. CertHub erhält den kontrollierten Verweis und die Zusammenfassung, die ihr tatsächlich prüft.

Du bestimmst die Tiefe​

Wie viel du zurückschreibst, ist eine Entscheidung deines Teams. Manche Organisationen schreiben einen einzigen Release-Record pro Version. Andere schreiben granularere Records pro Verifikationsaktivität.

Die Empfehlung: Beginne mit dem Minimum, das QM und RA das gibt, was sie brauchen. Du kannst später immer mehr Tiefe hinzufügen. Du solltest nicht versuchen, die gesamte Engineering-Umgebung in CertHub zu replizieren.

Auf der Export-Seite ist die übliche Tiefe das V-Modell, das ihr tatsächlich pflegt (oft sieben Content-Topics plus Traces). Du musst nicht jede Schicht in Software umsetzen. Du musst sie sehen, wenn sie im SoR steht.

Ein Beispiel, nicht die Methode​

Cadence ist CertHubs öffentliches Engineering-Beispiel für dieses Muster. Es nutzt die CertHub-API; useblocks (Sphinx-Needs / CodeLinks / Test-Reports) ist der optionale Last-Hop-Toolchain in diesem Repo, keine CertHub-Vorgabe.

Cadence synchronisiert sieben Requirements-Engineering-Knowledge-Topics aus CertHub in eine Git-Codebasis. Quellcode-Kommentare nutzen Design-Output-IDs; Tests nutzen Verifikations-IDs. Systemanforderungen schließen das Engineering-Gate über Tracer-Links, nicht über zusätzliche Kommentare. Es erstellt bei jedem Commit ein vollständiges Evidenzpaket und schreibt bei vollständigen Versions-Tags einen Release-Nachweis-Record zurück nach CertHub.

Nutze es als Referenzimplementierung. Ersetze den unteren Teil des V durch deinen eigenen Stack — das Muster bleibt gleich. Siehe Working example für das annotierte V und die zwei Downstream-Anwendungen (Traceability bis zum Code sowie Tests plus gezielter Write-back), oder schau dir den Walkthrough an.

Beispiel lokal ausprobieren
git clone https://github.com/CertHubCode/certhub-useblocks-example.git
cd certhub-useblocks-example
make install
make show              # Tests + Gate + Dashboard öffnen — erwartet VERIFIED, 4/4 SYSREQ PASS (kein API-Key)

API-Key erst für Sync oder Release-Record-Write-back (cp .env.example .env, dann make sync). Die README im Repository beschreibt den geführten Pfad, die RED/GREEN-Demo (make break / make fix) und das CI-Setup. docs/traceability-map.md in diesem Repo ist das ausgearbeitete Beispiel, was im Code markiert wird und warum.

Was du nicht tun solltest​

  • Versuche nicht, deinen gesamten Engineering-Workflow in CertHub abzubilden.
  • Belasse Anforderungen, Design Outputs und Verifikation nicht nur in deinem Entwicklungstool, ohne eine kontrollierte Kopie in der technischen Dokumentation.
  • Setze keine Systemanforderungs-IDs auf den Quellcode als Ersatz für den Design-Output-Record. Verifikation bestätigt, dass der Output den Input erfüllt.
  • Streiche unverbundene Zeilen nicht aus dem Export, damit das Paket aufgeräumter wirkt. Vollständigkeit ist der Befund.
  • Kippe nicht den gesamten CI-Artefakt-Baum nach CertHub. Speichere ihn dort, wo er hingehört, und schreibe einen Verweis zurück.
  • Baue keinen Custom-Sync, ohne vorher zu verstehen, welche IDs CertHub für API-Aufrufe und welche für Dashboard-URLs verwendet. Sie sind nicht austauschbar.

Empfehlung​

Für Software als Medizinprodukt: Pflege die V-Modell-Records und ihre Traces in CertHub. Lass Engineering den letzten Schritt in Quellcode und Testausführung verantworten. Verbinde beides über die API: Exportiere die Matrix, die deine Tools brauchen, schreibe zurück, was die technische Dokumentation braucht.

Faustregel: Synchronisiere das V-Modell; markiere im Code nur, was Software tatsächlich umsetzt oder verifiziert. Unverbundene Zeilen sind in Ordnung. Fremdprodukt-Zeilen sind ein Problem des Systems of Record, kein Grund, weniger zu synchronisieren.

Wenn du bereit bist​