Referenzmaterial

Session-Dokumentation: News-Aggregator — von der Planung bis Live

Vollständige Dokumentation der Claude Code Session vom 6. April 2026

Dieses Dokument wurde von Claude Code während der Implementierung des News-Aggregators erstellt. Es ist die vollständige technische Dokumentation einer einstündigen Session — Architektur, Implementierungsdetails, Bugfixes, Testergebnisse und Kostenkalkulation.

Der zugehörige Beitrag: Plan rein, Seite raus — ein News-Aggregator in einer Stunde

---

1. Ausgangslage

Ausgangspunkt war das Planungsdokument ops/NEWS-AGGREGATOR.md — eine Quellensammlung für einen internationalen News-Aggregator auf qzen.ch mit 35 RSS-Feeds aus 6 Regionen.

Zusammenfassung des Plans

• Konzept: Automatischer News-Aggregator, der internationale Tech/KI-Quellen sammelt, ins Deutsche übersetzt und auf qzen.ch darstellt
• Quellen (6 Regionen, 35 Feeds):
  • USA — MIT Tech Review, Ars Technica, TechCrunch, The Verge, Hacker News, Anthropic, OpenAI, 404 Media, Bloomberg
  • UK — Guardian, BBC, FT, The Register
  • Israel — CTech, Times of Israel, Haaretz, NoCamels, Jerusalem Post, Globes
  • Westeuropa — Heise, Golem, t3n, NZZ, Le Monde, Spiegel
  • Asien — SCMP, TechNode, Nikkei, Rest of World, The Diplomat, KrASIA
  • Forschung — Google AI, DeepMind, Hugging Face, arXiv

---

2. Feed-Validierung

Alle 35 Feed-URLs wurden verifiziert und in einer maschinenlesbaren JSON-Datei dokumentiert. Wesentliche Erkenntnisse:

• Korrigierte Feed-URLs bei mehreren Quellen
• Bloomberg und CTech nutzen Google News Proxies statt nativer RSS-Feeds
• Anthropic nutzt einen Community-gepflegten GitHub-Feed
• arXiv kombiniert cs.AI + cs.LG
• Paywall-Flags als Boolean direkt im JSON
• Format-Feld unterscheidet RSS vs. Atom

---

3. Development Plan — 4 Phasen

1. Kirby-Struktur — Blueprint article-news + collection-news, Templates, Controller, Collection-Seite /radar
2. Python Feed-Aggregator — RSS parsen, Relevanz-Filter (Haiku), Übersetzen (Haiku), Kirby-Seiten schreiben
3. Cronjob + Ops — Alle 4h, Logging, Retention 30 Tage, API-Key isoliert
4. Frontend — Region-Filter, Paywall-Badges, Quellen-Badge, Transparenzhinweis

Vorab-Entscheidungen

Frage	Entscheidung
URL-Pfad	/radar
Übersetzungs-API	Claude Haiku
Kuratierung	Vollautomatisch
Seitenstruktur	Flach mit Datum-Prefix im Slug
arXiv-Volumen	Keyword-Filter

---

4. Implementierung

Phase 1: Kirby-Struktur

Blueprint article-news.yml — Schlankes Template ohne Layout/Copilot:

• Felder: title, description (Writer), sourceurl, sourcename, sourceregion (Select: 6 Regionen), sourcelang, paywall (Toggle), date, tags, translated (Toggle)

Blueprint collection-news.yml — Erweitert das bestehende Collection-Blueprint:

• Kindseiten: nur article-news
• Panel-Tabelle: Datum, Quelle, Region statt Author

Collection-Seite /radar — Cards-Layout, Pagination 20, Tags-Filter aktiv, Datum anzeigen, Author verbergen

Template article-news.php — Einzelansicht:

• Quellen-Badge (Name + Region-Flagge) in der Meta-Spalte
• Paywall-Icon bei kostenpflichtigen Quellen
• CTA-Button: «Originalartikel lesen bei [Quelle] →»
• Transparenzhinweis bei übersetzten Artikeln
• Tags als klickbare Links zurück zur Collection

Template collection-news.php — Listenansicht:

• Region-Filter als Button-Leiste (USA | UK | Israel | Europa | Asien | Forschung)

Controller: Sortierung nach Datum absteigend, Region-Filter via URL-Parameter, $cover = null (kein Cover bei News)

Phase 2: Python-Aggregator

Verzeichnis: ops/aggregator/

config.py — Zentrale Konfiguration: Pfade, API-Key aus .env, Limits (MAX_ARTICLES_PER_RUN=15, RELEVANCE_THRESHOLD=6, RETENTION_DAYS=30)

feeds.py — RSS/Atom-Parser: Liest die Feed-Definitionen, fetcht alle 35 Feeds parallel (Timeout 15s), normalisiert Einträge, generiert URL-sichere Slugs, entfernt HTML-Tags aus Summaries, max 20 Einträge pro Feed

filter.py — Relevanz-Filter: Claude Haiku mit System-Prompt für die qzen.ch-Zielgruppe. Score 0–10, automatische Tag-Vergabe aus 15 vordefinierten Tags, Batch-Größe 15, max_tokens 4096. Fallback bei API-Fehler: Score 5

translate.py — Übersetzung: Claude Haiku, deutsche Quellen werden übersprungen, Fachbegriffe bleiben englisch. Fallback bei API-Fehler: Originaltext

