Migrate all repos into monorepo context folders
Bahn: aisupport, Analyse-O2C-C2S, awesome-bahn-mcp-servers, beam-mcp,
Confluence_Bot, db-planet-mcp-server, O2C-Harness, project-audit,
Projekt-KIQ-HP, teamlandkarte-mcp
Dhive: Jury-Voting
Privat: CV, NoteGraph (NOTE: NoteGraph needs complete redo after consolidation)
Shared: AI-Orchestrator, OrgMyLife, power_skills_and_more
Shared/references: symphony (read-only)
Bahn repos remain available as independent remotes - this monorepo
pulls them in via subtree, the originals are untouched.
This commit is contained in:
@@ -0,0 +1,306 @@
|
||||
DB Inner Source Lizenz Version 1.0
|
||||
|
||||
_Fachautoren: Cornelius Schumacher, Schlomo Schapiro (DB Systel GmbH)_
|
||||
|
||||
Diese Inner-Source-Lizenz für die Deutsche Bahn („DBISL“) gilt für Werke
|
||||
(im Sinne der nachfolgenden Begriffsbestimmung), die unter
|
||||
DBISL-Bedingungen zur Verfügung gestellt werden. Das Werk darf nur in
|
||||
der durch diese Lizenz gestatteten Form genutzt werden (insoweit eine
|
||||
solche Nutzung dem Urheber vorbehalten ist).
|
||||
|
||||
Das Werk wird unter den Bedingungen dieser Lizenz zur Verfügung
|
||||
gestellt, wenn der Lizenzgeber (im Sinne der nachfolgenden
|
||||
Begriffsbestimmung) den folgenden Hinweis unmittelbar hinter dem
|
||||
Urheberrechtshinweis dieses Werks anbringt:
|
||||
|
||||
„Lizenziert unter der DBISL“ oder alternativ „Licensed under the DBISL“
|
||||
|
||||
oder in einer anderen Form zum Ausdruck bringt, dass er es unter der
|
||||
DBISL lizenzieren möchte.
|
||||
|
||||
== 1. Begriffsbestimmungen
|
||||
|
||||
Für diese Lizenz gelten folgende Begriffsbestimmungen:
|
||||
|
||||
* „Lizenz“: diese Lizenz.
|
||||
* „Originalwerk“: das Werk oder die Software, die vom Lizenzgeber unter
|
||||
dieser Lizenz verbreitet oder zugänglich gemacht wird, und zwar als
|
||||
Quellcode und gegebenenfalls auch als ausführbarer Code.
|
||||
* „Bearbeitungen“: die Werke oder Software, die der Lizenznehmer auf der
|
||||
Grundlage des Originalwerks oder seiner Bearbeitungen schaffen kann. In
|
||||
dieser Lizenz wird nicht festgelegt, wie umfangreich die Änderung oder
|
||||
wie stark die Abhängigkeit vom Originalwerk für eine Einstufung als
|
||||
Bearbeitung sein muss; dies bestimmt sich nach dem anwendbaren
|
||||
Urheberrecht
|
||||
* „Werk“: das Originalwerk oder seine Bearbeitungen.
|
||||
* „Quellcode“: diejenige Form des Werkes, die zur Auffassung durch den
|
||||
Menschen bestimmt ist und die am besten geeignet ist, um vom Menschen
|
||||
verstanden und verändert zu werden.
|
||||
* „Ausführbarer Code“: die — üblicherweise — kompilierte Form des Werks,
|
||||
die von einem Computer als Programm ausgeführt werden soll.
|
||||
* „Lizenzgeber“: die juristische Person innerhalb des DB Konzerns, die
|
||||
das Werk unter der Lizenz verbreitet oder zugänglich macht.
|
||||
* „Urheberrechtsinhaber/Autor“: jeder, der bestimmte von ihm selbst
|
||||
entwickelte oder von Dritten vorgegebene Aufgabenstellungen in ein
|
||||
Originalwerk umsetzt oder am Originalwerk eine Bearbeitung vornimmt.
|
||||
* „Bearbeiter“: jeder, der das Werk unter der Lizenz verändert oder auf
|
||||
andere Weise zur Schaffung einer Bearbeitung beiträgt. Jeder Autor ist
|
||||
auch Bearbeiter.
|
||||
* „Lizenznehmer“ („Sie“, „Ihnen“): jede juristische Person innerhalb des
|
||||
DB Konzerns, die das Werk unter den Lizenzbedingungen nutzt.
|
||||
* „Verbreitung“ oder „Zugänglichmachung“: alle Formen von Verkauf,
|
||||
Überlassung, Verleih, Vermietung, Verbreitung, Weitergabe, Übermittlung
|
||||
oder anderweitiger Online- oder Offline-Bereitstellung von
|
||||
Vervielfältigungen des Werks oder Zugänglichmachung seiner wesentlichen
|
||||
Funktionen für dritte natürliche oder juristische Personen.
|
||||
* „Beitrag“: jedes urheberrechtliche Werk, einschließlich des
|
||||
Originalwerks sowie jeglicher Änderungen, die der Bearbeiter vornimmt,
|
||||
und die dem Lizenzgeber bewusst zur Aufnahme in das Werk eingereicht
|
||||
werden.
|
||||
* „DB“ oder „DB Konzern“: die Deutsche Bahn AG und alle mit ihr nach §
|
||||
15 AktG verbundenen Unternehmen.
|
||||
|
||||
== 2. Umfang der Lizenzrechte
|
||||
|
||||
Der Lizenzgeber erteilt Ihnen hiermit eine weltweite, unentgeltliche,
|
||||
nicht ausschließliche, unterlizenzierbare Lizenz, die Sie für
|
||||
Geschäftszwecke des DB Konzerns berechtigt:
|
||||
|
||||
* das Werk uneingeschränkt zu nutzen,
|
||||
* das Werk zu vervielfältigen,
|
||||
* das Werk zu verändern und Bearbeitungen auf der Grundlage des Werks zu
|
||||
schaffen,
|
||||
* das Werk oder Vervielfältigungen davon innerhalb der DB zu verbreiten,
|
||||
|
||||
Für die Wahrnehmung dieser Rechte können beliebige, derzeit bekannte
|
||||
oder künftige Medien, Träger und Formate verwendet werden, soweit das
|
||||
geltende Recht dem nicht entgegensteht.
|
||||
|
||||
Der Lizenzgeber erteilt dem Lizenznehmer ein nicht ausschließliches,
|
||||
unentgeltliches Nutzungsrecht an seinen Patenten, sofern dies zur
|
||||
Ausübung der durch die Lizenz erteilten Nutzungsrechte am Werk notwendig
|
||||
ist.
|
||||
|
||||
== 3. Zugänglichmachung des Quellcodes
|
||||
|
||||
Der Lizenzgeber kann das Werk entweder als Quellcode oder als
|
||||
ausführbaren Code zur Verfügung stellen. Stellt er es als ausführbaren
|
||||
Code zur Verfügung, so stellt er darüber hinaus eine maschinenlesbare
|
||||
Kopie des Quellcodes für jedes von ihm verbreitete
|
||||
Vervielfältigungsstück des Werks zur Verfügung, oder er verweist in
|
||||
einem Vermerk im Anschluss an den dem Werk beigefügten
|
||||
Urheberrechtshinweis auf einen Speicherort, an dem problemlos und
|
||||
unentgeltlich auf den Quellcode zugegriffen werden kann, solange der
|
||||
Lizenzgeber das Werk verbreitet oder zugänglich macht.
|
||||
|
||||
== 4. Einschränkungen des Urheberrechts
|
||||
|
||||
Es ist nicht Zweck dieser Lizenz, Ausnahmen oder Schranken der
|
||||
ausschließlichen Rechte des Urhebers am Werk, die dem Lizenznehmer
|
||||
zugutekommen, einzuschränken. Auch die Erschöpfung dieser Rechte bleibt
|
||||
von dieser Lizenz unberührt.
|
||||
|
||||
== 5. Pflichten des Lizenznehmers
|
||||
|
||||
Die Einräumung der oben genannten Rechte ist an mehrere Beschränkungen
|
||||
und Pflichten für den Lizenznehmer gebunden:
|
||||
|
||||
* Inner Source: Der Lizenznehmer darf das Werk ausschließlich für
|
||||
Geschäftszwecke des DB Konzerns nutzen.
|
||||
* Urheberrechtshinweis, Lizenztext, Nennung des Bearbeiters: Der
|
||||
Lizenznehmer muss alle Urheberrechts-, Patent- oder Markenrechtshinweise
|
||||
und alle Hinweise auf die Lizenz und den Haftungsausschluss unverändert
|
||||
lassen. Jedem von ihm verbreiteten oder zugänglich gemachten
|
||||
Vervielfältigungsstück des Werks muss der Lizenznehmer diese Hinweise
|
||||
sowie diese Lizenz beifügen. Der Lizenznehmer muss auf jedem
|
||||
abgeleiteten Werk deutlich darauf hinweisen, dass das Werk geändert
|
||||
wurde, und das Datum der Bearbeitung angeben.
|
||||
* „Copyleft“-Klausel: Der Lizenznehmer darf Vervielfältigungen des
|
||||
Originalwerks oder Bearbeitungen nur unter den Bedingungen dieser DBISL
|
||||
oder einer neueren Version dieser Lizenz innerhalb der DB verbreiten
|
||||
oder zugänglich machen. Der Lizenznehmer (der zum Lizenzgeber wird) darf
|
||||
für das Werk oder die Bearbeitung keine zusätzlichen Bedingungen
|
||||
anbieten oder vorschreiben, die die Bedingungen dieser Lizenz verändern
|
||||
oder einschränken.
|
||||
* Bereitstellung des Quellcodes: Wenn der Lizenznehmer
|
||||
Vervielfältigungsstücke des Werks verbreitet oder zugänglich macht, muss
|
||||
er eine maschinenlesbare Fassung des Quellcodes mitliefern oder einen
|
||||
Speicherort angeben, über den problemlos und unentgeltlich so lange auf
|
||||
diesen Quellcode zugegriffen werden kann, wie der Lizenznehmer das Werk
|
||||
verbreitet oder zugänglich macht.
|
||||
* Rechtsschutz: Diese Lizenz erlaubt nicht die Benutzung von
|
||||
Kennzeichen, Marken oder geschützten Namensrechten des Lizenzgebers,
|
||||
soweit dies nicht für die angemessene und übliche Beschreibung der
|
||||
Herkunft des Werks und der inhaltlichen Wiedergabe des
|
||||
Urheberrechtshinweises erforderlich ist.
|
||||
|
||||
== 6. Urheber und Bearbeiter
|
||||
|
||||
Der ursprüngliche Lizenzgeber gewährleistet, dass er das Urheberrecht am
|
||||
Originalwerk innehat oder dieses an ihn lizenziert wurde und dass er
|
||||
befugt ist, diese Lizenz zu erteilen.
|
||||
|
||||
Jeder Bearbeiter gewährleistet, dass er das Urheberrecht an den von ihm
|
||||
vorgenommenen Änderungen des Werks besitzt und befugt ist, einen Beitrag
|
||||
unter dieser Lizenz zu erstellen und beizutragen.
|
||||
|
||||
Für jeden Fall, in dem der Lizenznehmer die Lizenz annimmt, erteilt der
|
||||
ursprüngliche Lizenzgeber und alle folgenden Bearbeiter eine Befugnis
|
||||
zur Nutzung der Beiträge zum Werk unter den Bedingungen dieser Lizenz.
|
||||
|
||||
== 7. Gewährleistungsausschluss
|
||||
|
||||
Falls die konzerninternen Leistungsbedingungen keine Anwendung finden,
|
||||
gelten die folgenden Regelungen.
|
||||
|
||||
Die Arbeit an diesem Werk wird laufend fortgeführt; es wird durch
|
||||
unzählige Bearbeiter ständig verbessert. Das Werk ist nicht vollendet
|
||||
und kann daher Fehler („Bugs“) enthalten, die dieser Art der Entwicklung
|
||||
inhärent sind.
|
||||
|
||||
Aus den genannten Gründen wird das Werk unter dieser Lizenz „so, wie es
|
||||
ist“ ohne jegliche Gewährleistung zur Verfügung gestellt. Dies gilt
|
||||
unter anderem — aber nicht ausschließlich — für Marktreife,
|
||||
Verwendbarkeit für einen bestimmten Zweck, Mängelfreiheit, Richtigkeit
|
||||
sowie Nichtverletzung von anderen Immaterialgüterrechten als dem
|
||||
Urheberrecht (vgl. dazu Artikel 6 dieser Lizenz).
|
||||
|
||||
Dieser Gewährleistungsausschluss ist wesentlicher Bestandteil der Lizenz
|
||||
und Bedingung für die Einräumung von Rechten an dem Werk.
|
||||
|
||||
== 8. Haftungsausschluss/Haftungsbeschränkung
|
||||
|
||||
Falls die konzerninternen Leistungsbedingungen keine Anwendung finden,
|
||||
gelten die folgenden Regelungen.
|
||||
|
||||
Außer in Fällen von Vorsatz oder der Verursachung von Personenschäden
|
||||
haftet der Lizenzgeber nicht für direkte oder indirekte, materielle oder
|
||||
immaterielle Schäden irgendwelcher Art, die aus der Lizenz oder der
|
||||
Benutzung des Werks folgen; dies gilt unter anderem, aber nicht
|
||||
ausschließlich, für Firmenwertverluste, Produktionsausfall,
|
||||
Computerausfall oder Computerfehler, Datenverlust oder wirtschaftliche
|
||||
Schäden, und zwar auch dann, wenn der Lizenzgeber auf die Möglichkeit
|
||||
solcher Schäden hingewiesen wurde. Unabhängig davon haftet der
|
||||
Lizenzgeber im Rahmen der gesetzlichen Produkthaftung, soweit die
|
||||
entsprechenden Regelungen auf das Werk anwendbar sind.
|
||||
|
||||
== 9. Zusatzvereinbarungen
|
||||
|
||||
Wenn der Lizenznehmer das Werk verbreitet, kann er Zusatzvereinbarungen
|
||||
schließen, in denen Verpflichtungen oder Dienstleistungen festgelegt
|
||||
werden, die mit dieser Lizenz vereinbar sind.
|
||||
|
||||
Der Lizenznehmer darf Verpflichtungen nur in seinem eigenen Namen
|
||||
eingehen, nicht jedoch im Namen des ursprünglichen Lizenzgebers oder
|
||||
eines anderen Bearbeiters, und nur, wenn er sich gegenüber allen
|
||||
Bearbeitern verpflichtet, sie zu entschädigen, zu verteidigen und von
|
||||
der Haftung freizustellen, falls aufgrund der von ihm eingegangenen
|
||||
Gewährleistungsverpflichtung oder Haftungsübernahme Forderungen gegen
|
||||
sie geltend gemacht werden oder eine Haftungsverpflichtung entsteht.
|
||||
|
||||
== 10. Annahme der Lizenz
|
||||
|
||||
Der Lizenznehmer stimmt den Bestimmungen dieser Lizenz zu, indem er das
|
||||
Symbol „Lizenz annehmen“ unter dem Fenster mit dem Lizenztext anklickt
|
||||
oder indem er seine Zustimmung auf vergleichbare Weise gibt. Das
|
||||
Anklicken des Symbols gilt als Anzeichen der eindeutigen und
|
||||
unwiderruflichen Annahme der Lizenz und der darin enthaltenen Klauseln
|
||||
und Bedingungen.
|
||||
|
||||
In gleicher Weise gilt als Zeichen der eindeutigen und unwiderruflichen
|
||||
Zustimmung die Ausübung eines Rechtes, das in Artikel 2 dieser Lizenz
|
||||
angeführt ist, wie das Erstellen einer Bearbeitung oder die Verbreitung
|
||||
oder Zugänglichmachung des Werks oder dessen Vervielfältigungen.
|
||||
|
||||
== 11. Informationspflichten
|
||||
|
||||
Wenn der Lizenznehmer das Werk verbreitet oder zugänglich macht
|
||||
(beispielsweise, indem er es zum Herunterladen von einer Website
|
||||
anbietet), muss der Lizenznehmer über den Vertriebskanal oder das
|
||||
benutzte Verbreitungsmedium dem Adressatenkreis bzw. der Öffentlichkeit
|
||||
Mindest-Informationen bereitstellen, üblicherweise bezüglich der
|
||||
Lizenzgeber, der Lizenz und ihrer Zugänglichkeit, des Abschlusses des
|
||||
Lizenzvertrags sowie darüber, wie die Lizenz durch den Lizenznehmer
|
||||
gespeichert und vervielfältigt werden kann.
|
||||
|
||||
== 12. Beendigung der Lizenz
|
||||
|
||||
Die Lizenz und die damit eingeräumten Rechte erlöschen automatisch, wenn
|
||||
der Lizenznehmer gegen die Lizenzbedingungen verstößt.
|
||||
|
||||
Ein solches Erlöschen der Lizenz führt nicht zum Erlöschen der Lizenzen
|
||||
von Dritten, denen das Werk vom Lizenznehmer unter dieser Lizenz zur
|
||||
Verfügung gestellt worden ist, solange diese Personen die
|
||||
Lizenzbedingungen erfüllen.
|
||||
|
||||
== 13. Einreichung von Beiträgen
|
||||
|
||||
Sofern nichts ausdrücklich anderes angegeben, unterliegt jeder Beitrag,
|
||||
den der Lizenzgeber bewusst zur Aufnahme in das Werk eingereicht hat,
|
||||
den Bedingungen dieser Lizenz, ohne dass zusätzliche Bedingungen gelten.
|
||||
Ungeachtet des Vorstehenden ersetzt oder ändert keine der hierin
|
||||
enthaltenen Bestimmungen die Bedingungen einer separaten
|
||||
Lizenzvereinbarung, die der Auftraggeber möglicherweise mit dem
|
||||
Auftragnehmer für solche Beiträge abgeschlossen hat.
|
||||
|
||||
Für die Länder, in denen Urheberpersönlichkeitsrechte an einem Werk
|
||||
entstehen können, verzichtet der Urheberrechtsinhaber/Autor im
|
||||
gesetzlich zulässigen Umfang auf seine Urheberpersönlichkeitsrechte, um
|
||||
die Lizenzierung der oben aufgeführten Verwertungsrechte wirksam
|
||||
durchführen zu können.
|
||||
|
||||
== 14. Sonstiges
|
||||
|
||||
Unbeschadet des Artikels 9 stellt diese Lizenz die vollständige
|
||||
Vereinbarung der Parteien über das Werk dar.
|
||||
|
||||
Es gilt deutsches Recht. Sind einzelne Bestimmungen der Lizenz nach
|
||||
geltendem Recht nichtig oder unwirksam, so berührt dies nicht die
|
||||
Wirksamkeit oder Durchsetzbarkeit der Lizenz an sich. Solche
|
||||
Bestimmungen werden vielmehr dergestalt ausgelegt oder modifiziert, dass
|
||||
sie wirksam und durchsetzbar sind.
|
||||
|
||||
== 15. Gesellschaftsrechtliche Veränderungen
|
||||
|
||||
Bei gesellschaftsrechtlichen Veränderungen, z.B. dem Verkauf oder der
|
||||
Abspaltung einer DB Gesellschaft, gilt folgende Regelungen in Anlehnung
|
||||
an §12 Beendigungsunterstützung der konzerninternen
|
||||
Leistungsbedingungen:
|
||||
|
||||
Eine weitere Nutzung der lizenzierten Software durch ein nicht mehr dem
|
||||
DB Konzern angehöriges Unternehmen unterliegt der Zustimmung durch die
|
||||
Urheber bzw. das CIO Board.
|
||||
|
||||
== 16. Lizenzänderungen
|
||||
|
||||
Die Urheber eines Werks können gemeinsam eine Änderung der Lizenz
|
||||
entscheiden, z.B. um das Werk als Open Source Software zu
|
||||
veröffentlichen. Falls die Urheber nicht verfügbar sind oder sich nicht
|
||||
einigen können, so kann das CIO Board stellvertretend für alle Urheber
|
||||
innerhalb der DB die Änderung der Lizenz für ein Werk beschließen.
|
||||
|
||||
== 17. Streitbeilegung
|
||||
|
||||
Unbeschadet der Regelungen in den konzerninternen Leistungsbedingungen
|
||||
zwischen den Parteien gilt zwischen den Parteien Folgendes:
|
||||
|
||||
Bei Streitigkeiten im Zusammenhang mit der Auslegung und Anwendung
|
||||
dieser Lizenz, bei denen mehr als ein Konzernunternehmen beteiligt ist,
|
||||
dient das CIO Board des Konzerns als Entscheidungsgremium, welches von
|
||||
jeder Partei angerufen werden kann.
|
||||
|
||||
== 18. Lizenz der Lizenz
|
||||
|
||||
Dieser Lizenztext ist lizenziert unter einer
|
||||
„link:http://creativecommons.org/licenses/by/4.0/[Creative Commons
|
||||
Namensnennung 4.0 International Lizenz]“ (CC-BY 4.0).
|
||||
|
||||
Sie dürfen diesen Lizenztext für sich kopieren und anpassen, solange Sie
|
||||
dabei die Deutsche Bahn Marke und „DB“ nur innerhalb der DB benutzen.
|
||||
Falls Sie das Material für die Verwendung außerhalb der DB anpassen, so
|
||||
müssen Sie alle Nennungen der Deutschen Bahn und DB ersetzen bzw.
|
||||
entfernen. Geänderte Versionen des Lizenztextes müssen klar als
|
||||
geänderte Versionen kenntlich gemacht werden.
|
||||
|
||||
Teile des Textes dieser Lizenz basieren auf der EU Public License (EUPL)
|
||||
v1.2.
|
||||
@@ -0,0 +1,65 @@
|
||||
# Agent Harness
|
||||
|
||||
## KI-Tool-unabhängige Steering-Instructions
|
||||
|
||||
Dieses Repository definiert **wie** ein KI-Agent arbeiten soll – unabhängig davon **welches** Tool ihn antreibt.
|
||||
|
||||
### Warum?
|
||||
|
||||
| Eigenschaft | Vorteil |
|
||||
|-------------|---------|
|
||||
| **Kein Vendor-Lock** | Funktioniert mit OpenCode, Kiro CLI, Claude Code, Copilot, Cursor – jedes Tool das Markdown lesen kann |
|
||||
| **Menschenlesbar** | Jeder Entwickler kann die Instructions lesen, verstehen und korrigieren |
|
||||
| **Versioniert** | Git-History zeigt wer was wann geändert hat |
|
||||
| **Reviewbar** | Änderungen gehen über MR mit Code-Review |
|
||||
| **Teilbar** | Teams können den Harness forken und für ihren Kontext anpassen |
|
||||
| **Kein proprietäres Format** | Keine .cursorrules, keine Kiro-Skills, kein CLAUDE.md – nur Markdown |
|
||||
|
||||
### Prinzip
|
||||
|
||||
Der Agent ist austauschbar. Die Standards bleiben.
|
||||
|
||||
## Inhalt
|
||||
|
||||
- **workflow.md** – Git-Workflow, Branching, Repo-Erstellung
|
||||
- **tools.md** – Verfügbare CLI-Tools
|
||||
- **testing.md** – Unit/Integration/E2E Tests, Testcontainers, Playwright
|
||||
- **planning.md** – GitLab Issues, Responsible Vibe Workflow
|
||||
- **documentation.md** – Arc42 (12 Kapitel), ADRs, Mermaid C4
|
||||
- **code-review.md** – Self-Review mit GitLab Discussions
|
||||
- **merge-request.md** – MR-Standards, Conventional Commits
|
||||
- **quality-gates.md** – Linter, Trivy, gitleaks, Renovate
|
||||
- **requirements-review.md** – Anforderungen prüfen, Fragen stellen
|
||||
- **git-setup.md** – Branching, Jira-Referenz, Commit-Prefix
|
||||
- **self-review.md** – Pipeline-Überwachung, Fortschritt
|
||||
- **autonomous-mode.md** – Autonomer Modus, Entscheidungshilfen
|
||||
- **clean-code.md** – Architektur, Clean Code, Observability
|
||||
- **session-notes.md** – Arbeitsprotokoll
|
||||
- **project-setup.md** – Pflichtdateien, Repo-Struktur
|
||||
- **mcp.json** – MCP-Server-Config mit Env-Platzhaltern
|
||||
|
||||
## Anpassung für ein ART
|
||||
|
||||
Dieses Repo ist ein **generisches Template**. Jedes ART forkt es und ergänzt:
|
||||
|
||||
1. ART-spezifische Dateien (z.B. `pipeline.md`, `infrastructure.md`, `coding-standards.md`)
|
||||
2. Platzhalter durch eigene Werte ersetzen
|
||||
3. MCP-Server in `mcp.json` ergänzen (z.B. Rollout-Tool, ART-spezifische APIs)
|
||||
|
||||
### Platzhalter
|
||||
|
||||
| Platzhalter | Beschreibung | Beispiel |
|
||||
|-------------|-------------|----------|
|
||||
| `${ART_NAME}` | Name des ART (GitLab-Gruppe, Namespace-Prefix) | `apn`, `o2c`, `netz` |
|
||||
| `${JIRA_PREFIX}` | Jira-Projekt-Key für Branch-/Commit-Referenzen | `O2CAAPN`, `O2CO2C` |
|
||||
| `${CONTACT_EMAIL}` | Team-Kontakt-E-Mail für `scm-info.yaml` | `mein-art@deutschebahn.com` |
|
||||
|
||||
## Verwendung
|
||||
|
||||
Als Steering-Repo über x-Header an den Orchestrator übergeben:
|
||||
|
||||
```
|
||||
x-steering-repo: https://git.tech.rz.db.de/${ART_NAME}/playground/agent-harness.git
|
||||
```
|
||||
|
||||
Der Agent klont das Repo und lädt alle .md-Dateien als Instructions.
|
||||
@@ -0,0 +1,115 @@
|
||||
# Sub-Agenten
|
||||
|
||||
Kiro CLI unterstützt Sub-Agenten – spezialisierte Rollen die der Haupt-Agent für komplexe Aufgaben nutzen kann.
|
||||
|
||||
## Verfügbare Profile
|
||||
|
||||
| Agent | Datei | Rolle | Tools |
|
||||
|-------|-------|-------|-------|
|
||||
| researcher | `researcher.json` | Informationen sammeln, analysieren | Alle |
|
||||
| implementer | `implementer.json` | Code schreiben, testen, committen | Alle |
|
||||
| reviewer | `reviewer.json` | Code-Review, Security, Best Practices | read, grep, shell |
|
||||
|
||||
## Wie der Haupt-Agent Sub-Agenten nutzt
|
||||
|
||||
Der Haupt-Agent entscheidet selbst ob er Sub-Agenten braucht. Bei komplexen Aufgaben nutzt er das `subagent` Tool:
|
||||
|
||||
```
|
||||
subagent(
|
||||
task: "Feature implementieren und reviewen",
|
||||
stages: [
|
||||
{name: "research", role: "researcher", prompt: "Analysiere die bestehende Codebasis..."},
|
||||
{name: "implement", role: "implementer", prompt: "Implementiere basierend auf der Analyse...", depends_on: ["research"]},
|
||||
{name: "review", role: "reviewer", prompt: "Prüfe die Implementierung...", depends_on: ["implement"]}
|
||||
]
|
||||
)
|
||||
```
|
||||
|
||||
### Parallelisierung
|
||||
|
||||
Stages ohne `depends_on` laufen parallel:
|
||||
|
||||
```
|
||||
Stage 1 (parallel): Stage 2: Stage 3:
|
||||
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
|
||||
│ researcher: │───┐ │ implementer: │ │ reviewer: │
|
||||
│ API lesen │ ├───▶│ Code + Tests │──▶│ Qualität │
|
||||
│ researcher: │───┘ │ │ │ prüfen │
|
||||
│ DB Schema │ └──────────────┘ └──────────────┘
|
||||
└──────────────┘
|
||||
```
|
||||
|
||||
### Shared Filesystem
|
||||
|
||||
Alle Sub-Agenten teilen `/workspace/project`. Der Researcher schreibt Ergebnisse in Dateien die der Implementer liest.
|
||||
|
||||
## Eigene Profile erstellen
|
||||
|
||||
Ein Agent-Profil ist eine JSON-Datei:
|
||||
|
||||
```json
|
||||
{
|
||||
"tools": ["*"],
|
||||
"systemPrompt": "Du bist ein spezialisierter Agent für..."
|
||||
}
|
||||
```
|
||||
|
||||
### Felder
|
||||
|
||||
| Feld | Beschreibung |
|
||||
|------|-------------|
|
||||
| `tools` | `["*"]` für alle, oder Liste: `["read", "grep", "shell", "write"]` |
|
||||
| `systemPrompt` | Instruktionen für den Sub-Agenten |
|
||||
| `mcpServers` | Optional: zusätzliche MCP-Server für diesen Agenten |
|
||||
|
||||
### Beispiel: Ops-Agent
|
||||
|
||||
```json
|
||||
{
|
||||
"tools": ["*"],
|
||||
"systemPrompt": "Du bist ein Ops-Agent. Analysiere Kubernetes-Cluster: Pods, Deployments, Events, Logs. Identifiziere Probleme und schlage Lösungen vor. Nutze kubectl für alle Abfragen.",
|
||||
"mcpServers": {
|
||||
"orchestrator": {
|
||||
"url": "http://opencode-k8s-agent-${ART_NAME}-tools.${ART_NAME}-tools.svc.cluster.local:8080/mcp",
|
||||
"headers": {
|
||||
"x-runtime": "kiro",
|
||||
"x-agent-kiro-api-key": "${KIRO_API_KEY}",
|
||||
"x-agent-gitlab-token": "${GITLAB_TOKEN}"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Beispiel: Security-Agent
|
||||
|
||||
```json
|
||||
{
|
||||
"tools": ["read", "grep", "shell"],
|
||||
"systemPrompt": "Du bist ein Security-Agent. Prüfe Code auf Schwachstellen: SQL Injection, XSS, Secrets im Code, unsichere Dependencies. Nutze trivy und gitleaks. Erstelle einen strukturierten Security-Report."
|
||||
}
|
||||
```
|
||||
|
||||
## Laden der Profile
|
||||
|
||||
Das Entrypoint-Script kopiert beim Pod-Start automatisch alle `agents/*.json` nach `$HOME/.kiro/agents/`. Änderungen an Profilen werden beim nächsten Job-Start wirksam – kein Image-Rebuild nötig.
|
||||
|
||||
## MCP-Server für Sub-Agenten
|
||||
|
||||
Die `mcp.json` im Root dieses Repos wird als MCP-Konfiguration für alle Agenten geladen. Damit können Sub-Agenten:
|
||||
|
||||
- Den **Orchestrator** aufrufen (weitere K8s-Pods spawnen)
|
||||
- **Playwright** für Browser-Tests nutzen
|
||||
- Andere MCP-Server ansprechen (Jira, Confluence, etc.)
|
||||
|
||||
### Rekursive Hierarchie
|
||||
|
||||
Ein Sub-Agent kann über den Orchestrator-MCP-Server weitere Agent-Pods starten:
|
||||
|
||||
```
|
||||
Haupt-Agent (Pod A)
|
||||
└── subagent: researcher
|
||||
└── MCP: orchestrator.implement_ticket(...)
|
||||
└── Neuer Pod B startet
|
||||
└── arbeitet unabhängig
|
||||
```
|
||||
@@ -0,0 +1 @@
|
||||
{"tools":["*"],"systemPrompt":"Du bist ein Implementierungs-Agent. Setze die gegebene Aufgabe um: Code schreiben, Tests erstellen, committen. Arbeite präzise und vollständig."}
|
||||
@@ -0,0 +1 @@
|
||||
{"tools":["*"],"systemPrompt":"Du bist ein Research-Agent. Sammle Informationen, analysiere Code und Konfigurationen. Gib strukturierte Ergebnisse zurück. Keine Änderungen vornehmen."}
|
||||
@@ -0,0 +1 @@
|
||||
{"tools":["*"],"systemPrompt":"Du bist ein Review-Agent. Prüfe Code auf Qualität, Security, Best Practices. Gib strukturiertes Feedback mit konkreten Verbesserungsvorschlägen."}
|
||||
@@ -0,0 +1,73 @@
|
||||
# Autonomer Modus
|
||||
|
||||
Du arbeitest vollständig autonom. KEINE Rückfragen an den Benutzer.
|
||||
|
||||
## Regeln
|
||||
|
||||
- Triff alle Entscheidungen selbst basierend auf Best Practices und dem vorhandenen Code
|
||||
- Bei Unklarheiten: wähle die pragmatischste, konventionellste Option
|
||||
- Implementiere vollständig – keine Platzhalter, keine TODOs
|
||||
- Schreibe Tests für neuen Code
|
||||
- Wenn Tests fehlschlagen: analysiere und fixe (max 3 Versuche)
|
||||
- Dokumentiere getroffene Entscheidungen in der Commit-Message
|
||||
|
||||
## Git-Workflow (WICHTIG)
|
||||
|
||||
- **NIEMALS direkt auf `develop` oder `main` pushen**
|
||||
- Erstelle IMMER einen Feature-Branch: `feature/{ticket-id}` oder `experimental/{beschreibung}`
|
||||
- Committe auf den Feature-Branch
|
||||
- Erstelle einen **Merge Request** mit `glab mr create`
|
||||
- Der MR wird NICHT automatisch gemergt – er wartet auf menschliches Approval
|
||||
- Deine Aufgabe endet mit dem erstellten MR
|
||||
|
||||
### Branch-Naming
|
||||
|
||||
```
|
||||
feature/${JIRA_PREFIX}-123-kurze-beschreibung
|
||||
experimental/cluster-analyse
|
||||
bugfix/${JIRA_PREFIX}-456-fix-null-pointer
|
||||
```
|
||||
|
||||
### MR erstellen
|
||||
|
||||
```bash
|
||||
glab mr create \
|
||||
--title "feat(scope): kurze Beschreibung" \
|
||||
--description "$(cat <<MR
|
||||
## Zusammenfassung
|
||||
|
||||
Was wurde gemacht und warum.
|
||||
|
||||
## Änderungen
|
||||
|
||||
- Punkt 1
|
||||
- Punkt 2
|
||||
|
||||
## Testergebnisse
|
||||
|
||||
- Tests: ✅ X/X bestanden
|
||||
- Build: ✅ erfolgreich
|
||||
|
||||
## Entscheidungen
|
||||
|
||||
- Entscheidung A weil Grund B
|
||||
MR
|
||||
)" \
|
||||
--target-branch develop \
|
||||
--remove-source-branch
|
||||
```
|
||||
|
||||
## Entscheidungshilfen
|
||||
|
||||
- REST vs GraphQL → REST (außer Projekt nutzt bereits GraphQL)
|
||||
- Framework-Wahl → das was im Projekt bereits verwendet wird
|
||||
- Test-Framework → das was in der CI konfiguriert ist
|
||||
- Unsicher über Scope → lieber weniger aber vollständig als viel aber halbfertig
|
||||
|
||||
## Ausgabe kurz halten
|
||||
|
||||
- **Tool-Output nicht wiederholen** – nicht "Die Ausgabe war: ..." nacherzählen
|
||||
- **Dateien schreiben statt ausgeben** – Code direkt in Datei schreiben, nicht erst anzeigen
|
||||
- **Erfolgs-Output kürzen** – bei grünen Tests/Builds nur Zusammenfassung
|
||||
- **Fehlermeldungen IMMER vollständig lesen** – Stacktraces, Compiler-Errors komplett aufnehmen
|
||||
- **Kompakte Antworten** – keine langen Erklärungen an dich selbst
|
||||
@@ -0,0 +1,237 @@
|
||||
# Clean Code & Architektur
|
||||
|
||||
## Architektur: Ports & Adapters (Hexagonal)
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────┐
|
||||
│ Application Core │
|
||||
│ ┌─────────────────────────────────┐ │
|
||||
│ │ Domain Model │ │
|
||||
│ │ (Entities, Value Objects) │ │
|
||||
│ └─────────────────────────────────┘ │
|
||||
│ ┌─────────────────────────────────┐ │
|
||||
│ │ Use Cases / Services │ │
|
||||
│ │ (Business Logic, Ports) │ │
|
||||
│ └─────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────┘
|
||||
▲ ▲
|
||||
Driving Ports Driven Ports
|
||||
│ │
|
||||
┌────────┴───────┐ ┌────────┴───────┐
|
||||
│ REST API │ │ Repository │
|
||||
│ (Adapter) │ │ (Adapter) │
|
||||
│ Controller │ │ JPA/JDBC │
|
||||
└────────────────┘ └────────────────┘
|
||||
```
|
||||
|
||||
- **Domain**: Reine Business-Logik, keine Framework-Abhängigkeiten
|
||||
- **Ports**: Interfaces die Use Cases definieren (inbound) und externe Systeme abstrahieren (outbound)
|
||||
- **Adapters**: Implementierungen (REST Controller, JPA Repository, Kafka Consumer)
|
||||
|
||||
## Separation of Concerns
|
||||
|
||||
- **Controller/Handler**: Nur Request/Response Mapping, Validierung, keine Business-Logik
|
||||
- **Service**: Business-Logik, Orchestrierung, Transaktionen
|
||||
- **Repository/DAO**: Datenzugriff, Queries
|
||||
- **Model/Entity**: Datenstrukturen, Domain-Logik
|
||||
- **DTO**: Daten-Transfer zwischen Schichten (nicht Entity direkt exponieren)
|
||||
- **Mapper**: Entity ↔ DTO Konvertierung
|
||||
- **Config**: Konfiguration, Beans, Dependency Injection
|
||||
|
||||
## Exception Handling
|
||||
|
||||
### Strategie
|
||||
|
||||
- **Domain Exceptions**: Fachliche Fehler (z.B. `AddressNotFoundException`)
|
||||
- **Global Exception Handler**: `@RestControllerAdvice` für einheitliche Error-Responses
|
||||
- **Keine generischen Exceptions** werfen (nicht `throw new RuntimeException`)
|
||||
- **HTTP Status Codes** korrekt nutzen (400, 404, 409, 422, 500)
|
||||
|
||||
### Pattern
|
||||
|
||||
```java
|
||||
@RestControllerAdvice
|
||||
public class GlobalExceptionHandler {
|
||||
|
||||
@ExceptionHandler(EntityNotFoundException.class)
|
||||
public ResponseEntity<ErrorResponse> handleNotFound(EntityNotFoundException ex) {
|
||||
return ResponseEntity.status(404)
|
||||
.body(new ErrorResponse("NOT_FOUND", ex.getMessage()));
|
||||
}
|
||||
|
||||
@ExceptionHandler(ConstraintViolationException.class)
|
||||
public ResponseEntity<ErrorResponse> handleValidation(ConstraintViolationException ex) {
|
||||
return ResponseEntity.status(400)
|
||||
.body(new ErrorResponse("VALIDATION_ERROR", ex.getMessage()));
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Observability (Logging, Tracing, Metrics)
|
||||
|
||||
### Logging
|
||||
|
||||
- **Structured Logging** (JSON) mit SLF4J/Logback
|
||||
- Log-Level: ERROR (Fehler), WARN (unerwartetes Verhalten), INFO (Business-Events), DEBUG (Entwicklung)
|
||||
- **Correlation-ID** in jedem Log-Eintrag (aus Request-Header oder generiert)
|
||||
- Keine sensiblen Daten loggen (Passwörter, Tokens, PII)
|
||||
|
||||
### Tracing (OpenTelemetry)
|
||||
|
||||
- **OTEL** für Distributed Tracing (Spring Boot Actuator + Micrometer)
|
||||
- Trace-ID und Span-ID in Logs propagieren
|
||||
- Externe Calls (DB, HTTP, Kafka) automatisch instrumentiert
|
||||
|
||||
```yaml
|
||||
# application.yml
|
||||
management:
|
||||
tracing:
|
||||
sampling:
|
||||
probability: 1.0
|
||||
otlp:
|
||||
tracing:
|
||||
endpoint: http://k8s-monitoring-alloy-receiver.monitoring.svc.cluster.local:4317
|
||||
# CNP Grafana Alloy - OTLP gRPC Port 4317
|
||||
# Doku: https://cnp.gitpages.tech.rz.db.de/core/docs/cnp/latest/cnp-portfolio/observability/tracing.html
|
||||
```
|
||||
|
||||
### Metrics
|
||||
|
||||
- Spring Boot Actuator Endpoints (`/actuator/health`, `/actuator/metrics`, `/actuator/prometheus`)
|
||||
- Custom Business-Metrics wo sinnvoll (z.B. Bestellungen pro Minute)
|
||||
- Prometheus-Format für Grafana-Dashboards
|
||||
|
||||
### Health Checks
|
||||
|
||||
```yaml
|
||||
management:
|
||||
endpoint:
|
||||
health:
|
||||
show-details: always
|
||||
health:
|
||||
db:
|
||||
enabled: true
|
||||
kafka:
|
||||
enabled: true
|
||||
```
|
||||
|
||||
## Clean Code Prinzipien
|
||||
|
||||
- **Single Responsibility**: Eine Klasse/Funktion = eine Aufgabe
|
||||
- **DRY**: Keine Code-Duplikation, gemeinsame Logik extrahieren
|
||||
- **KISS**: Einfachste Lösung die funktioniert
|
||||
- **YAGNI**: Nichts implementieren was nicht gefordert ist
|
||||
- **Dependency Injection**: Abhängigkeiten injizieren, nicht selbst erstellen
|
||||
- **Interface Segregation**: Kleine, fokussierte Interfaces
|
||||
- **Open/Closed**: Offen für Erweiterung, geschlossen für Änderung
|
||||
|
||||
## Naming
|
||||
|
||||
- Klassen: PascalCase, Substantive (UserService, OrderRepository)
|
||||
- Methoden: camelCase, Verben (findById, createUser, validateInput)
|
||||
- Variablen: camelCase, sprechend (userCount statt n, isActive statt flag)
|
||||
- Konstanten: UPPER_SNAKE_CASE
|
||||
- Packages: lowercase, Singular (controller, service, model)
|
||||
|
||||
## Methoden
|
||||
|
||||
- Max 20 Zeilen (Richtwert)
|
||||
- Max 3 Parameter (sonst Object/DTO)
|
||||
- Keine boolean-Parameter (Split in zwei Methoden)
|
||||
- Early Return statt tiefe Verschachtelung
|
||||
|
||||
## Error Responses (API)
|
||||
|
||||
Einheitliches Format:
|
||||
|
||||
```json
|
||||
{
|
||||
"error": "NOT_FOUND",
|
||||
"message": "Address with id 42 not found",
|
||||
"timestamp": "2026-05-17T19:00:00Z",
|
||||
"path": "/api/addresses/42"
|
||||
}
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
- **application.yml** für Defaults
|
||||
- **application-{profile}.yml** für Stage-spezifisch (dev, iu, prod)
|
||||
- Secrets NICHT in application.yml (über Env-Variablen oder SecretProviderClass)
|
||||
- **@ConfigurationProperties** statt @Value für typsichere Config
|
||||
|
||||
## Mapper: MapStruct
|
||||
|
||||
Entity ↔ DTO Mapping über **MapStruct** (compile-time, kein Reflection):
|
||||
|
||||
```java
|
||||
@Mapper(componentModel = "spring")
|
||||
public interface AddressMapper {
|
||||
AddressDto toDto(Address entity);
|
||||
Address toEntity(AddressDto dto);
|
||||
List<AddressDto> toDtoList(List<Address> entities);
|
||||
}
|
||||
```
|
||||
|
||||
- Kein manuelles Mapping in Services
|
||||
- MapStruct generiert Implementierung zur Compile-Zeit
|
||||
- Bei komplexen Mappings: `@Mapping(source = "...", target = "...")`
|
||||
|
||||
## Lombok
|
||||
|
||||
Getter, Setter, Builder über **Lombok** (kein Boilerplate):
|
||||
|
||||
```java
|
||||
@Data // Getter + Setter + toString + equals + hashCode
|
||||
@Builder // Builder-Pattern
|
||||
@NoArgsConstructor // JPA braucht Default-Konstruktor
|
||||
@AllArgsConstructor // Für Builder
|
||||
@Entity
|
||||
public class Address {
|
||||
@Id @GeneratedValue(strategy = GenerationType.IDENTITY)
|
||||
private Long id;
|
||||
private String name;
|
||||
private String street;
|
||||
private String city;
|
||||
private String zip;
|
||||
}
|
||||
```
|
||||
|
||||
### Konventionen
|
||||
|
||||
- `@Data` für Entities und DTOs
|
||||
- `@Builder` für DTOs (immutable Construction)
|
||||
- `@Value` für immutable Value Objects (statt @Data)
|
||||
- `@Slf4j` für Logger (statt `private static final Logger log = ...`)
|
||||
- `@RequiredArgsConstructor` für Constructor-Injection (statt @Autowired)
|
||||
|
||||
## Validierung
|
||||
|
||||
### Schichten
|
||||
|
||||
1. **Bean Validation** (`@Valid`, `@NotNull`, `@Size`) – Syntaktische Prüfung im Controller
|
||||
2. **Business Rules** – Fachliche Validierung im Service/Validator (eigene Schicht)
|
||||
3. **Domain Invarianten** – Im Entity selbst (z.B. `@PrePersist`)
|
||||
|
||||
### Pattern: Separater Validator
|
||||
|
||||
```java
|
||||
@Component
|
||||
@RequiredArgsConstructor
|
||||
public class OrderValidator {
|
||||
|
||||
public void validate(OrderRequest request) {
|
||||
if (request.getQuantity() > MAX_QUANTITY) {
|
||||
throw new BusinessRuleViolationException("Maximale Bestellmenge überschritten");
|
||||
}
|
||||
// Weitere fachliche Regeln...
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Konventionen
|
||||
|
||||
- Bean Validation für einfache Feld-Prüfungen (nicht null, Format, Länge)
|
||||
- Eigener Validator für fachliche Regeln (Abhängigkeiten zwischen Feldern, DB-Lookups)
|
||||
- Business-Regeln NICHT im Controller
|
||||
- Custom Constraint-Annotations für wiederverwendbare Validierungen
|
||||
@@ -0,0 +1,105 @@
|
||||
# Code-Review (Self-Review mit GitLab Discussions)
|
||||
|
||||
**WICHTIG:** Code-Review erst durchführen wenn die MR-Pipeline GRÜN ist.
|
||||
Reihenfolge: Push → MR erstellen → Pipeline abwarten → Pipeline grün → Code-Review → Findings fixen → Merge.
|
||||
Nicht reviewen solange Pipeline noch läuft oder failed ist – erst Pipeline fixen!
|
||||
|
||||
## Ablauf nach MR-Erstellung (ERST wenn MR-Pipeline grün!)
|
||||
|
||||
1. **Code lokal reviewen** (nicht nur Diff, sondern gesamten Code)
|
||||
2. **Findings als GitLab Discussions anlegen**
|
||||
3. **Findings selbst fixen**
|
||||
4. **Threads resolven**
|
||||
5. **Erst mergen wenn alle Threads resolved**
|
||||
|
||||
## Review-Kriterien
|
||||
|
||||
### Clean Code
|
||||
- Single Responsibility Principle
|
||||
- Sprechende Namen (Variablen, Methoden, Klassen)
|
||||
- Kleine Methoden (max 20 Zeilen)
|
||||
- Kein toter Code, keine auskommentierten Blöcke
|
||||
- DRY (Don't Repeat Yourself)
|
||||
|
||||
### Separation of Concerns
|
||||
- Controller nur für HTTP-Handling (kein Business-Logic)
|
||||
- Service-Layer für Business-Logik
|
||||
- Repository nur für Datenzugriff
|
||||
- DTOs für API-Kommunikation (nicht Entity direkt exponieren)
|
||||
|
||||
### Best Practices
|
||||
- Input-Validierung (@Valid, Bean Validation)
|
||||
- Fehlerbehandlung (Exception Handler, sinnvolle HTTP Status Codes)
|
||||
- Logging an kritischen Stellen
|
||||
- Keine Secrets/Credentials im Code
|
||||
- Immutable wo möglich
|
||||
|
||||
### Tests
|
||||
- Alle öffentlichen Methoden getestet
|
||||
- Edge Cases abgedeckt (null, leer, ungültig)
|
||||
- Given-When-Then Struktur
|
||||
- Mocks nur wo nötig (keine Over-Mocking)
|
||||
|
||||
### Security
|
||||
- Keine SQL Injection (Parameterized Queries / JPA)
|
||||
- Keine XSS (Output Encoding)
|
||||
- Keine Secrets im Code
|
||||
- Dependencies ohne bekannte CVEs
|
||||
|
||||
## GitLab Discussion anlegen
|
||||
|
||||
```bash
|
||||
# Discussion an einer bestimmten Datei/Zeile
|
||||
glab api -X POST "projects/:id/merge_requests/{mr_iid}/discussions" \
|
||||
-f "body=**Clean Code:** Diese Methode hat zu viele Verantwortlichkeiten. Bitte in separate Methoden aufteilen." \
|
||||
-f "position[base_sha]=$(git merge-base main HEAD)" \
|
||||
-f "position[start_sha]=$(git merge-base main HEAD)" \
|
||||
-f "position[head_sha]=$(git rev-parse HEAD)" \
|
||||
-f "position[position_type]=text" \
|
||||
-f "position[new_path]=src/main/java/com/example/controller/AddressController.java" \
|
||||
-f "position[new_line]=42"
|
||||
|
||||
# Allgemeine Discussion (nicht an Datei gebunden)
|
||||
glab api -X POST "projects/:id/merge_requests/{mr_iid}/discussions" \
|
||||
-f "body=**Architektur:** Service-Layer fehlt. Controller greift direkt auf Repository zu. Bitte AddressService einführen."
|
||||
```
|
||||
|
||||
## Findings fixen und Thread resolven
|
||||
|
||||
```bash
|
||||
# Fix implementieren
|
||||
# ... Code ändern ...
|
||||
git add -A && git commit -m "fix(review): Service-Layer einführen (#issue)"
|
||||
git push
|
||||
|
||||
# Thread resolven
|
||||
glab api -X PUT "projects/:id/merge_requests/{mr_iid}/discussions/{discussion_id}" \
|
||||
-f "resolved=true"
|
||||
```
|
||||
|
||||
## Merge-Bedingung
|
||||
|
||||
```bash
|
||||
# Prüfen ob alle Threads resolved sind
|
||||
UNRESOLVED=$(glab api "projects/:id/merge_requests/{mr_iid}/discussions" | python3 -c "
|
||||
import sys, json
|
||||
discussions = json.load(sys.stdin)
|
||||
unresolved = [d for d in discussions if any(n.get('resolvable') and not n.get('resolved') for n in d.get('notes',[]))]
|
||||
print(len(unresolved))
|
||||
")
|
||||
|
||||
if [ "$UNRESOLVED" = "0" ]; then
|
||||
echo "Alle Threads resolved - merge möglich"
|
||||
glab mr merge --when-pipeline-succeeds
|
||||
else
|
||||
echo "Noch $UNRESOLVED offene Threads - erst fixen"
|
||||
fi
|
||||
```
|
||||
|
||||
## Wichtig
|
||||
|
||||
- Review den GESAMTEN Code, nicht nur den Diff
|
||||
- Mindestens 3 Review-Punkte prüfen (auch wenn alles gut aussieht → "LGTM" als Discussion)
|
||||
- Findings mit Kategorie-Prefix: **Clean Code:**, **Security:**, **Architektur:**, **Test:**
|
||||
- Jedes Finding muss actionable sein (konkreter Verbesserungsvorschlag)
|
||||
- Erst mergen wenn 0 unresolved Threads
|
||||
@@ -0,0 +1,130 @@
|
||||
# Dokumentation (Arc42 docs-as-code)
|
||||
|
||||
Referenz: arc42.org, Ralf D. Müller docs-as-code Ansatz.
|
||||
|
||||
## Verzeichnisstruktur
|
||||
|
||||
```
|
||||
docs/
|
||||
├── README.md ← Übersicht + Links zu allen Kapiteln
|
||||
├── arc42/
|
||||
│ ├── README.md ← Inhaltsverzeichnis der Arc42-Doku
|
||||
│ ├── 01-introduction-and-goals.md
|
||||
│ ├── 02-constraints.md
|
||||
│ ├── 03-context-and-scope.md
|
||||
│ ├── 04-solution-strategy.md
|
||||
│ ├── 05-building-block-view.md
|
||||
│ ├── 06-runtime-view.md
|
||||
│ ├── 07-deployment-view.md
|
||||
│ ├── 08-crosscutting-concepts.md
|
||||
│ ├── 09-architecture-decisions.md
|
||||
│ ├── 10-quality.md
|
||||
│ ├── 11-risks-and-technical-debt.md
|
||||
│ └── 12-glossary.md
|
||||
└── session-notes.md
|
||||
```
|
||||
|
||||
## README.md in jedem Verzeichnis
|
||||
|
||||
### Root README.md
|
||||
|
||||
Muss auf die Doku verlinken:
|
||||
|
||||
```markdown
|
||||
## Dokumentation
|
||||
|
||||
- [Arc42 Architekturdokumentation](docs/arc42/README.md)
|
||||
- [Session Notes](docs/session-notes.md)
|
||||
```
|
||||
|
||||
### docs/README.md
|
||||
|
||||
```markdown
|
||||
# Dokumentation
|
||||
|
||||
- [Arc42 Architektur](arc42/README.md)
|
||||
- [Session Notes](session-notes.md)
|
||||
```
|
||||
|
||||
### docs/arc42/README.md
|
||||
|
||||
```markdown
|
||||
# Arc42 Architekturdokumentation
|
||||
|
||||
| Kapitel | Inhalt |
|
||||
|---------|--------|
|
||||
| [01 - Einführung und Ziele](01-introduction-and-goals.md) | Aufgabenstellung, Qualitätsziele, Stakeholder |
|
||||
| [02 - Randbedingungen](02-constraints.md) | Technische, organisatorische Constraints |
|
||||
| [03 - Kontextabgrenzung](03-context-and-scope.md) | Systemkontext, externe Schnittstellen |
|
||||
| [04 - Lösungsstrategie](04-solution-strategy.md) | Fundamentale Entscheidungen |
|
||||
| [05 - Bausteinsicht](05-building-block-view.md) | Statische Zerlegung |
|
||||
| [06 - Laufzeitsicht](06-runtime-view.md) | Wichtige Abläufe |
|
||||
| [07 - Verteilungssicht](07-deployment-view.md) | Infrastruktur, Deployment |
|
||||
| [08 - Querschnittliche Konzepte](08-crosscutting-concepts.md) | Übergreifende Patterns |
|
||||
| [09 - Architekturentscheidungen](09-architecture-decisions.md) | ADRs |
|
||||
| [10 - Qualitätsanforderungen](10-quality.md) | Qualitätsbaum, Szenarien |
|
||||
| [11 - Risiken und technische Schulden](11-risks-and-technical-debt.md) | Bekannte Probleme |
|
||||
| [12 - Glossar](12-glossary.md) | Begriffe |
|
||||
```
|
||||
|
||||
## Kapitel-Inhalte (Mindestanforderung)
|
||||
|
||||
### 01 - Einführung und Ziele
|
||||
- Aufgabenstellung (was macht das System)
|
||||
- Qualitätsziele (Top 3)
|
||||
- Stakeholder-Tabelle
|
||||
|
||||
### 03 - Kontextabgrenzung
|
||||
- C4 Context-Diagramm als Mermaid:
|
||||
|
||||
```mermaid
|
||||
C4Context
|
||||
title System Context
|
||||
Person(user, "Benutzer")
|
||||
System(system, "Mein Service", "Beschreibung")
|
||||
System_Ext(ext, "Externes System")
|
||||
Rel(user, system, "Nutzt")
|
||||
Rel(system, ext, "Ruft auf")
|
||||
```
|
||||
|
||||
### 05 - Bausteinsicht
|
||||
- Komponenten-Diagramm (Mermaid)
|
||||
- Beschreibung der Hauptbausteine
|
||||
|
||||
### 06 - Laufzeitsicht
|
||||
- Sequenzdiagramm für Hauptflow (Mermaid)
|
||||
|
||||
### 07 - Verteilungssicht
|
||||
- Deployment-Diagramm (Mermaid) wenn deployed
|
||||
|
||||
### 09 - Architekturentscheidungen
|
||||
- Mindestens 1 ADR im Nygard-Format:
|
||||
|
||||
```markdown
|
||||
## ADR-1: Titel
|
||||
|
||||
### Status
|
||||
Accepted
|
||||
|
||||
### Context
|
||||
Problem/Situation.
|
||||
|
||||
### Decision
|
||||
Entscheidung.
|
||||
|
||||
### Consequences
|
||||
Auswirkungen (positiv + negativ).
|
||||
```
|
||||
|
||||
### 11 - Risiken
|
||||
- Bekannte Risiken und technische Schulden auflisten
|
||||
|
||||
### 12 - Glossar
|
||||
- Fachbegriffe des Projekts erklären
|
||||
|
||||
## Kontextabhängig
|
||||
|
||||
Arc42-Doku anlegen bei:
|
||||
- Services/APIs mit Deployment → Vollständig (alle 12 Kapitel)
|
||||
- Libraries → Minimal (01, 03, 05, 09)
|
||||
- Doku-Repos → KEINE Arc42 nötig
|
||||
@@ -0,0 +1,64 @@
|
||||
# Git-Setup
|
||||
|
||||
## GitLab Host
|
||||
|
||||
```bash
|
||||
export GITLAB_HOST=git.tech.rz.db.de
|
||||
export GITLAB_TOKEN=$GITLAB_PAT
|
||||
```
|
||||
|
||||
IMMER `GITLAB_HOST=git.tech.rz.db.de` setzen – glab nutzt sonst gitlab.com.
|
||||
|
||||
## Branching (mit Jira-Referenz)
|
||||
|
||||
- `develop` – Hauptentwicklungsbranch
|
||||
- `feature/*` – Feature-Branches
|
||||
- `Release_*` – Release-Tags (z.B. Release_40.04.03)
|
||||
- MRs gehen nach `develop`, nicht nach `main`
|
||||
|
||||
## Conventional Commits
|
||||
|
||||
```
|
||||
feat(benutzer): add user search endpoint (#123)
|
||||
fix(gateway): handle timeout in service call (#124)
|
||||
docs(arc42): update context diagram
|
||||
ci(pipeline): update pipelinetemplates to Release_40.04.04
|
||||
```
|
||||
|
||||
## Jira-Referenz
|
||||
|
||||
Der initiale Issue ist in Jira beschrieben. Branch-Name und Commits MÜSSEN die Jira-Nummer referenzieren:
|
||||
|
||||
```bash
|
||||
# Branch-Name
|
||||
feature/${JIRA_PREFIX}-1234-user-search
|
||||
bugfix/${JIRA_PREFIX}-5678-fix-timeout
|
||||
|
||||
# Commits
|
||||
feat(benutzer): add user search endpoint (${JIRA_PREFIX}-1234)
|
||||
fix(gateway): handle timeout in service call (${JIRA_PREFIX}-5678)
|
||||
```
|
||||
|
||||
### MR-Title
|
||||
|
||||
```
|
||||
feat(benutzer): add user search endpoint (${JIRA_PREFIX}-1234)
|
||||
bugfix(gateway): fix timeout in service call (${JIRA_PREFIX}-5678)
|
||||
```
|
||||
|
||||
GitLab verlinkt automatisch auf Jira wenn die Issue-Nummer im Commit/MR steht.
|
||||
|
||||
## Commit-Message Prefix (Konvention)
|
||||
|
||||
Jede Commit-Message und jeder MR-Title beginnt mit dem Branch-Namen in eckigen Klammern:
|
||||
|
||||
```bash
|
||||
# Commits
|
||||
[feature/${JIRA_PREFIX}-1234-user-search] feat(benutzer): add user search endpoint
|
||||
[bugfix/${JIRA_PREFIX}-5678-fix-timeout] fix(gateway): handle timeout in service call
|
||||
|
||||
# MR-Title
|
||||
[feature/${JIRA_PREFIX}-1234-user-search] feat(benutzer): add user search endpoint
|
||||
```
|
||||
|
||||
Format: `[{branch-name}] {conventional commit message}`
|
||||
@@ -0,0 +1,19 @@
|
||||
allprojects {
|
||||
repositories {
|
||||
maven {
|
||||
url "https://bahnhub.tech.rz.db.de/artifactory/maven-remote/"
|
||||
allowInsecureProtocol = false
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
settingsEvaluated { settings ->
|
||||
settings.pluginManagement {
|
||||
repositories {
|
||||
maven {
|
||||
url "https://bahnhub.tech.rz.db.de/artifactory/maven-remote/"
|
||||
allowInsecureProtocol = false
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,24 @@
|
||||
{
|
||||
"playwright": {
|
||||
"type": "local",
|
||||
"command": ["npx", "-y", "@playwright/mcp", "--headless", "--browser", "msedge", "--no-sandbox", "--isolated"],
|
||||
"enabled": true
|
||||
},
|
||||
"dbctx": {
|
||||
"url": "https://taros-playground-dbctx.apps.dbcs-prag.comp.db.de/mcp",
|
||||
"enabled": true
|
||||
},
|
||||
"workflows": {
|
||||
"type": "local",
|
||||
"command": ["npx", "-y", "@codemcp/workflows-server"],
|
||||
"enabled": true
|
||||
},
|
||||
"jira": {
|
||||
"url": "https://taros-playground-mcp-jira-v2.apps.dbcs-prag.comp.db.de/mcp",
|
||||
"enabled": true
|
||||
},
|
||||
"confluence": {
|
||||
"url": "https://taros-playground-mcp-confluence.apps.dbcs-prag.comp.db.de/mcp",
|
||||
"enabled": true
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,120 @@
|
||||
# Merge Request Standards
|
||||
|
||||
## MR-Title: Conventional Commit Format (Pflicht)
|
||||
|
||||
```
|
||||
feat(scope): kurze Beschreibung
|
||||
fix(auth): Token-Refresh bei 401 Response
|
||||
docs(arc42): Context-Diagramm ergänzen
|
||||
```
|
||||
|
||||
## MR-Description: Markdown (Pflicht)
|
||||
|
||||
Jede MR braucht eine **ausführliche Beschreibung** in Markdown:
|
||||
|
||||
```markdown
|
||||
## Zusammenfassung
|
||||
|
||||
Kurze Beschreibung was diese MR macht und warum.
|
||||
|
||||
## Änderungen
|
||||
|
||||
- Controller für `/api/users` mit CRUD-Operationen
|
||||
- Service-Layer mit Validierung
|
||||
- Integration-Tests mit Testcontainers
|
||||
|
||||
## Gelöste Issues
|
||||
|
||||
Closes #1, Closes #3
|
||||
|
||||
## Testergebnisse
|
||||
|
||||
- Unit-Tests: ✅ 12/12
|
||||
- Integration-Tests: ✅ 4/4
|
||||
- Coverage: 85%
|
||||
|
||||
## Screenshots / Beispiele
|
||||
|
||||
(Falls UI-Änderungen oder API-Responses)
|
||||
```
|
||||
|
||||
## Assignee: Immer sich selbst
|
||||
|
||||
```bash
|
||||
glab mr create \
|
||||
--title "feat(users): implement CRUD REST API" \
|
||||
--description "$(cat mr-description.md)" \
|
||||
--assignee "@me" \
|
||||
--remove-source-branch \
|
||||
--fill
|
||||
```
|
||||
|
||||
## Checkliste vor MR-Erstellung
|
||||
|
||||
- [ ] Alle Issues angelegt und referenziert
|
||||
- [ ] Pipeline grün
|
||||
- [ ] Tests geschrieben und bestanden
|
||||
- [ ] Conventional Commit im Title
|
||||
- [ ] Ausführliche Description in Markdown
|
||||
- [ ] Assignee gesetzt (@me)
|
||||
|
||||
## Self-Review, Approve und Merge
|
||||
|
||||
Nach MR-Erstellung und grüner Pipeline:
|
||||
|
||||
### 1. Self-Review durchführen
|
||||
|
||||
```bash
|
||||
# Diff des MR anschauen
|
||||
glab mr diff
|
||||
|
||||
# Prüfpunkte:
|
||||
# - Keine Debug-Code/TODOs vergessen?
|
||||
# - Keine Secrets im Code?
|
||||
# - Tests vollständig?
|
||||
# - Doku aktuell?
|
||||
# - Naming Conventions eingehalten?
|
||||
```
|
||||
|
||||
### 2. Approve (wenn Review OK)
|
||||
|
||||
```bash
|
||||
glab mr approve
|
||||
```
|
||||
|
||||
### 3. Merge (wenn Pipeline grün + Review OK)
|
||||
|
||||
```bash
|
||||
glab mr merge --when-pipeline-succeeds
|
||||
```
|
||||
|
||||
### Bedingungen für Auto-Merge
|
||||
|
||||
Nur mergen wenn ALLE Bedingungen erfüllt:
|
||||
- [ ] Pipeline ist grün (alle Jobs passed)
|
||||
- [ ] Self-Review durchgeführt (keine Findings)
|
||||
- [ ] Keine offenen Threads/Diskussionen
|
||||
- [ ] Keine CRITICAL/HIGH Trivy-Findings
|
||||
|
||||
Wenn eine Bedingung NICHT erfüllt ist → NICHT mergen, stattdessen:
|
||||
- Findings als Kommentar am MR dokumentieren
|
||||
- Fixen wenn möglich
|
||||
- Oder um Hilfe bitten (HELP:)
|
||||
|
||||
## Nach dem Merge: Main-Pipeline prüfen
|
||||
|
||||
Nach `glab mr merge` startet eine Pipeline auf main. Diese MUSS auch grün sein:
|
||||
|
||||
```bash
|
||||
# Merge durchführen
|
||||
glab mr merge --when-pipeline-succeeds
|
||||
|
||||
# Danach: Main-Pipeline überwachen
|
||||
sleep 30
|
||||
glab ci status # zeigt jetzt main-Pipeline
|
||||
|
||||
# Bei Fehler auf main: sofort fixen (neuer Branch, neuer MR)
|
||||
```
|
||||
|
||||
Der Merge ist erst wirklich erfolgreich wenn die Main-Pipeline grün ist.
|
||||
Wenn main failed → Issue anlegen, Fix-Branch erstellen, fixen, MR, mergen.
|
||||
@@ -0,0 +1,159 @@
|
||||
# Planung mit Responsible Vibe + GitLab Issues
|
||||
|
||||
## Entwicklungsprozess
|
||||
|
||||
Nutze den `workflows` MCP Server (Responsible Vibe) für strukturierte Entwicklung:
|
||||
|
||||
1. **`start_development()`** – Workflow starten (greenfield für neue Projekte)
|
||||
2. **`whats_next()`** – Nach JEDER Aktion aufrufen für nächsten Schritt
|
||||
3. **`proceed_to_phase()`** – Phase wechseln wenn Kriterien erfüllt
|
||||
|
||||
## GitLab Issues: PFLICHT vor Implementierung
|
||||
|
||||
**BEVOR du eine einzige Zeile Code schreibst**, MUSST du Issues anlegen:
|
||||
|
||||
```bash
|
||||
# Labels erstellen (einmalig)
|
||||
glab label create "enhancement" --color "#428BCA"
|
||||
glab label create "bug" --color "#d9534f"
|
||||
glab label create "documentation" --color "#5cb85c"
|
||||
glab label create "test" --color "#f0ad4e"
|
||||
glab label create "ci/cd" --color "#777777"
|
||||
glab label create "refactoring" --color "#9b59b6"
|
||||
|
||||
# Issues anlegen – JEDE Aufgabe wird ein Issue
|
||||
glab issue create --title "feat: REST Controller implementieren" --description "Endpoints: GET/POST/PUT/DELETE /api/..." --label "enhancement"
|
||||
glab issue create --title "feat: Service-Layer mit Business-Logik" --description "Validierung, Error-Handling, ..." --label "enhancement"
|
||||
glab issue create --title "test: Unit- und Integrationstests" --description "Controller-Tests, Service-Tests, Testcontainers" --label "test"
|
||||
glab issue create --title "docs: Arc42 + README" --description "Context-Diagramm, ADRs, API-Doku" --label "documentation"
|
||||
glab issue create --title "ci: Pipeline konfigurieren" --description ".gitlab-ci.yml, Helm Values, Deployment" --label "ci/cd"
|
||||
```
|
||||
|
||||
**Reihenfolge:**
|
||||
1. Aufgabe analysieren
|
||||
2. In 3-7 Issues zerlegen
|
||||
3. Issues in GitLab anlegen
|
||||
4. Erst DANN implementieren
|
||||
|
||||
## Ablauf (strikt einhalten)
|
||||
|
||||
1. `start_development()` → Workflow initialisieren
|
||||
2. `whats_next()` → Plan erstellen
|
||||
3. **Issues in GitLab anlegen** (PFLICHT, nicht optional!)
|
||||
4. Issues der Reihe nach abarbeiten:
|
||||
- Implementieren
|
||||
- Testen
|
||||
- Committen mit Issue-Referenz: `feat(users): implement GET endpoint (#1)`
|
||||
- Issue schließen: `glab issue close 1`
|
||||
5. `whats_next()` → Nächste Phase
|
||||
6. Wiederholen bis alle Issues geschlossen
|
||||
|
||||
## Commit-Messages: Conventional Commits (Pflicht)
|
||||
|
||||
```
|
||||
feat(controller): implement GET /users endpoint (#1)
|
||||
feat(service): add validation and error handling (#2)
|
||||
test(controller): add WebMvcTest for UserController (#3)
|
||||
docs(arc42): add context diagram and ADR-1 (#4)
|
||||
ci(pipeline): add .gitlab-ci.yml from pipelinetemplates (#5)
|
||||
```
|
||||
|
||||
Format: `type(scope): beschreibung (#issue-nummer)`
|
||||
|
||||
## Fragen selbst beantworten
|
||||
|
||||
Responsible Vibe stellt in den Phasen Fragen (z.B. "Wer nutzt das System?", "Welche Constraints gibt es?").
|
||||
|
||||
**WICHTIG:** Diese Fragen NICHT an den Benutzer weiterleiten. Beantworte sie selbst basierend auf:
|
||||
1. Der Ticket-Beschreibung / Aufgabe ($TICKET_DESCRIPTION)
|
||||
2. Dem Projekt-Kontext (vorhandener Code, README, etc.)
|
||||
3. Best Practices und Conventions aus dem Steering
|
||||
4. Sinnvollen Defaults wenn keine Info vorhanden
|
||||
|
||||
Der Agent arbeitet autonom – er ist Entwickler UND Product Owner in einem.
|
||||
|
||||
## Issue-Labels nach Workflow-Typ
|
||||
|
||||
| Workflow | Label | Beschreibung |
|
||||
|----------|-------|-------------|
|
||||
| greenfield | `enhancement` | Neues Projekt/Feature |
|
||||
| epcc | `enhancement` | Feature zu bestehendem Projekt |
|
||||
| bugfix | `bug` | Fehlerbehebung |
|
||||
| tdd | `test` | Test-getriebene Entwicklung |
|
||||
| minor | `chore` | Kleine Änderung/Refactoring |
|
||||
|
||||
## GitLab Issues: Qualität
|
||||
|
||||
Issues MÜSSEN ausführlich in Markdown geschrieben werden:
|
||||
|
||||
### Format
|
||||
|
||||
```bash
|
||||
glab issue create \
|
||||
--title "feat: Address REST API (CRUD)" \
|
||||
--label "enhancement" \
|
||||
--description "## Beschreibung
|
||||
|
||||
REST Controller mit vollständigen CRUD Endpoints für die Adressverwaltung.
|
||||
|
||||
## Anforderungen
|
||||
|
||||
- GET /api/addresses – Alle Adressen auflisten
|
||||
- GET /api/addresses/{id} – Einzelne Adresse
|
||||
- POST /api/addresses – Neue Adresse anlegen
|
||||
- PUT /api/addresses/{id} – Adresse aktualisieren
|
||||
- DELETE /api/addresses/{id} – Adresse löschen
|
||||
|
||||
## Akzeptanzkriterien
|
||||
|
||||
- [ ] Alle Endpoints implementiert und getestet
|
||||
- [ ] Validierung der Eingaben (Name, PLZ nicht leer)
|
||||
- [ ] Korrekte HTTP Status Codes (201, 404, 400)
|
||||
- [ ] JSON Request/Response Format dokumentiert
|
||||
|
||||
## Technische Details
|
||||
|
||||
- Spring @RestController
|
||||
- @Valid für Bean Validation
|
||||
- ResponseEntity für Status Codes"
|
||||
```
|
||||
|
||||
### Regeln
|
||||
|
||||
- **Mehrzeilige Descriptions**: Heredoc oder mehrzeilige Strings nutzen, KEINE `\n` Escapes
|
||||
- **Markdown-Struktur**: Überschriften (##), Listen (-), Checkboxen (- [ ])
|
||||
- **Inhalt**: Beschreibung, Anforderungen, Akzeptanzkriterien, technische Details
|
||||
- **Ausführlich**: Jedes Issue muss für sich allein verständlich sein
|
||||
|
||||
## Arc42 Dokumentation: PFLICHT-Issue
|
||||
|
||||
Bei JEDEM Projekt muss ein Issue für Arc42-Doku angelegt und abgearbeitet werden:
|
||||
|
||||
```bash
|
||||
glab issue create \
|
||||
--title "docs: Arc42 Dokumentation erstellen" \
|
||||
--label "documentation" \
|
||||
--description "## Beschreibung
|
||||
|
||||
Arc42-Dokumentation unter docs/arc42/ anlegen.
|
||||
|
||||
## Pflicht-Inhalte
|
||||
|
||||
- docs/arc42/01-introduction.md (Aufgabenstellung, Qualitätsziele)
|
||||
- docs/arc42/03-context.md (C4 Context-Diagramm als Mermaid)
|
||||
- docs/arc42/05-building-blocks.md (Komponenten-Übersicht)
|
||||
- docs/arc42/06-runtime-view.md (Sequenzdiagramm Hauptflow)
|
||||
- docs/arc42/09-architecture-decisions.md (mind. 1 ADR im Nygard-Format)
|
||||
|
||||
## Akzeptanzkriterien
|
||||
|
||||
- [ ] Mindestens 5 Arc42-Dateien unter docs/arc42/
|
||||
- [ ] C4 Context-Diagramm als Mermaid
|
||||
- [ ] Mindestens 1 ADR (z.B. Stack-Wahl, Datenbank-Wahl)
|
||||
- [ ] Sequenzdiagramm für den Hauptflow"
|
||||
```
|
||||
|
||||
Arc42-Doku ist kontextabhängig:
|
||||
- Services/APIs mit Deployment → Arc42 anlegen
|
||||
- Libraries, CLI-Tools, Doku-Repos → KEINE Arc42 nötig
|
||||
- Bestehende Projekte mit vorhandener Doku → nur ergänzen wenn sinnvoll
|
||||
@@ -0,0 +1,132 @@
|
||||
# Projekt-Setup Standards
|
||||
|
||||
## Pflichtdateien für jedes neue Repo
|
||||
|
||||
### LICENSE.adoc
|
||||
|
||||
```adoc
|
||||
= DB Inner Source License (DBISL)
|
||||
|
||||
Copyright (c) Deutsche Bahn AG
|
||||
|
||||
Permission is hereby granted to any employee of Deutsche Bahn AG and its
|
||||
subsidiaries to use, copy, modify, and distribute this software within
|
||||
the Deutsche Bahn group of companies.
|
||||
|
||||
This software may not be distributed outside of Deutsche Bahn AG without
|
||||
explicit written permission.
|
||||
```
|
||||
|
||||
### scm-info.yaml
|
||||
|
||||
```yaml
|
||||
name: "{project-name}"
|
||||
description: "{kurze Beschreibung}"
|
||||
owner:
|
||||
team: "{team-name}"
|
||||
email: "{team-email}"
|
||||
lifecycle: "active"
|
||||
classification: "internal"
|
||||
language: "{java|python|go|typescript}"
|
||||
```
|
||||
|
||||
### README.md
|
||||
|
||||
```markdown
|
||||
# {Project Name}
|
||||
|
||||
[]
|
||||
[]
|
||||
|
||||
## Beschreibung
|
||||
|
||||
{Was macht das Projekt}
|
||||
|
||||
## Quickstart
|
||||
|
||||
{Wie starte ich es lokal}
|
||||
|
||||
## Build & Test
|
||||
|
||||
{Build- und Test-Befehle}
|
||||
|
||||
## Deployment
|
||||
|
||||
{Wie wird es deployed}
|
||||
```
|
||||
|
||||
### .gitignore
|
||||
|
||||
Passend zum Stack generieren (Java: target/, .idea/ | Python: __pycache__/, .venv/ | etc.)
|
||||
|
||||
### .gitlab-ci.yml
|
||||
|
||||
Siehe gitlab-ci.md
|
||||
|
||||
## Repo-Struktur nach Stack
|
||||
|
||||
### Java (Spring Boot)
|
||||
```
|
||||
├── src/main/java/de/db/{team}/{project}/
|
||||
│ ├── controller/
|
||||
│ ├── service/
|
||||
│ ├── repository/
|
||||
│ ├── model/
|
||||
│ └── config/
|
||||
├── src/main/resources/
|
||||
│ └── application.yml
|
||||
├── src/test/java/de/db/{team}/{project}/
|
||||
├── pom.xml
|
||||
├── LICENSE.adoc
|
||||
├── scm-info.yaml
|
||||
├── README.md
|
||||
├── .gitignore
|
||||
└── .gitlab-ci.yml
|
||||
```
|
||||
|
||||
### Python (FastAPI)
|
||||
```
|
||||
├── src/{project}/
|
||||
│ ├── __init__.py
|
||||
│ ├── main.py
|
||||
│ ├── api/
|
||||
│ ├── services/
|
||||
│ ├── models/
|
||||
│ └── config.py
|
||||
├── tests/
|
||||
├── pyproject.toml
|
||||
├── LICENSE.adoc
|
||||
├── scm-info.yaml
|
||||
├── README.md
|
||||
├── .gitignore
|
||||
└── .gitlab-ci.yml
|
||||
```
|
||||
|
||||
### Go
|
||||
```
|
||||
├── cmd/{project}/main.go
|
||||
├── internal/
|
||||
│ ├── handler/
|
||||
│ ├── service/
|
||||
│ └── model/
|
||||
├── go.mod
|
||||
├── LICENSE.adoc
|
||||
├── scm-info.yaml
|
||||
├── README.md
|
||||
├── .gitignore
|
||||
└── .gitlab-ci.yml
|
||||
```
|
||||
|
||||
## Templates
|
||||
|
||||
Die Vorlagen für Pflichtdateien liegen im Steering-Repo unter `/templates/`:
|
||||
|
||||
- `templates/LICENSE.adoc` → 1:1 kopieren (DB Inner Source Lizenz, NICHT ändern)
|
||||
- `templates/scm-info.yaml` → kopieren und `{CONTACT_EMAIL}` ersetzen
|
||||
|
||||
```bash
|
||||
cp /steering/templates/LICENSE.adoc ./LICENSE.adoc
|
||||
cp /steering/templates/scm-info.yaml ./scm-info.yaml
|
||||
# Platzhalter ersetzen
|
||||
sed -i "s/{CONTACT_EMAIL}/team@deutschebahn.com/" scm-info.yaml
|
||||
```
|
||||
@@ -0,0 +1,115 @@
|
||||
# Quality Gates (Pflicht vor jedem Commit)
|
||||
|
||||
## Reihenfolge vor dem Commit
|
||||
|
||||
Alle Checks MÜSSEN lokal bestehen bevor committed wird:
|
||||
|
||||
### 1. Linter (je nach Stack)
|
||||
|
||||
```bash
|
||||
# Java
|
||||
./mvnw checkstyle:check
|
||||
|
||||
# Python
|
||||
ruff check .
|
||||
ruff format --check .
|
||||
|
||||
# Go
|
||||
golangci-lint run
|
||||
|
||||
# Node/TypeScript
|
||||
npm run lint
|
||||
|
||||
# Shell-Scripts
|
||||
shellcheck *.sh
|
||||
|
||||
# YAML
|
||||
yamllint .
|
||||
|
||||
# Dockerfile
|
||||
hadolint Dockerfile
|
||||
```
|
||||
|
||||
### 2. Tests
|
||||
|
||||
```bash
|
||||
# Java
|
||||
./mvnw test
|
||||
|
||||
# Python
|
||||
pytest -v --cov --cov-fail-under=80
|
||||
|
||||
# Go
|
||||
go test ./... -cover
|
||||
|
||||
# Node
|
||||
npm test
|
||||
```
|
||||
|
||||
### 3. Security-Scans
|
||||
|
||||
```bash
|
||||
# Secrets im Code suchen
|
||||
gitleaks detect --source . --no-git
|
||||
|
||||
# Dependency-Vulnerabilities (Filesystem)
|
||||
trivy fs --severity HIGH,CRITICAL .
|
||||
|
||||
# Docker-Image scannen (wenn Dockerfile vorhanden)
|
||||
docker build -t app:scan .
|
||||
trivy image --severity HIGH,CRITICAL app:scan
|
||||
```
|
||||
|
||||
### 4. Erst dann committen
|
||||
|
||||
Nur wenn ALLE Checks grün sind:
|
||||
```bash
|
||||
git add -A
|
||||
git commit -m "feat(scope): beschreibung (#issue)"
|
||||
```
|
||||
|
||||
## Bei Findings
|
||||
|
||||
- **Linter-Fehler**: Sofort fixen
|
||||
- **Test-Failures**: Code korrigieren bis grün
|
||||
- **Trivy HIGH/CRITICAL**: Dependency updaten oder begründen (ADR)
|
||||
- **Gitleaks**: Secret entfernen, .gitignore anpassen
|
||||
|
||||
## Verfügbare Tools im Container
|
||||
|
||||
Alle vorinstalliert – keine Installation nötig:
|
||||
- `trivy` – Container/Filesystem/Dependency Scanner
|
||||
- `gitleaks` – Secret Detection
|
||||
- `golangci-lint` – Go Linter
|
||||
- `ruff` – Python Linter/Formatter
|
||||
- `hadolint` – Dockerfile Linter
|
||||
- `shellcheck` – Shell Script Linter
|
||||
- `yamllint` – YAML Linter
|
||||
|
||||
## Renovate-MRs prüfen (vor Dependency-Änderungen)
|
||||
|
||||
BEVOR du manuell Dependencies aktualisierst oder Vulnerabilities fixst:
|
||||
|
||||
```bash
|
||||
# Offene Renovate-MRs im Projekt prüfen
|
||||
GITLAB_HOST=git.tech.rz.db.de glab mr list --author=renovate-bot --state=opened
|
||||
```
|
||||
|
||||
Wenn Renovate bereits einen MR für die betroffene Dependency hat:
|
||||
1. **Nicht selbst fixen** – Renovate-MR nutzen
|
||||
2. Pipeline des Renovate-MR prüfen
|
||||
3. Bei grüner Pipeline: Approve + Merge
|
||||
4. Bei fehlgeschlagener Pipeline: Retry oder manuell fixen und in den Renovate-Branch pushen
|
||||
|
||||
### Warum?
|
||||
|
||||
- Renovate trackt Versionen zentral
|
||||
- Doppelte Updates führen zu Merge-Konflikten
|
||||
- Renovate erstellt saubere Changelogs
|
||||
- Renovate-MRs sind bereits getestet
|
||||
|
||||
### Nur manuell fixen wenn:
|
||||
|
||||
- Kein Renovate-MR existiert
|
||||
- Renovate-MR ist seit >7 Tagen offen und blockiert
|
||||
- Renovate kann die Vulnerability nicht lösen (z.B. Major-Version-Sprung nötig)
|
||||
@@ -0,0 +1,111 @@
|
||||
# Requirements-Review (vor Implementierung)
|
||||
|
||||
## Ablauf bei Issue-basierter Aufgabe
|
||||
|
||||
Wenn die Aufgabe als GitLab Issue übergeben wird (statt Freitext):
|
||||
|
||||
### 1. Issue lesen und analysieren
|
||||
|
||||
```bash
|
||||
glab issue view {issue-id} --repo {repo}
|
||||
```
|
||||
|
||||
### 2. Anforderung kritisch reviewen
|
||||
|
||||
Prüfe ob folgende Fragen beantwortet sind:
|
||||
|
||||
**Fachlichkeit:**
|
||||
- Ist die Domäne/der Fachkontext verstanden?
|
||||
- Gibt es Fachbegriffe die unklar sind?
|
||||
- Welche Business-Regeln gelten?
|
||||
- Gibt es Abhängigkeiten zu anderen fachlichen Prozessen?
|
||||
|
||||
**Funktional:**
|
||||
- Was genau soll das System tun?
|
||||
- Wer sind die Nutzer?
|
||||
- Welche Ein-/Ausgaben gibt es?
|
||||
- Welche Edge Cases gibt es?
|
||||
|
||||
**Nicht-funktional:**
|
||||
- Performance-Anforderungen (Response-Zeit, Concurrent Users)?
|
||||
- Verfügbarkeit?
|
||||
- Security-Anforderungen?
|
||||
|
||||
**Technisch:**
|
||||
- Stack/Framework vorgegeben?
|
||||
- Schnittstellen zu anderen Systemen?
|
||||
- Deployment-Ziel?
|
||||
|
||||
**Akzeptanzkriterien:**
|
||||
- Sind Gherkin-Szenarien vorhanden?
|
||||
- Wann ist die Aufgabe "fertig"?
|
||||
|
||||
### 3. Offene Fragen als Kommentar am Issue
|
||||
|
||||
Wenn Informationen fehlen → Kommentar am Issue mit konkreten Fragen:
|
||||
|
||||
```bash
|
||||
glab issue comment {issue-id} --repo {repo} --body "## Offene Fragen zur Anforderung
|
||||
|
||||
Bevor ich mit der Implementierung beginne, bitte folgende Punkte klären:
|
||||
|
||||
1. **Performance:** Wie viele gleichzeitige Nutzer werden erwartet? Gibt es Response-Zeit-Anforderungen?
|
||||
2. **Validierung:** Welche Felder sind Pflicht? Gibt es Format-Vorgaben (z.B. PLZ nur 5-stellig)?
|
||||
3. **Auth:** Soll die API authentifiziert sein oder öffentlich?
|
||||
|
||||
Sobald geklärt, starte ich die Implementierung."
|
||||
```
|
||||
|
||||
### 4. Warten oder selbst entscheiden
|
||||
|
||||
- **Wenn Fragen kritisch sind** (Architektur-Entscheidung, unklarer Scope): Warten auf Antwort
|
||||
- **Wenn Fragen nice-to-have sind** (Details die man mit Best Practices lösen kann): Selbst entscheiden und dokumentieren
|
||||
|
||||
### 5. Implementierung starten
|
||||
|
||||
Erst wenn die Anforderung klar ist:
|
||||
- Alle kritischen Fragen beantwortet
|
||||
- Oder: Agent hat pragmatische Defaults gewählt und dokumentiert
|
||||
|
||||
```bash
|
||||
echo "PROGRESS: 5% - Requirements-Review abgeschlossen, starte Implementierung"
|
||||
```
|
||||
|
||||
## Bei Freitext-Aufgabe (kein Issue)
|
||||
|
||||
Wenn die Aufgabe als Freitext kommt (über implement_ticket):
|
||||
- Selbst ein Issue anlegen mit der Aufgabe
|
||||
- Fehlende Infos mit Best Practices/Defaults füllen
|
||||
- Entscheidungen als ADR dokumentieren
|
||||
- Direkt implementieren (nicht warten)
|
||||
|
||||
## Wann sind Anforderungen klar?
|
||||
|
||||
- **Keine offenen Fragen** → Anforderungen klar → direkt implementieren
|
||||
- **Offene Fragen** → Kommentar am Issue → warten
|
||||
|
||||
### Ablauf bei offenen Fragen
|
||||
|
||||
```bash
|
||||
# 1. Fragen als Kommentar posten
|
||||
glab issue comment {id} --body "## Offene Fragen ..."
|
||||
|
||||
# 2. Signal geben dass du wartest
|
||||
echo "HELP: Warte auf Antwort zu offenen Fragen am Issue #{id}"
|
||||
|
||||
# 3. Warten bis Antwort kommt (via send_message vom User/Kiro)
|
||||
# → Agent bekommt Nachricht: "Fragen beantwortet, siehe Issue-Kommentar"
|
||||
|
||||
# 4. Issue-Kommentare erneut lesen
|
||||
glab issue view {id} --comments
|
||||
|
||||
# 5. Weiterarbeiten
|
||||
echo "PROGRESS: 5% - Requirements klar, starte Implementierung"
|
||||
```
|
||||
|
||||
### Kiro als Vermittler
|
||||
|
||||
Kiro sieht `needs_help: true` + `help_message: "Warte auf Antwort..."` und kann:
|
||||
- Den User informieren
|
||||
- Selbst die Fragen beantworten (wenn er den Kontext hat)
|
||||
- Oder `send_message` an den Agent schicken: "Fragen beantwortet, siehe Kommentar"
|
||||
@@ -0,0 +1,15 @@
|
||||
---
|
||||
# Docs: https://git.tech.rz.db.de/db-inner-source/scm-info-json-schema
|
||||
version: v3
|
||||
license: LicenseRef-DBISL
|
||||
contacts:
|
||||
- ${CONTACT_EMAIL}
|
||||
confidentiality: internal
|
||||
reference-ids:
|
||||
- none
|
||||
protected-branches:
|
||||
- main
|
||||
custom:
|
||||
integrity: normal
|
||||
availability: normal
|
||||
confidentiality: normal
|
||||
@@ -0,0 +1,210 @@
|
||||
# Self-Review & Pipeline-Überwachung
|
||||
|
||||
## Code-Review vor Push
|
||||
|
||||
Vor dem Push den eigenen Code reviewen:
|
||||
- Naming Conventions eingehalten?
|
||||
- Keine TODOs oder Debug-Code?
|
||||
- Tests vollständig?
|
||||
- Doku aktuell?
|
||||
|
||||
## Pipeline-Überwachung (Pflicht nach jedem Push)
|
||||
|
||||
Nach JEDEM `git push` die Pipeline überwachen mit Polling:
|
||||
|
||||
```bash
|
||||
# Pipeline-Status abfragen (wiederholen bis nicht mehr "running")
|
||||
glab ci status
|
||||
|
||||
# Wenn "running" → 30 Sekunden warten und erneut prüfen
|
||||
sleep 30
|
||||
glab ci status
|
||||
|
||||
# Bei "failed" → Logs des fehlgeschlagenen Jobs anzeigen
|
||||
glab ci view
|
||||
```
|
||||
|
||||
### Polling-Schleife (so implementieren):
|
||||
|
||||
```bash
|
||||
# Solange "running" → weiter pollen
|
||||
while true; do
|
||||
STATUS=$(glab ci status 2>&1)
|
||||
echo "$STATUS"
|
||||
if echo "$STATUS" | grep -q "passed"; then
|
||||
echo "Pipeline erfolgreich!"
|
||||
break
|
||||
elif echo "$STATUS" | grep -qE "failed|canceled"; then
|
||||
echo "Pipeline fehlgeschlagen – abbrechen und fixen"
|
||||
glab ci cancel
|
||||
glab ci view
|
||||
break
|
||||
fi
|
||||
sleep 30
|
||||
done
|
||||
```
|
||||
|
||||
### WICHTIG:
|
||||
- `glab ci status` funktioniert OHNE `--wait` Flag
|
||||
- NICHT die GitLab API direkt aufrufen (kein Zugriff auf Web-UI)
|
||||
- Einfach `glab ci status` wiederholt aufrufen mit `sleep 30` dazwischen
|
||||
|
||||
## Bei Pipeline-Fehler
|
||||
|
||||
1. `glab ci view` – Fehlgeschlagenen Job identifizieren
|
||||
2. Fehler analysieren
|
||||
3. Fix committen
|
||||
4. Erneut pushen
|
||||
5. Pipeline erneut überwachen
|
||||
|
||||
## Deployment-Stages
|
||||
|
||||
| Branch | Umgebung | Automatisch? |
|
||||
|--------|----------|-------------|
|
||||
| Feature-Branch | Preview (Dev) | ✅ Ja |
|
||||
| main | Produktion | ✅ Ja (nach Merge) |
|
||||
|
||||
## Pipeline-Fehler diagnostizieren
|
||||
|
||||
### Logs lesen mit glab
|
||||
|
||||
```bash
|
||||
# Jobs der Pipeline auflisten
|
||||
glab api "projects/:id/pipelines/$(glab ci status 2>&1 | grep -oP '#\K[0-9]+')/jobs"
|
||||
|
||||
# Job-Log lesen (Job-ID aus obigem Output)
|
||||
glab api "projects/:id/jobs/{job_id}/trace"
|
||||
|
||||
# Wenn keine Jobs vorhanden (leeres Array []):
|
||||
# → Kein Runner verfügbar ODER .gitlab-ci.yml fehlerhaft
|
||||
```
|
||||
|
||||
### Häufige Fehler
|
||||
|
||||
| Symptom | Ursache | Fix |
|
||||
|---------|---------|-----|
|
||||
| Pipeline failed, keine Jobs | YAML-Fehler | `.gitlab-ci.yml` prüfen |
|
||||
| Job failed: "image not found" | Falsches Docker-Image | DB Container Lib Image nutzen |
|
||||
|
||||
## Um Hilfe bitten (statt endlos loopen)
|
||||
|
||||
Wenn du nach **3 Versuchen** ein Problem nicht lösen kannst:
|
||||
|
||||
1. **STOPPE** – nicht weiter versuchen
|
||||
2. **Dokumentiere** das Problem klar in einer Nachricht:
|
||||
- Was du versucht hast
|
||||
- Welcher Fehler auftritt
|
||||
- Was du als Ursache vermutest
|
||||
3. **Schreibe in die Konsole**: `echo "HELP: <deine Frage>"`
|
||||
|
||||
Beispiel:
|
||||
```
|
||||
Ich komme nicht weiter. Die Pipeline schlägt fehl:
|
||||
- Symptom: Pipeline failed, keine Jobs werden gestartet
|
||||
- Versucht: .gitlab-ci.yml angepasst (3x)
|
||||
- Frage: Wie sieht die korrekte .gitlab-ci.yml für dieses Projekt aus?
|
||||
```
|
||||
|
||||
### Wann um Hilfe bitten:
|
||||
- Pipeline-Fehler nach 3 Fix-Versuchen
|
||||
- Zugriffsprobleme (401/403/404)
|
||||
- Unklare Anforderungen
|
||||
- Fehlende Credentials oder Konfiguration
|
||||
- Tool funktioniert nicht wie erwartet
|
||||
|
||||
### NICHT endlos loopen bei:
|
||||
- Gleichem Fehler der sich wiederholt
|
||||
- Timeout/Netzwerk-Problemen
|
||||
- Fehlenden Berechtigungen
|
||||
|
||||
## Pipeline manuell triggern
|
||||
|
||||
Wenn nach einem Push keine neue Pipeline startet (alter SHA in `glab ci status`):
|
||||
|
||||
```bash
|
||||
# Pipeline manuell für aktuellen Branch triggern
|
||||
glab ci create --ref $(git branch --show-current)
|
||||
```
|
||||
|
||||
Dann erneut mit `glab ci status` überwachen.
|
||||
|
||||
## Kein Runner verfügbar
|
||||
|
||||
Wenn Pipeline failed mit 0 Jobs oder Jobs ewig "pending" bleiben:
|
||||
- Ursache: Kein Runner mit passenden Tags im Projekt
|
||||
- Das ist ein Infrastruktur-Problem, kein Code-Problem
|
||||
- In der MR-Beschreibung vermerken: "Pipeline benötigt Runner mit Tags: group-runner, kubernetes"
|
||||
- Nicht endlos versuchen zu fixen
|
||||
|
||||
## MR-Pipeline überwachen
|
||||
|
||||
- MR-Pipeline hat alle Jobs (lint, test, build, deploy)
|
||||
|
||||
**Ablauf:**
|
||||
1. Push auf Feature-Branch
|
||||
2. MR erstellen (`glab mr create ...`)
|
||||
3. DANN Pipeline überwachen: `glab ci status` (zeigt MR-Pipeline)
|
||||
4. Bei Fehler: `glab ci list` → Job-Logs lesen → fixen → pushen
|
||||
5. MR-Pipeline startet automatisch neu nach Push
|
||||
|
||||
**Job-Logs lesen:**
|
||||
```bash
|
||||
# Fehlgeschlagene Jobs finden
|
||||
glab ci list
|
||||
|
||||
# Trace eines bestimmten Jobs (non-interaktiv)
|
||||
glab api "projects/:id/jobs/{job_id}/trace" | tail -50
|
||||
```
|
||||
|
||||
### Signal für Hilfe
|
||||
|
||||
Wenn du nicht weiterkommst, schreibe EXAKT dieses Format in die Shell:
|
||||
|
||||
```bash
|
||||
echo "HELP: Pipeline failed mit 0 Jobs - wie soll die .gitlab-ci.yml aussehen?"
|
||||
```
|
||||
|
||||
Das `HELP:` Prefix wird vom Orchestrator erkannt und signalisiert dem Benutzer im Dashboard, dass du Hilfe brauchst. Warte danach auf eine Antwort.
|
||||
|
||||
### Pipeline-Status loggen
|
||||
|
||||
Beim Überwachen der Pipeline den Status in die Konsole schreiben, damit das Dashboard den Fortschritt zeigt:
|
||||
|
||||
```bash
|
||||
echo "PROMPT: Pipeline überwachen - warte auf MR-Pipeline"
|
||||
# ... polling ...
|
||||
echo "PROMPT: Pipeline grün - alle Jobs bestanden"
|
||||
# oder
|
||||
echo "PROMPT: Pipeline fehlgeschlagen - Job lint_scm_info failed"
|
||||
```
|
||||
|
||||
### Fortschritt und ETA loggen
|
||||
|
||||
Nach jedem abgeschlossenen Arbeitsschritt den Fortschritt melden:
|
||||
|
||||
```bash
|
||||
echo "PROGRESS: 20% - Issues angelegt, starte Implementierung (ETA: 8min)"
|
||||
echo "PROGRESS: 50% - Backend fertig, starte Frontend (ETA: 5min)"
|
||||
echo "PROGRESS: 70% - Tests geschrieben, starte Quality Gates (ETA: 3min)"
|
||||
echo "PROGRESS: 85% - Gepusht, MR erstellt, warte auf Pipeline (ETA: 2min)"
|
||||
echo "PROGRESS: 100% - Fertig"
|
||||
```
|
||||
|
||||
Format: `PROGRESS: {prozent}% - {was gerade passiert} (ETA: {geschätzte Restzeit})`
|
||||
|
||||
Schätze die ETA basierend auf:
|
||||
- Anzahl verbleibender Issues/Aufgaben
|
||||
- Bisherige Dauer pro Schritt
|
||||
- Komplexität der verbleibenden Arbeit
|
||||
|
||||
### Referenzen in Logs
|
||||
|
||||
Wenn du Issues, MRs oder Pipelines erstellst/referenzierst, gib die URL oder Referenz mit an:
|
||||
|
||||
```bash
|
||||
echo "PROMPT: Issues angelegt: #1 #2 #3 #4 in https://git.tech.rz.db.de/group/project"
|
||||
echo "PROMPT: MR erstellt: https://git.tech.rz.db.de/group/project/-/merge_requests/1"
|
||||
echo "PROMPT: Pipeline überwachen: https://git.tech.rz.db.de/group/project/-/pipelines/12345"
|
||||
```
|
||||
|
||||
Das Dashboard macht URLs und #Issue/!MR-Referenzen automatisch klickbar.
|
||||
@@ -0,0 +1,70 @@
|
||||
# Session-Notes (Arbeitsprotokoll)
|
||||
|
||||
## Ablageort
|
||||
|
||||
Session-Notes werden **im Projekt-Repository** abgelegt (nicht im Agent-Workspace):
|
||||
|
||||
```
|
||||
{projekt-root}/
|
||||
├── docs/
|
||||
│ └── arc42/ ← Architektur-Dokumentation
|
||||
├── session-notes/ ← Arbeitsprotokoll des Agenten
|
||||
│ └── 2026-05-14-initial-setup.md
|
||||
├── src/
|
||||
└── ...
|
||||
```
|
||||
|
||||
Beides wird committed und gepusht – so ist alles im Git nachvollziehbar.
|
||||
|
||||
## Pflicht
|
||||
|
||||
Bei JEDEM Task ein Protokoll anlegen:
|
||||
```
|
||||
session-notes/{datum}-{kurzbeschreibung}.md
|
||||
```
|
||||
|
||||
## Format
|
||||
|
||||
```markdown
|
||||
# Session: {Kurzbeschreibung}
|
||||
|
||||
**Datum:** {ISO-Datum}
|
||||
**Aufgabe:** {Was wurde beauftragt}
|
||||
**Modell:** {Welches LLM wurde verwendet}
|
||||
|
||||
## Ablauf
|
||||
|
||||
| Zeit | Aktion | Ergebnis |
|
||||
|------|--------|----------|
|
||||
| 14:30 | Repo angelegt | ✅ |
|
||||
| 14:31 | Projektstruktur erstellt | ✅ |
|
||||
| 14:33 | Tests geschrieben | ✅ |
|
||||
| 14:35 | mvn test | ❌ Fehler in XY |
|
||||
| 14:36 | Fix: ... | ✅ |
|
||||
| 14:38 | Coverage 85% | ✅ |
|
||||
| 14:39 | Push + MR | ✅ |
|
||||
|
||||
## Entscheidungen
|
||||
|
||||
- REST statt GraphQL gewählt (Projekt-Konvention)
|
||||
- JaCoCo statt Cobertura (Maven-Standard)
|
||||
→ Wichtige Entscheidungen als ADR in docs/arc42/09-architecture-decisions.md dokumentieren
|
||||
|
||||
## Probleme
|
||||
|
||||
- Coverage initial unter 80% wegen Main-Klasse → JaCoCo Exclude konfiguriert
|
||||
|
||||
## Ergebnis
|
||||
|
||||
- Repo: {URL}
|
||||
- MR: {URL}
|
||||
- Pipeline: ✅ grün
|
||||
```
|
||||
|
||||
## Wichtig
|
||||
|
||||
- Zeitstempel bei jeder Aktion
|
||||
- Entscheidungen dokumentieren (wichtige → ADR in Arc42)
|
||||
- Probleme und deren Lösung festhalten
|
||||
- Am Ende: Links zu Repo, MR, Pipeline
|
||||
- ALLES wird committed und gepusht (ist Teil des Repos)
|
||||
@@ -0,0 +1,306 @@
|
||||
DB Inner Source Lizenz Version 1.0
|
||||
|
||||
_Fachautoren: Cornelius Schumacher, Schlomo Schapiro (DB Systel GmbH)_
|
||||
|
||||
Diese Inner-Source-Lizenz für die Deutsche Bahn („DBISL“) gilt für Werke
|
||||
(im Sinne der nachfolgenden Begriffsbestimmung), die unter
|
||||
DBISL-Bedingungen zur Verfügung gestellt werden. Das Werk darf nur in
|
||||
der durch diese Lizenz gestatteten Form genutzt werden (insoweit eine
|
||||
solche Nutzung dem Urheber vorbehalten ist).
|
||||
|
||||
Das Werk wird unter den Bedingungen dieser Lizenz zur Verfügung
|
||||
gestellt, wenn der Lizenzgeber (im Sinne der nachfolgenden
|
||||
Begriffsbestimmung) den folgenden Hinweis unmittelbar hinter dem
|
||||
Urheberrechtshinweis dieses Werks anbringt:
|
||||
|
||||
„Lizenziert unter der DBISL“ oder alternativ „Licensed under the DBISL“
|
||||
|
||||
oder in einer anderen Form zum Ausdruck bringt, dass er es unter der
|
||||
DBISL lizenzieren möchte.
|
||||
|
||||
== 1. Begriffsbestimmungen
|
||||
|
||||
Für diese Lizenz gelten folgende Begriffsbestimmungen:
|
||||
|
||||
* „Lizenz“: diese Lizenz.
|
||||
* „Originalwerk“: das Werk oder die Software, die vom Lizenzgeber unter
|
||||
dieser Lizenz verbreitet oder zugänglich gemacht wird, und zwar als
|
||||
Quellcode und gegebenenfalls auch als ausführbarer Code.
|
||||
* „Bearbeitungen“: die Werke oder Software, die der Lizenznehmer auf der
|
||||
Grundlage des Originalwerks oder seiner Bearbeitungen schaffen kann. In
|
||||
dieser Lizenz wird nicht festgelegt, wie umfangreich die Änderung oder
|
||||
wie stark die Abhängigkeit vom Originalwerk für eine Einstufung als
|
||||
Bearbeitung sein muss; dies bestimmt sich nach dem anwendbaren
|
||||
Urheberrecht
|
||||
* „Werk“: das Originalwerk oder seine Bearbeitungen.
|
||||
* „Quellcode“: diejenige Form des Werkes, die zur Auffassung durch den
|
||||
Menschen bestimmt ist und die am besten geeignet ist, um vom Menschen
|
||||
verstanden und verändert zu werden.
|
||||
* „Ausführbarer Code“: die — üblicherweise — kompilierte Form des Werks,
|
||||
die von einem Computer als Programm ausgeführt werden soll.
|
||||
* „Lizenzgeber“: die juristische Person innerhalb des DB Konzerns, die
|
||||
das Werk unter der Lizenz verbreitet oder zugänglich macht.
|
||||
* „Urheberrechtsinhaber/Autor“: jeder, der bestimmte von ihm selbst
|
||||
entwickelte oder von Dritten vorgegebene Aufgabenstellungen in ein
|
||||
Originalwerk umsetzt oder am Originalwerk eine Bearbeitung vornimmt.
|
||||
* „Bearbeiter“: jeder, der das Werk unter der Lizenz verändert oder auf
|
||||
andere Weise zur Schaffung einer Bearbeitung beiträgt. Jeder Autor ist
|
||||
auch Bearbeiter.
|
||||
* „Lizenznehmer“ („Sie“, „Ihnen“): jede juristische Person innerhalb des
|
||||
DB Konzerns, die das Werk unter den Lizenzbedingungen nutzt.
|
||||
* „Verbreitung“ oder „Zugänglichmachung“: alle Formen von Verkauf,
|
||||
Überlassung, Verleih, Vermietung, Verbreitung, Weitergabe, Übermittlung
|
||||
oder anderweitiger Online- oder Offline-Bereitstellung von
|
||||
Vervielfältigungen des Werks oder Zugänglichmachung seiner wesentlichen
|
||||
Funktionen für dritte natürliche oder juristische Personen.
|
||||
* „Beitrag“: jedes urheberrechtliche Werk, einschließlich des
|
||||
Originalwerks sowie jeglicher Änderungen, die der Bearbeiter vornimmt,
|
||||
und die dem Lizenzgeber bewusst zur Aufnahme in das Werk eingereicht
|
||||
werden.
|
||||
* „DB“ oder „DB Konzern“: die Deutsche Bahn AG und alle mit ihr nach §
|
||||
15 AktG verbundenen Unternehmen.
|
||||
|
||||
== 2. Umfang der Lizenzrechte
|
||||
|
||||
Der Lizenzgeber erteilt Ihnen hiermit eine weltweite, unentgeltliche,
|
||||
nicht ausschließliche, unterlizenzierbare Lizenz, die Sie für
|
||||
Geschäftszwecke des DB Konzerns berechtigt:
|
||||
|
||||
* das Werk uneingeschränkt zu nutzen,
|
||||
* das Werk zu vervielfältigen,
|
||||
* das Werk zu verändern und Bearbeitungen auf der Grundlage des Werks zu
|
||||
schaffen,
|
||||
* das Werk oder Vervielfältigungen davon innerhalb der DB zu verbreiten,
|
||||
|
||||
Für die Wahrnehmung dieser Rechte können beliebige, derzeit bekannte
|
||||
oder künftige Medien, Träger und Formate verwendet werden, soweit das
|
||||
geltende Recht dem nicht entgegensteht.
|
||||
|
||||
Der Lizenzgeber erteilt dem Lizenznehmer ein nicht ausschließliches,
|
||||
unentgeltliches Nutzungsrecht an seinen Patenten, sofern dies zur
|
||||
Ausübung der durch die Lizenz erteilten Nutzungsrechte am Werk notwendig
|
||||
ist.
|
||||
|
||||
== 3. Zugänglichmachung des Quellcodes
|
||||
|
||||
Der Lizenzgeber kann das Werk entweder als Quellcode oder als
|
||||
ausführbaren Code zur Verfügung stellen. Stellt er es als ausführbaren
|
||||
Code zur Verfügung, so stellt er darüber hinaus eine maschinenlesbare
|
||||
Kopie des Quellcodes für jedes von ihm verbreitete
|
||||
Vervielfältigungsstück des Werks zur Verfügung, oder er verweist in
|
||||
einem Vermerk im Anschluss an den dem Werk beigefügten
|
||||
Urheberrechtshinweis auf einen Speicherort, an dem problemlos und
|
||||
unentgeltlich auf den Quellcode zugegriffen werden kann, solange der
|
||||
Lizenzgeber das Werk verbreitet oder zugänglich macht.
|
||||
|
||||
== 4. Einschränkungen des Urheberrechts
|
||||
|
||||
Es ist nicht Zweck dieser Lizenz, Ausnahmen oder Schranken der
|
||||
ausschließlichen Rechte des Urhebers am Werk, die dem Lizenznehmer
|
||||
zugutekommen, einzuschränken. Auch die Erschöpfung dieser Rechte bleibt
|
||||
von dieser Lizenz unberührt.
|
||||
|
||||
== 5. Pflichten des Lizenznehmers
|
||||
|
||||
Die Einräumung der oben genannten Rechte ist an mehrere Beschränkungen
|
||||
und Pflichten für den Lizenznehmer gebunden:
|
||||
|
||||
* Inner Source: Der Lizenznehmer darf das Werk ausschließlich für
|
||||
Geschäftszwecke des DB Konzerns nutzen.
|
||||
* Urheberrechtshinweis, Lizenztext, Nennung des Bearbeiters: Der
|
||||
Lizenznehmer muss alle Urheberrechts-, Patent- oder Markenrechtshinweise
|
||||
und alle Hinweise auf die Lizenz und den Haftungsausschluss unverändert
|
||||
lassen. Jedem von ihm verbreiteten oder zugänglich gemachten
|
||||
Vervielfältigungsstück des Werks muss der Lizenznehmer diese Hinweise
|
||||
sowie diese Lizenz beifügen. Der Lizenznehmer muss auf jedem
|
||||
abgeleiteten Werk deutlich darauf hinweisen, dass das Werk geändert
|
||||
wurde, und das Datum der Bearbeitung angeben.
|
||||
* „Copyleft“-Klausel: Der Lizenznehmer darf Vervielfältigungen des
|
||||
Originalwerks oder Bearbeitungen nur unter den Bedingungen dieser DBISL
|
||||
oder einer neueren Version dieser Lizenz innerhalb der DB verbreiten
|
||||
oder zugänglich machen. Der Lizenznehmer (der zum Lizenzgeber wird) darf
|
||||
für das Werk oder die Bearbeitung keine zusätzlichen Bedingungen
|
||||
anbieten oder vorschreiben, die die Bedingungen dieser Lizenz verändern
|
||||
oder einschränken.
|
||||
* Bereitstellung des Quellcodes: Wenn der Lizenznehmer
|
||||
Vervielfältigungsstücke des Werks verbreitet oder zugänglich macht, muss
|
||||
er eine maschinenlesbare Fassung des Quellcodes mitliefern oder einen
|
||||
Speicherort angeben, über den problemlos und unentgeltlich so lange auf
|
||||
diesen Quellcode zugegriffen werden kann, wie der Lizenznehmer das Werk
|
||||
verbreitet oder zugänglich macht.
|
||||
* Rechtsschutz: Diese Lizenz erlaubt nicht die Benutzung von
|
||||
Kennzeichen, Marken oder geschützten Namensrechten des Lizenzgebers,
|
||||
soweit dies nicht für die angemessene und übliche Beschreibung der
|
||||
Herkunft des Werks und der inhaltlichen Wiedergabe des
|
||||
Urheberrechtshinweises erforderlich ist.
|
||||
|
||||
== 6. Urheber und Bearbeiter
|
||||
|
||||
Der ursprüngliche Lizenzgeber gewährleistet, dass er das Urheberrecht am
|
||||
Originalwerk innehat oder dieses an ihn lizenziert wurde und dass er
|
||||
befugt ist, diese Lizenz zu erteilen.
|
||||
|
||||
Jeder Bearbeiter gewährleistet, dass er das Urheberrecht an den von ihm
|
||||
vorgenommenen Änderungen des Werks besitzt und befugt ist, einen Beitrag
|
||||
unter dieser Lizenz zu erstellen und beizutragen.
|
||||
|
||||
Für jeden Fall, in dem der Lizenznehmer die Lizenz annimmt, erteilt der
|
||||
ursprüngliche Lizenzgeber und alle folgenden Bearbeiter eine Befugnis
|
||||
zur Nutzung der Beiträge zum Werk unter den Bedingungen dieser Lizenz.
|
||||
|
||||
== 7. Gewährleistungsausschluss
|
||||
|
||||
Falls die konzerninternen Leistungsbedingungen keine Anwendung finden,
|
||||
gelten die folgenden Regelungen.
|
||||
|
||||
Die Arbeit an diesem Werk wird laufend fortgeführt; es wird durch
|
||||
unzählige Bearbeiter ständig verbessert. Das Werk ist nicht vollendet
|
||||
und kann daher Fehler („Bugs“) enthalten, die dieser Art der Entwicklung
|
||||
inhärent sind.
|
||||
|
||||
Aus den genannten Gründen wird das Werk unter dieser Lizenz „so, wie es
|
||||
ist“ ohne jegliche Gewährleistung zur Verfügung gestellt. Dies gilt
|
||||
unter anderem — aber nicht ausschließlich — für Marktreife,
|
||||
Verwendbarkeit für einen bestimmten Zweck, Mängelfreiheit, Richtigkeit
|
||||
sowie Nichtverletzung von anderen Immaterialgüterrechten als dem
|
||||
Urheberrecht (vgl. dazu Artikel 6 dieser Lizenz).
|
||||
|
||||
Dieser Gewährleistungsausschluss ist wesentlicher Bestandteil der Lizenz
|
||||
und Bedingung für die Einräumung von Rechten an dem Werk.
|
||||
|
||||
== 8. Haftungsausschluss/Haftungsbeschränkung
|
||||
|
||||
Falls die konzerninternen Leistungsbedingungen keine Anwendung finden,
|
||||
gelten die folgenden Regelungen.
|
||||
|
||||
Außer in Fällen von Vorsatz oder der Verursachung von Personenschäden
|
||||
haftet der Lizenzgeber nicht für direkte oder indirekte, materielle oder
|
||||
immaterielle Schäden irgendwelcher Art, die aus der Lizenz oder der
|
||||
Benutzung des Werks folgen; dies gilt unter anderem, aber nicht
|
||||
ausschließlich, für Firmenwertverluste, Produktionsausfall,
|
||||
Computerausfall oder Computerfehler, Datenverlust oder wirtschaftliche
|
||||
Schäden, und zwar auch dann, wenn der Lizenzgeber auf die Möglichkeit
|
||||
solcher Schäden hingewiesen wurde. Unabhängig davon haftet der
|
||||
Lizenzgeber im Rahmen der gesetzlichen Produkthaftung, soweit die
|
||||
entsprechenden Regelungen auf das Werk anwendbar sind.
|
||||
|
||||
== 9. Zusatzvereinbarungen
|
||||
|
||||
Wenn der Lizenznehmer das Werk verbreitet, kann er Zusatzvereinbarungen
|
||||
schließen, in denen Verpflichtungen oder Dienstleistungen festgelegt
|
||||
werden, die mit dieser Lizenz vereinbar sind.
|
||||
|
||||
Der Lizenznehmer darf Verpflichtungen nur in seinem eigenen Namen
|
||||
eingehen, nicht jedoch im Namen des ursprünglichen Lizenzgebers oder
|
||||
eines anderen Bearbeiters, und nur, wenn er sich gegenüber allen
|
||||
Bearbeitern verpflichtet, sie zu entschädigen, zu verteidigen und von
|
||||
der Haftung freizustellen, falls aufgrund der von ihm eingegangenen
|
||||
Gewährleistungsverpflichtung oder Haftungsübernahme Forderungen gegen
|
||||
sie geltend gemacht werden oder eine Haftungsverpflichtung entsteht.
|
||||
|
||||
== 10. Annahme der Lizenz
|
||||
|
||||
Der Lizenznehmer stimmt den Bestimmungen dieser Lizenz zu, indem er das
|
||||
Symbol „Lizenz annehmen“ unter dem Fenster mit dem Lizenztext anklickt
|
||||
oder indem er seine Zustimmung auf vergleichbare Weise gibt. Das
|
||||
Anklicken des Symbols gilt als Anzeichen der eindeutigen und
|
||||
unwiderruflichen Annahme der Lizenz und der darin enthaltenen Klauseln
|
||||
und Bedingungen.
|
||||
|
||||
In gleicher Weise gilt als Zeichen der eindeutigen und unwiderruflichen
|
||||
Zustimmung die Ausübung eines Rechtes, das in Artikel 2 dieser Lizenz
|
||||
angeführt ist, wie das Erstellen einer Bearbeitung oder die Verbreitung
|
||||
oder Zugänglichmachung des Werks oder dessen Vervielfältigungen.
|
||||
|
||||
== 11. Informationspflichten
|
||||
|
||||
Wenn der Lizenznehmer das Werk verbreitet oder zugänglich macht
|
||||
(beispielsweise, indem er es zum Herunterladen von einer Website
|
||||
anbietet), muss der Lizenznehmer über den Vertriebskanal oder das
|
||||
benutzte Verbreitungsmedium dem Adressatenkreis bzw. der Öffentlichkeit
|
||||
Mindest-Informationen bereitstellen, üblicherweise bezüglich der
|
||||
Lizenzgeber, der Lizenz und ihrer Zugänglichkeit, des Abschlusses des
|
||||
Lizenzvertrags sowie darüber, wie die Lizenz durch den Lizenznehmer
|
||||
gespeichert und vervielfältigt werden kann.
|
||||
|
||||
== 12. Beendigung der Lizenz
|
||||
|
||||
Die Lizenz und die damit eingeräumten Rechte erlöschen automatisch, wenn
|
||||
der Lizenznehmer gegen die Lizenzbedingungen verstößt.
|
||||
|
||||
Ein solches Erlöschen der Lizenz führt nicht zum Erlöschen der Lizenzen
|
||||
von Dritten, denen das Werk vom Lizenznehmer unter dieser Lizenz zur
|
||||
Verfügung gestellt worden ist, solange diese Personen die
|
||||
Lizenzbedingungen erfüllen.
|
||||
|
||||
== 13. Einreichung von Beiträgen
|
||||
|
||||
Sofern nichts ausdrücklich anderes angegeben, unterliegt jeder Beitrag,
|
||||
den der Lizenzgeber bewusst zur Aufnahme in das Werk eingereicht hat,
|
||||
den Bedingungen dieser Lizenz, ohne dass zusätzliche Bedingungen gelten.
|
||||
Ungeachtet des Vorstehenden ersetzt oder ändert keine der hierin
|
||||
enthaltenen Bestimmungen die Bedingungen einer separaten
|
||||
Lizenzvereinbarung, die der Auftraggeber möglicherweise mit dem
|
||||
Auftragnehmer für solche Beiträge abgeschlossen hat.
|
||||
|
||||
Für die Länder, in denen Urheberpersönlichkeitsrechte an einem Werk
|
||||
entstehen können, verzichtet der Urheberrechtsinhaber/Autor im
|
||||
gesetzlich zulässigen Umfang auf seine Urheberpersönlichkeitsrechte, um
|
||||
die Lizenzierung der oben aufgeführten Verwertungsrechte wirksam
|
||||
durchführen zu können.
|
||||
|
||||
== 14. Sonstiges
|
||||
|
||||
Unbeschadet des Artikels 9 stellt diese Lizenz die vollständige
|
||||
Vereinbarung der Parteien über das Werk dar.
|
||||
|
||||
Es gilt deutsches Recht. Sind einzelne Bestimmungen der Lizenz nach
|
||||
geltendem Recht nichtig oder unwirksam, so berührt dies nicht die
|
||||
Wirksamkeit oder Durchsetzbarkeit der Lizenz an sich. Solche
|
||||
Bestimmungen werden vielmehr dergestalt ausgelegt oder modifiziert, dass
|
||||
sie wirksam und durchsetzbar sind.
|
||||
|
||||
== 15. Gesellschaftsrechtliche Veränderungen
|
||||
|
||||
Bei gesellschaftsrechtlichen Veränderungen, z.B. dem Verkauf oder der
|
||||
Abspaltung einer DB Gesellschaft, gilt folgende Regelungen in Anlehnung
|
||||
an §12 Beendigungsunterstützung der konzerninternen
|
||||
Leistungsbedingungen:
|
||||
|
||||
Eine weitere Nutzung der lizenzierten Software durch ein nicht mehr dem
|
||||
DB Konzern angehöriges Unternehmen unterliegt der Zustimmung durch die
|
||||
Urheber bzw. das CIO Board.
|
||||
|
||||
== 16. Lizenzänderungen
|
||||
|
||||
Die Urheber eines Werks können gemeinsam eine Änderung der Lizenz
|
||||
entscheiden, z.B. um das Werk als Open Source Software zu
|
||||
veröffentlichen. Falls die Urheber nicht verfügbar sind oder sich nicht
|
||||
einigen können, so kann das CIO Board stellvertretend für alle Urheber
|
||||
innerhalb der DB die Änderung der Lizenz für ein Werk beschließen.
|
||||
|
||||
== 17. Streitbeilegung
|
||||
|
||||
Unbeschadet der Regelungen in den konzerninternen Leistungsbedingungen
|
||||
zwischen den Parteien gilt zwischen den Parteien Folgendes:
|
||||
|
||||
Bei Streitigkeiten im Zusammenhang mit der Auslegung und Anwendung
|
||||
dieser Lizenz, bei denen mehr als ein Konzernunternehmen beteiligt ist,
|
||||
dient das CIO Board des Konzerns als Entscheidungsgremium, welches von
|
||||
jeder Partei angerufen werden kann.
|
||||
|
||||
== 18. Lizenz der Lizenz
|
||||
|
||||
Dieser Lizenztext ist lizenziert unter einer
|
||||
„link:http://creativecommons.org/licenses/by/4.0/[Creative Commons
|
||||
Namensnennung 4.0 International Lizenz]“ (CC-BY 4.0).
|
||||
|
||||
Sie dürfen diesen Lizenztext für sich kopieren und anpassen, solange Sie
|
||||
dabei die Deutsche Bahn Marke und „DB“ nur innerhalb der DB benutzen.
|
||||
Falls Sie das Material für die Verwendung außerhalb der DB anpassen, so
|
||||
müssen Sie alle Nennungen der Deutschen Bahn und DB ersetzen bzw.
|
||||
entfernen. Geänderte Versionen des Lizenztextes müssen klar als
|
||||
geänderte Versionen kenntlich gemacht werden.
|
||||
|
||||
Teile des Textes dieser Lizenz basieren auf der EU Public License (EUPL)
|
||||
v1.2.
|
||||
@@ -0,0 +1,16 @@
|
||||
---
|
||||
# Docs: https://git.tech.rz.db.de/db-inner-source/scm-info-json-schema
|
||||
version: v3
|
||||
license: LicenseRef-DBISL
|
||||
contacts:
|
||||
- {CONTACT_EMAIL}
|
||||
confidentiality: internal
|
||||
reference-ids:
|
||||
- none
|
||||
protected-branches: main
|
||||
custom:
|
||||
production-branch: main
|
||||
integrity: normal
|
||||
availability: normal
|
||||
confidentiality: normal
|
||||
it-service-id: unknown
|
||||
@@ -0,0 +1,227 @@
|
||||
# Testing Standards
|
||||
|
||||
## Coverage
|
||||
|
||||
- **Minimum: 80% Line Coverage** – kein Merge unter 80%
|
||||
- Neue Features: 90%+ Coverage anstreben
|
||||
- Kritische Pfade (Auth, Payment, Data): 95%+
|
||||
|
||||
## Testarten
|
||||
|
||||
| Art | Scope | Framework |
|
||||
|-----|-------|-----------|
|
||||
| Unit | Einzelne Klasse/Funktion | JUnit/pytest/go test/Vitest |
|
||||
| Integration | Mehrere Komponenten | @SpringBootTest/TestClient |
|
||||
| E2E | Ganzer Flow | Playwright/RestAssured |
|
||||
|
||||
## Teststruktur: Gherkin/Given-When-Then
|
||||
|
||||
Alle Testfälle in Given-When-Then Struktur schreiben:
|
||||
|
||||
```java
|
||||
@Test
|
||||
void shouldReturnUserWhenValidIdProvided() {
|
||||
// Given
|
||||
var userId = UUID.randomUUID();
|
||||
var expectedUser = new User(userId, "Max Mustermann");
|
||||
when(userRepository.findById(userId)).thenReturn(Optional.of(expectedUser));
|
||||
|
||||
// When
|
||||
var result = userService.findById(userId);
|
||||
|
||||
// Then
|
||||
assertThat(result).isPresent();
|
||||
assertThat(result.get().getName()).isEqualTo("Max Mustermann");
|
||||
}
|
||||
```
|
||||
|
||||
```python
|
||||
def test_should_return_user_when_valid_id():
|
||||
# Given
|
||||
user_id = uuid4()
|
||||
mock_repo.find_by_id.return_value = User(id=user_id, name="Max")
|
||||
|
||||
# When
|
||||
result = user_service.find_by_id(user_id)
|
||||
|
||||
# Then
|
||||
assert result is not None
|
||||
assert result.name == "Max"
|
||||
```
|
||||
|
||||
## Was testen
|
||||
|
||||
- Happy Path (Normalfall)
|
||||
- Edge Cases (leere Listen, None/null, Grenzwerte)
|
||||
- Error Cases (ungültige Eingaben, Exceptions)
|
||||
- Security (unautorisierter Zugriff, SQL Injection Inputs)
|
||||
|
||||
## Was NICHT testen
|
||||
|
||||
- Getter/Setter ohne Logik
|
||||
- Framework-Code (Spring Boot Auto-Config)
|
||||
- Third-Party Libraries
|
||||
|
||||
## E2E-Tests mit Playwright (nach Deploy auf Preview)
|
||||
|
||||
Wenn das Projekt eine Webapp ist und auf der Preview-Umgebung deployed wurde:
|
||||
|
||||
### Preview-URL
|
||||
|
||||
```
|
||||
https://{app-name}-{namespace}.${ART_NAME}-iat.cnp-test.comp.db.de
|
||||
```
|
||||
|
||||
### E2E-Tests durchführen
|
||||
|
||||
Nutze den Playwright MCP Server (ist im Pod verfügbar):
|
||||
|
||||
1. Zur Preview-URL navigieren
|
||||
2. Seite laden, prüfen ob Grundfunktionen da sind
|
||||
3. Formulare ausfüllen, Buttons klicken
|
||||
4. Responses/Ergebnisse prüfen
|
||||
5. Screenshots als Evidenz
|
||||
|
||||
### Beispiel-Prüfungen
|
||||
|
||||
- Startseite lädt ohne Fehler
|
||||
- CRUD-Operationen funktionieren (Erstellen, Lesen, Bearbeiten, Löschen)
|
||||
- Validierung greift (leere Felder, ungültige Eingaben)
|
||||
- API-Endpoints antworten korrekt (JSON-Response prüfen)
|
||||
|
||||
### Screenshots im MR
|
||||
|
||||
Relevante Screenshots als Kommentar am MR anhängen oder in der MR-Description referenzieren.
|
||||
|
||||
### Akzeptanzkriterien in Gherkin
|
||||
|
||||
Testfälle als Gherkin-Szenarien. Wenn in der Aufgabe bereits Gherkin-Szenarien formuliert sind → direkt übernehmen. Sonst selbst aus der Anforderung ableiten.
|
||||
|
||||
```gherkin
|
||||
Feature: Adressverwaltung
|
||||
|
||||
Scenario: Neue Adresse anlegen
|
||||
Given ich bin auf der Startseite
|
||||
When ich auf "Neue Adresse" klicke
|
||||
And ich das Formular ausfülle:
|
||||
| Feld | Wert |
|
||||
| Name | Max Mustermann |
|
||||
| Straße | Musterstr. 1 |
|
||||
| Stadt | Berlin |
|
||||
| PLZ | 10115 |
|
||||
| Land | Deutschland |
|
||||
And ich auf "Speichern" klicke
|
||||
Then sehe ich "Max Mustermann" in der Adressliste
|
||||
|
||||
Scenario: Validierung bei leerem Namen
|
||||
Given ich bin auf der Startseite
|
||||
When ich auf "Neue Adresse" klicke
|
||||
And ich das Formular ohne Name absende
|
||||
Then sehe ich eine Fehlermeldung
|
||||
|
||||
Scenario: Adresse löschen
|
||||
Given es existiert eine Adresse "Max Mustermann"
|
||||
When ich auf "Löschen" klicke
|
||||
Then ist "Max Mustermann" nicht mehr in der Liste
|
||||
```
|
||||
|
||||
### Ablauf
|
||||
|
||||
1. Gherkin-Szenarien aus der Aufgabe ableiten
|
||||
2. In GitLab Issue als Akzeptanzkriterien dokumentieren
|
||||
3. Nach Deploy: Szenarien mit Playwright gegen Preview-URL ausführen
|
||||
4. Jedes Szenario = ein Playwright-Test (navigieren, klicken, prüfen)
|
||||
5. Bei Fehler: Screenshot + Beschreibung als MR-Kommentar
|
||||
|
||||
## Load-Testing mit hey
|
||||
|
||||
Nach erfolgreichem E2E-Test: Einfachen Last-Test gegen die Preview-URL fahren.
|
||||
|
||||
### Wann Load-Testing
|
||||
|
||||
- Bei REST APIs mit erwarteter Last
|
||||
- Bei Endpoints die Datenbank-Zugriffe machen
|
||||
- Nicht bei reinen Doku-Projekten oder Libraries
|
||||
|
||||
### Verwendung
|
||||
|
||||
```bash
|
||||
# Einfacher GET-Test: 200 Requests, 10 parallel
|
||||
hey -n 200 -c 10 http://preview-url/api/addresses
|
||||
|
||||
# POST mit Body und Auth
|
||||
hey -n 100 -c 5 \
|
||||
-m POST \
|
||||
-H "Content-Type: application/json" \
|
||||
-H "Authorization: Bearer $TOKEN" \
|
||||
-d '{"name":"Load Test","street":"Teststr. 1","city":"Berlin","zip":"10115","country":"DE"}' \
|
||||
http://preview-url/api/addresses
|
||||
|
||||
# PUT (Update)
|
||||
hey -n 100 -c 5 \
|
||||
-m PUT \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{"name":"Updated"}' \
|
||||
http://preview-url/api/addresses/1
|
||||
```
|
||||
|
||||
### Auswertung
|
||||
|
||||
hey gibt aus:
|
||||
- Response-Zeiten (avg, p50, p95, p99)
|
||||
- Throughput (Requests/sec)
|
||||
- Status-Code-Verteilung
|
||||
- Fehlerrate
|
||||
|
||||
### Akzeptanzkriterien (Richtwerte)
|
||||
|
||||
- p95 Response-Zeit < 500ms
|
||||
- Fehlerrate < 1%
|
||||
- Keine 5xx Errors unter Last
|
||||
|
||||
### Ergebnis dokumentieren
|
||||
|
||||
Load-Test-Ergebnisse als Kommentar am MR oder in Session-Notes festhalten.
|
||||
Wenn Ergebnisse schlecht: Performance-Issue anlegen.
|
||||
|
||||
## Integration Tests mit Testcontainers
|
||||
|
||||
Für Integration Tests mit echten Datenbanken/Services: [testcontainers.org](https://testcontainers.org)
|
||||
|
||||
### Verwendung
|
||||
|
||||
```java
|
||||
@SpringBootTest
|
||||
@Testcontainers
|
||||
class UserRepositoryIT {
|
||||
|
||||
@Container
|
||||
static PostgreSQLContainer<?> postgres = new PostgreSQLContainer<>("postgres:16-alpine");
|
||||
|
||||
@DynamicPropertySource
|
||||
static void configureProperties(DynamicPropertyRegistry registry) {
|
||||
registry.add("spring.datasource.url", postgres::getJdbcUrl);
|
||||
registry.add("spring.datasource.username", postgres::getUsername);
|
||||
registry.add("spring.datasource.password", postgres::getPassword);
|
||||
}
|
||||
|
||||
@Test
|
||||
void shouldSaveAndFindUser() {
|
||||
// Given-When-Then
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Im Agent-Pod
|
||||
|
||||
- Podman ist im Base-Image installiert (Testcontainers-kompatibel)
|
||||
- Env-Variablen für Testcontainers mit Podman sind gesetzt:
|
||||
- `TESTCONTAINERS_RYUK_DISABLED=true`
|
||||
- `DOCKER_HOST=unix:///run/podman/podman.sock`
|
||||
|
||||
### Wann Testcontainers nutzen
|
||||
|
||||
- Repository-Tests mit echter DB (statt H2)
|
||||
- Kafka-Integration Tests
|
||||
- Tests gegen externe Services (Wiremock-Container)
|
||||
- NICHT für Unit-Tests (dort Mocks verwenden)
|
||||
@@ -0,0 +1,105 @@
|
||||
# Verfügbare CLI Tools
|
||||
|
||||
## Git & GitLab
|
||||
|
||||
| Tool | Verwendung |
|
||||
|------|-----------|
|
||||
| `git` | Clone, commit, push, branch, merge |
|
||||
| `glab` | MRs erstellen, Issues, Pipelines, Repos anlegen |
|
||||
|
||||
```bash
|
||||
# Repo anlegen
|
||||
glab repo create {name} --group ${ART_NAME}/playground --internal
|
||||
|
||||
# MR erstellen
|
||||
glab mr create --title "feat: ..." --description "..." --target-branch main
|
||||
|
||||
# Pipeline Status
|
||||
glab ci status
|
||||
```
|
||||
|
||||
## Kubernetes
|
||||
|
||||
| Tool | Verwendung |
|
||||
|------|-----------|
|
||||
| `kubectl` | Pods, Deployments, Services, Logs, Exec |
|
||||
| `helm` | Chart install/upgrade, Template, Values |
|
||||
| `argocd` | App sync, Status, Rollback, Diff |
|
||||
|
||||
```bash
|
||||
# Deployment Status
|
||||
kubectl get pods -n {namespace}
|
||||
kubectl logs -f deployment/{name} -n {namespace}
|
||||
|
||||
# Helm
|
||||
helm upgrade --install {release} ./chart -n {namespace} -f values.yaml
|
||||
|
||||
# ArgoCD
|
||||
argocd app sync {app-name}
|
||||
argocd app get {app-name}
|
||||
argocd app rollback {app-name}
|
||||
argocd app diff {app-name}
|
||||
```
|
||||
|
||||
## Build & Test
|
||||
|
||||
| Tool | Verwendung |
|
||||
|------|-----------|
|
||||
| `mvn` | Java Build, Test, Package |
|
||||
| `gradle` | Java/Kotlin Build |
|
||||
| `python` / `pip` / `uv` | Python Projekte |
|
||||
| `go` | Go Build, Test, Cross-Compile |
|
||||
| `node` / `npm` / `npx` | Frontend Build, Dependencies |
|
||||
| `make` | Makefiles ausführen |
|
||||
|
||||
## Container & Security
|
||||
|
||||
| Tool | Verwendung |
|
||||
|------|-----------|
|
||||
| `buildah` | Container Images bauen (rootless, kein Docker) |
|
||||
| `podman` | Container starten (Testcontainers) |
|
||||
| `trivy` | Vulnerability Scan (Images, Filesystem, Config) |
|
||||
| `gitleaks` | Secret Scanning vor Commits |
|
||||
|
||||
```bash
|
||||
# Image bauen und scannen
|
||||
buildah bud -t myapp:latest .
|
||||
trivy image myapp:latest --severity HIGH,CRITICAL --exit-code 1
|
||||
buildah push myapp:latest registry/myapp:latest
|
||||
|
||||
# Projekt auf Secrets prüfen
|
||||
gitleaks detect --source . --no-git
|
||||
|
||||
# Dependencies scannen
|
||||
trivy fs . --severity HIGH,CRITICAL
|
||||
```
|
||||
|
||||
## Linting & Formatting
|
||||
|
||||
| Tool | Stack | Verwendung |
|
||||
|------|-------|-----------|
|
||||
| `ruff` | Python | Linter + Formatter |
|
||||
| `golangci-lint` | Go | Meta-Linter |
|
||||
| `hadolint` | Docker | Dockerfile Best Practices |
|
||||
| `shellcheck` | Bash | Shell-Script Linter |
|
||||
| `yamllint` | YAML | K8s/Helm Manifeste |
|
||||
|
||||
```bash
|
||||
ruff check . && ruff format .
|
||||
golangci-lint run
|
||||
hadolint Dockerfile
|
||||
shellcheck scripts/*.sh
|
||||
yamllint .
|
||||
```
|
||||
|
||||
## Browser (via Playwright MCP)
|
||||
|
||||
| Tool | Verwendung |
|
||||
|------|-----------|
|
||||
| `browser_navigate` | URL öffnen |
|
||||
| `browser_snapshot` | Seite lesen (Accessibility Tree) |
|
||||
| `browser_click` | Elemente klicken |
|
||||
| `browser_type` | Text eingeben |
|
||||
| `browser_take_screenshot` | Screenshot erstellen |
|
||||
|
||||
Headless Edge Browser für UI-Tests und Web-Scraping.
|
||||
@@ -0,0 +1,152 @@
|
||||
# Workflow
|
||||
|
||||
## Ablauf bei bestehendem Repo
|
||||
|
||||
1. Repo klonen (`git clone $REPO_URL`)
|
||||
2. Feature-Branch erstellen (`git checkout -b $BRANCH`)
|
||||
3. Implementieren
|
||||
4. Tests schreiben und ausführen (80% Coverage)
|
||||
5. gitleaks ausführen
|
||||
6. Linting/Formatting anwenden
|
||||
7. Commit mit Conventional Commits Message
|
||||
8. Push auf Feature-Branch
|
||||
9. Merge Request erstellen mit `glab mr create`
|
||||
|
||||
## Ablauf wenn Repo nicht existiert (neues Projekt)
|
||||
|
||||
1. Repo in GitLab anlegen mit `glab`:
|
||||
```bash
|
||||
glab repo create {repo-name} --group {group} --internal --description "{beschreibung}"
|
||||
```
|
||||
- GitLab Host: https://git.tech.rz.db.de
|
||||
- Gruppe kommt aus REPO_URL oder aus der Aufgabe (z.B. "GitLab Group: ${ART_NAME}/playground")
|
||||
|
||||
2. Lokal initialisieren auf **main** Branch:
|
||||
```bash
|
||||
mkdir project && cd project
|
||||
git init
|
||||
git remote add origin https://git.tech.rz.db.de/{group}/{project}.git
|
||||
git checkout -b main
|
||||
```
|
||||
|
||||
3. **Pflichtdateien zuerst** (siehe project-setup.md):
|
||||
- README.md (mit Projektbeschreibung, Quickstart, Build/Test Anleitung)
|
||||
- LICENSE.adoc
|
||||
- scm-info.yaml
|
||||
- .gitignore
|
||||
- .gitlab-ci.yml
|
||||
|
||||
4. Implementieren, testen, linten
|
||||
|
||||
5. Erster Commit + Push auf **main**:
|
||||
```bash
|
||||
git add -A
|
||||
git commit -m "feat: initial project setup"
|
||||
git push -u origin main
|
||||
```
|
||||
|
||||
6. Falls Feature-Branch gewünscht ($BRANCH gesetzt und != main):
|
||||
```bash
|
||||
git checkout -b $BRANCH
|
||||
# weitere Implementierung
|
||||
git add -A
|
||||
git commit -m "feat: ..."
|
||||
git push -u origin $BRANCH
|
||||
glab mr create --fill --target-branch main
|
||||
```
|
||||
|
||||
## Git-Konfiguration
|
||||
|
||||
Die Git-Credentials sind bereits konfiguriert (über Env-Variablen im Pod).
|
||||
Nutze `git` und `glab` CLI direkt.
|
||||
|
||||
```bash
|
||||
# Repo anlegen
|
||||
glab repo create myproject --group ${ART_NAME}/playground --internal
|
||||
|
||||
# Push
|
||||
git push -u origin main
|
||||
|
||||
# MR erstellen
|
||||
glab mr create --fill --target-branch main
|
||||
```
|
||||
|
||||
## Wichtig
|
||||
|
||||
- Neue Repos: IMMER auf **main** Branch initial committen
|
||||
- IMMER README.md mit Beschreibung anlegen
|
||||
- IMMER pushen am Ende – Code der nur lokal liegt ist wertlos
|
||||
- IMMER Merge Request erstellen wenn auf Feature-Branch
|
||||
- Repo-URL und Branch kommen als Env-Variablen: $REPO_URL, $BRANCH
|
||||
- GitLab Host ist IMMER: https://git.tech.rz.db.de
|
||||
|
||||
## Projektnamen
|
||||
|
||||
- Saubere, sprechende Namen verwenden (z.B. `hello-spring-boot`, `user-service`)
|
||||
- KEINE Session-IDs, Job-IDs oder UUIDs im Projektnamen
|
||||
- KEINE Suffixe wie `-4b98bbd1` oder `-abc123`
|
||||
- Kebab-Case: `mein-projekt-name`
|
||||
- Wenn repo_url angegeben: Projektnamen daraus ableiten
|
||||
- Wenn nur gitlab_group angegeben: Projektnamen aus der Aufgabe ableiten
|
||||
|
||||
## Namenskorrektur
|
||||
|
||||
Falls die übergebene `repo_url` oder der Projektname eine Session-ID, Job-ID oder UUID enthält (z.B. `hello-spring-4b98bbd1`, `my-app-abc4a303`):
|
||||
- Den Suffix entfernen
|
||||
- Nur den sauberen Projektnamen verwenden
|
||||
- Beispiel: `hello-world-spring-boot-4b98bbd1` → `hello-world-spring-boot`
|
||||
|
||||
## Abschluss: Badges und Fertigmeldung
|
||||
|
||||
### GitLab Projekt-Badges anlegen
|
||||
|
||||
Erst prüfen ob Badges schon existieren, dann nur fehlende anlegen:
|
||||
|
||||
```bash
|
||||
# Bestehende Badges prüfen
|
||||
EXISTING=$(glab api "projects/:id/badges" | python3 -c "import sys,json; print([b["name"] for b in json.load(sys.stdin)])")
|
||||
|
||||
# Pipeline Badge (wenn nicht vorhanden)
|
||||
if ! echo "$EXISTING" | grep -q "Pipeline"; then
|
||||
glab api -X POST "projects/:id/badges" -f "link_url=https://git.tech.rz.db.de/%{project_path}/-/pipelines" -f "image_url=https://git.tech.rz.db.de/%{project_path}/badges/%{default_branch}/pipeline.svg" -f "name=Pipeline"
|
||||
fi
|
||||
|
||||
# Coverage Badge
|
||||
if ! echo "$EXISTING" | grep -q "Coverage"; then
|
||||
glab api -X POST "projects/:id/badges" -f "link_url=https://git.tech.rz.db.de/%{project_path}/-/pipelines" -f "image_url=https://git.tech.rz.db.de/%{project_path}/badges/%{default_branch}/coverage.svg" -f "name=Coverage"
|
||||
fi
|
||||
|
||||
# Web-Endpoint / Landing-Page Badge (wenn deployed)
|
||||
if ! echo "$EXISTING" | grep -q "App"; then
|
||||
glab api -X POST "projects/:id/badges" -f "link_url=https://{app-name}-{namespace}.${ART_NAME}-iat.cnp-test.comp.db.de" -f "image_url=https://img.shields.io/badge/App-live-green" -f "name=App"
|
||||
fi
|
||||
```
|
||||
|
||||
Regeln:
|
||||
- Keine doppelten Badges anlegen (erst prüfen)
|
||||
- Jeder Web-Endpoint/Landing-Page bekommt ein Badge mit der URL
|
||||
- Preview-Umgebung: Badge mit Preview-URL
|
||||
- Prod-Umgebung: Badge mit Prod-URL
|
||||
|
||||
### Fertigmeldung
|
||||
|
||||
Wenn alles abgeschlossen ist:
|
||||
```bash
|
||||
echo "PROGRESS: 100% - Fertig: MR erstellt, Pipeline grün, Badges gesetzt"
|
||||
```
|
||||
|
||||
## Aufgabe abschließen
|
||||
|
||||
Wenn alles fertig ist (MR gemerged, Main-Pipeline grün, Issues geschlossen):
|
||||
|
||||
```bash
|
||||
echo "PROGRESS: 100% - Aufgabe abgeschlossen: MR gemerged, Pipeline grün, Issues geschlossen"
|
||||
```
|
||||
|
||||
Erst PROGRESS 100% melden wenn:
|
||||
- [ ] Alle Issues geschlossen
|
||||
- [ ] MR gemerged
|
||||
- [ ] Main-Pipeline grün
|
||||
- [ ] Keine offenen Findings
|
||||
|
||||
Wenn Main-Pipeline failed → NICHT 100% melden, sondern fixen.
|
||||
Reference in New Issue
Block a user