Agentisches Programmieren mit KI-Assistenten

curl -fsSL https://claude.ai/install.sh | bash

claude --version

brew install --cask claude-code
claude --version

# Falls Node.js fehlt
brew install node

# Claude Code installieren
npm install -g @anthropic-ai/claude-code

# Bei "command not found":
echo 'export PATH="$(npm config get prefix)/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

claude --version

curl -fsSL https://claude.ai/install.sh | bash

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

brew install --cask claude-code

# npm-Verzeichnis ohne sudo einrichten
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc

# Installation
npm install -g @anthropic-ai/claude-code
claude --version

irm https://claude.ai/install.ps1 | iex
claude --version

curl -fsSL https://claude.ai/install.cmd -o install.cmd && install.cmd && del install.cmd

curl -fsSL https://claude.ai/install.sh | bash

mkdir -p mein-projekt/specs
cd mein-projekt

= Story: [Projektname]
:revdate: 2026-03-19

== Vision

[2-3 Sätze: Was soll das System leisten? Welches Problem löst es?]

== Grobe Anforderungen

* [Anforderung 1]
* [Anforderung 2]
* [Anforderung 3]

== Technische Rahmenbedingungen

[cols="1,2"]
|===
| Aspekt | Vorgabe

| Sprache
| Java 21

| Build-Tool
| Maven / Gradle

| Framework
| Spring Boot 3.x / Quarkus / ...

| Datenbank
| PostgreSQL / MongoDB / ...

| Architektur
| Hexagonale Architektur / Clean Architecture / ...

| Design Patterns
| Repository, Factory, Strategy, ...

| Dokumentation
| AsciiDoc (.adoc)

| Tests
| JUnit 5, AssertJ, Testcontainers
|===

== Offene Fragen

* [Was ist noch unklar?]
* [Welche Entscheidungen stehen aus?]

== Nicht-Ziele (Out of Scope)

* [Was gehört explizit NICHT zum Projekt?]

= Story: Online-Bestellsystem

== Vision

Ein Bestellsystem für einen mittelständischen Händler, das Kunden
ermöglicht, Produkte online zu bestellen und den Bestellstatus
zu verfolgen.

== Grobe Anforderungen

* Kunden können Produkte in einen Warenkorb legen
* Bestellungen werden mit Zahlungsart erfasst
* Sachbearbeiter können Bestellungen einsehen und bearbeiten
* E-Mail-Benachrichtigung bei Statusänderungen

== Technische Rahmenbedingungen

[cols="1,2"]
|===
| Aspekt | Vorgabe

| Sprache | Java 21
| Build-Tool | Gradle (Kotlin DSL)
| Framework | Spring Boot 3.3
| Datenbank | PostgreSQL 16
| Architektur | Hexagonale Architektur
| API | REST mit OpenAPI 3.0
| Dokumentation | AsciiDoc
| Tests | JUnit 5, AssertJ, Testcontainers
|===

== Offene Fragen

* Wie soll die Zahlungsabwicklung erfolgen?
* Gibt es ein bestehendes Kundensystem zur Integration?

== Nicht-Ziele

* Mobile App (nur Web)
* Internationalisierung (nur DACH-Region)

Lies bitte specs/story.adoc und analysiere die Anforderungen.

Stelle mir gezielte Fragen, um:
1. Die fachlichen Anforderungen vollständig zu verstehen
2. Alle Unklarheiten zu beseitigen
3. Die technischen Entscheidungen zu validieren

Formatiere deine Fragen strukturiert nach Kategorien.
Frage NICHT nach Code oder Implementierungsdetails –
das kommt später.

= Functional Specification: [Projektname]
:author: Fachbereich
:revdate: 2026-03-19
:toc: left
:sectnums:

== Einleitung

=== Zweck
[Geschäftlicher Kontext]

=== Scope
[Was ist enthalten, was nicht]

== Glossar

[cols="1,3"]
|===
| Begriff | Definition

| Bestellung
| Ein Auftrag eines Kunden über ein oder mehrere Produkte...

| Bestellposition
| Einzelne Zeile einer Bestellung mit Produkt, Menge, Preis
|===

== Akteure / Rollen

=== Kunde
* Kann Produkte suchen und bestellen
* Kann eigene Bestellungen einsehen

=== Sachbearbeiter
* Kann alle Bestellungen einsehen
* Kann Bestellstatus ändern

== Epics und User Stories

=== Epic: Bestellprozess

==== US-001: Bestellung aufgeben