kirby_writer.py — Generiert Kirby-Textdateien, erstellt Verzeichnisse unter content/radar/, nummeriert Ordner, setzt Dateiberechtigungen, prüft auf Duplikate

fetch.py — Orchestrierung:

1. Alle 35 Feeds abrufen (~620 Einträge)
2. Gegen state.json deduplizieren
3. Relevanz-Filter (~42 API-Calls, ~7 Min.)
4. Top 15 übersetzen (1 API-Call)
5. Kirby-Seiten schreiben
6. Cleanup: Einträge älter 30 Tage entfernen
7. state.json aktualisieren (max 5000 URLs)

Bugfixes während Implementierung

1. Batch-Größe 40→15: Bei 40 Artikeln pro Batch wurde die JSON-Antwort bei max_tokens=2048 abgeschnitten. Fix: Batch-Größe auf 15, max_tokens auf 4096.

2. Sonnet-Modell nicht verfügbar: Der API-Key erlaubt nur Haiku. Fix: Haiku für Filter und Übersetzung.

3. $cover-Variable fehlt: Das Layout-Snippet erwartet $cover für og:image. Fix: $cover = null im Controller.

4. Debug-Setting überschrieben: Host-spezifische Config überschrieb die globale. Fix: in beiden Dateien aktiviert.

Phase 3: Cronjob + Ops

• Cronjob alle 4 Stunden
• Log-Rotation: weekly, 4 Rotationen, komprimiert
• API-Key aus der Server-Konfiguration in eine lokale .env-Datei übertragen, chmod 600

---

5. Testergebnisse

Erster Lauf (roher Import, ohne KI)

• 620 Einträge aus 34/35 Feeds (Times of Israel: 403)
• 5 Testeinträge geschrieben, Frontend erreichbar

Zweiter Lauf (Filter, falsche Batch-Größe)

• Alle Filter-Batches fehlgeschlagen (JSON abgeschnitten)
• Fallback: alle Einträge mit Score 5 durchgelassen

Dritter Lauf (Filter funktioniert, Sonnet-Fehler)

• Übersetzung fehlgeschlagen: Sonnet-Modell 404
• 15 Artikel geschrieben, Titel auf Englisch

Vierter Lauf (finale Version)

• Filter und Übersetzung korrekt
• 15 Artikel mit deutschen Titeln und Tags
• Frontend-Rendering verifiziert

Beispiel-Ausgabe

• [Hacker News] Wenn Viralität die Botschaft ist: Das neue Zeitalter der AI-Propaganda
• [TechCrunch] So nutzt man die neuen ChatGPT-App-Integrationen
• [Nikkei Asia] Foxconn und Mitsubishi Fuso kooperieren beim Export von Elektrobussen
• [404 Media] Floridas Naturschutzpolizei durchsucht tausende Flock-Kameras für ICE
• [Globes] Quantum-Computing-Firma Q-Factor sammelt $24 Millionen ein
• [TechCrunch] OpenAIs Vision für die AI-Wirtschaft
• [The Verge] Iran droht OpenAIs Stargate-Rechenzentrum in Abu Dhabi
• [Spiegel] Copilot: Microsoft-KI dient ausschließlich Unterhaltungszwecken
• [CTech] NFX startet Investitionsprogramm für israelische Startups in Kriegszeiten

---

6. Erstellte Dateien

Kirby-Struktur

• site/blueprints/pages/article-news.yml — Blueprint für News-Einträge
• site/blueprints/pages/collection-news.yml — Blueprint für News-Collection
• site/templates/article-news.php — Template Einzelartikel
• site/templates/collection-news.php — Template Listenansicht
• site/controllers/article-news.php — Controller Einzelartikel
• site/controllers/collection-news.php — Controller Listenansicht
• site/snippets/article-news-meta.php — Quellen-Badge Snippet
• content/radar/collection-news.de.txt — Collection-Seite

Python-Aggregator

• ops/aggregator/config.py — Konfiguration
• ops/aggregator/feeds.py — RSS/Atom-Parser
• ops/aggregator/filter.py — Relevanz-Filter (Claude Haiku)
• ops/aggregator/translate.py — Übersetzung (Claude Haiku)
• ops/aggregator/kirby_writer.py — Kirby-Seiten schreiben
• ops/aggregator/fetch.py — Orchestrierung
• ops/aggregator/requirements.txt — Python-Dependencies

---

7. Kosten und Performance

Metrik	Wert
Feeds pro Lauf	35 (34 erreichbar)
Einträge pro Lauf	~620
API-Calls Filter	~42 (15er Batches)
API-Calls Übersetzung	1 (15 Artikel)
Laufzeit gesamt	~8–10 Minuten
Kosten pro Lauf	~$0.05–0.10 (Haiku)
Kosten pro Tag (6 Läufe)	~$0.30–0.60
Neue Artikel pro Lauf	Max. 15
Retention	30 Tage

---

8. Bekannte Einschränkungen

1. Times of Israel RSS-Feed blockiert mit 403
2. API-Key erlaubt nur Haiku — bei Upgrade auf Sonnet umstellbar
3. Hacker News Einträge verlinken oft auf Drittseiten — Quellenname kann irreführend sein
4. Keine Cover-Bilder (bewußte Entscheidung)
5. Nur deutsche Content-Dateien, keine englische Version der Radar-Seite

---

Dieses Dokument wurde von Claude Code während der Implementierung erstellt und für die Veröffentlichung redaktionell überarbeitet.