[horizontal]
Story:: Als *Kunde* möchte ich *meinen Warenkorb bestellen können*,
        damit *ich die gewünschten Produkte erhalte*.
Priorität:: Hoch
Story Points:: 8
Sprint:: 1

===== Akzeptanzkriterien

[source,gherkin]
....
Given ich bin eingeloggt
  And mein Warenkorb enthält mindestens einen Artikel
When ich auf "Bestellen" klicke
  And ich eine Lieferadresse auswähle
  And ich eine Zahlungsart auswähle
  And ich die Bestellung bestätige
Then wird eine Bestellung mit Status "offen" erzeugt
  And ich erhalte eine Bestätigungs-E-Mail
  And mein Warenkorb ist geleert
....

===== Geschäftsregeln
* <<BR-001>>: Mindestbestellwert 10 EUR
* <<BR-003>>: Maximal 99 Stück pro Position

===== Tasks
* [ ] REST-Endpoint POST /api/bestellungen
* [ ] BestellungService implementieren
* [ ] E-Mail-Versand (async)
* [ ] Unit Tests
* [ ] Integration Tests

==== US-002: Bestellstatus einsehen

[horizontal]
Story:: Als *Kunde* möchte ich *den Status meiner Bestellungen sehen*,
        damit *ich weiß, wann meine Lieferung ankommt*.
Priorität:: Mittel
Story Points:: 3
Sprint:: 1

===== Akzeptanzkriterien

[source,gherkin]
....
Given ich bin eingeloggt
  And ich habe mindestens eine Bestellung
When ich meine Bestellübersicht öffne
Then sehe ich alle meine Bestellungen mit aktuellem Status
  And die Bestellungen sind nach Datum sortiert (neueste zuerst)
....

=== Epic: Bestellverwaltung

==== US-010: Bestellung stornieren

[horizontal]
Story:: Als *Sachbearbeiter* möchte ich *eine Bestellung stornieren können*,
        damit *ich auf Kundenwünsche reagieren kann*.
Priorität:: Mittel
Story Points:: 5
Sprint:: 2

// Weitere User Stories...

== Geschäftsregeln

[[BR-001]]
=== BR-001: Mindestbestellwert
Der Mindestbestellwert beträgt 10,00 EUR.

[[BR-003]]
=== BR-003: Maximale Artikelmenge
Pro Position können maximal 99 Stück bestellt werden.

== Fachliches Datenmodell

[plantuml]
....
@startuml
entity Bestellung {
  nummer: Bestellnummer
  datum: Datum
  status: Bestellstatus
  gesamtbetrag: Geldbetrag
}

entity Bestellposition {
  menge: Anzahl
  einzelpreis: Geldbetrag
}

entity Kunde {
  kundennummer: Kundennummer
  name: Personenname
}

Kunde ||--|{ Bestellung
Bestellung ||--|{ Bestellposition
@enduml
....

== Sprint-Planung

=== Sprint 1
* US-001: Bestellung aufgeben (8 SP)
* US-002: Bestellstatus einsehen (3 SP)
* Velocity: 11 SP

=== Sprint 2
* US-010: Bestellung stornieren (5 SP)
* ...

= Technische Spezifikation: [Projektname]
:revdate: 2026-03-19

== Fachliche Spezifikation

IMPORTANT: Die fachlichen Anforderungen sind in `specs/fsd.adoc` definiert.
Diese Datei ist die Single Source of Truth für das WAS.

== Technologie-Stack

[cols="1,2"]
|===
| Komponente | Version/Details

| Java | 25 (LTS)
| Build | Maven 3.9.x
| Framework | Quarkus 3.x
| Datenbank | PostgreSQL 18
| ORM | Hibernate ORM mit Panache
| Migration | Flyway
| API-Docs | SmallRye OpenAPI
| JSON | Jackson
|===

== Architektur

=== Layer-Architektur

....
src/main/java/at/htl/projekt/
├── entity/                # JPA Entities
│   ├── Bestellung.java
│   └── Bestellposition.java
├── repository/            # Data Access (Panache)
│   └── BestellungRepository.java
├── service/               # Business Logic
│   └── BestellungService.java
├── boundary/              # REST Resources
│   └── BestellungResource.java
└── dto/                   # Data Transfer Objects
    ├── BestellungDTO.java
    └── CreateBestellungDTO.java
....

=== Schichten-Regeln

[IMPORTANT]
====
* `boundary/` → ruft `service/` auf
* `service/` → ruft `repository/` auf, enthält Geschäftslogik
* `repository/` → Datenzugriff via Panache
* `entity/` → JPA-Entities mit Validierung
* `dto/` → Für REST-Schnittstellen, keine Entities nach außen
====

== Coding-Konventionen

=== Allgemein
* Package-Prefix: `at.htl.projekt`
* Keine Wildcards in Imports
* Records für DTOs
* Optional statt null-Returns

=== Naming
* Klassen: PascalCase
* Methoden/Variablen: camelCase
* Konstanten: SCREAMING_SNAKE_CASE
* Packages: lowercase
* REST-Resources: `*Resource.java`
* Services: `*Service.java`
* Repositories: `*Repository.java`

=== Quarkus-spezifisch
* CDI für Dependency Injection (`@Inject`, `@ApplicationScoped`)
* Panache Active Record oder Repository Pattern
* `@Transactional` auf Service-Methoden
* `application.properties` für Konfiguration

== Mapping: FSD → Code

[cols="1,2,2"]
|===
| FSD-Element | Code-Artefakt | Beispiel

| Glossar-Begriff
| Entity in `entity/`
| `Bestellung.java`

| User Story
| Service-Methode + REST-Endpoint
| `BestellungService.aufgeben()`

| Geschäftsregel
| Validierung in Entity oder Service
| `Bestellung.validiereMindestwert()`

| Akteur
| Security Role
| `@RolesAllowed("kunde")`
|===

== Test-Strategie

[cols="1,2,2"]
|===
| Ebene | Scope | Technologie

| Unit Tests
| Services, Entities
| JUnit 5, AssertJ, Mockito

| Integration Tests
| Repository, REST
| @QuarkusTest, Testcontainers

| API Tests
| REST-Endpoints
| REST Assured

| Acceptance Tests
| User Stories End-to-End
| Cucumber (optional)
|===

== Workflow für Claude Code

=== Bei neuen User Stories

1. `specs/fsd.adoc` konsultieren
2. Relevante User Story identifizieren
3. Entity erstellen/erweitern (falls nötig)
4. Repository erstellen/erweitern
5. Service-Methode implementieren
6. REST-Resource implementieren
7. Tests auf allen Ebenen

=== Regeln

* Bei Unklarheiten: *nachfragen*, nicht raten
* Fachbegriffe exakt aus Glossar übernehmen
* Keine Änderungen an der Fachlichkeit ohne Rücksprache
* Commits nach jeder logischen Einheit

== Prompts für häufige Aufgaben

=== Neue User Story implementieren

[source]
....
Implementiere US-XXX aus specs/fsd.adoc.
Erstelle Entity, Repository, Service und Resource.
Schreibe Tests für jede Schicht.
....

=== Code Review anfordern

[source]
....
Prüfe [Datei/Package] auf:
- Einhaltung der Schichten-Architektur
- Clean Code und SOLID
- Vollständigkeit der Tests
- Übereinstimmung mit fsd.adoc
....

Lies agents.adoc und specs/fsd.adoc.
Erstelle die Grundstruktur des Projekts gemäß der
definierten Package-Struktur.

/plan Implementiere US-001 (Bestellung aufgeben) aus specs/fsd.adoc.
Befolge die Architekturprinzipien aus agents.adoc.
Beginne mit der Entity und arbeite dich nach außen vor.

/plan Erstelle Tests für US-001 basierend auf den Akzeptanzkriterien
in specs/fsd.adoc. Jedes Given/When/Then soll ein Testfall sein.

# Beim Start
claude --plan "Implementiere US-001"

# Oder interaktiv
/plan Implementiere US-001 aus specs/fsd.adoc

= Chat-Protokoll: [Projektname]

== Session 1

Lies specs/story.adoc und stelle mir Fragen zur Klärung
der fachlichen Anforderungen.

'''

Ja, es gibt drei Rollen: Kunde, Sachbearbeiter, Admin

'''

Ja, verwende das Builder Pattern für die Bestellung-Entity

'''

Nein, kein Event Sourcing – klassisches CRUD reicht

'''

Erstelle basierend auf unserer Diskussion eine vollständige
fachliche Spezifikation als specs/fsd.adoc.

== Session 2

Implementiere US-001 aus specs/fsd.adoc.
Erstelle Entity, Repository, Service und Resource.
Schreibe Tests für jede Schicht.

'''

Nein, die Validierung soll im Service erfolgen, nicht in der Entity.