Vibe Coding Tipps und Tricks für Astro und GitHub Pages mit OpenCode

Vibe Coding Tipps gibt es viele. Die meisten enden beim ersten Prompt. Spannend wird es danach. Die Seite soll live gehen, der Agent fasst Dateien an, die er nicht anfassen soll, und auf GitHub Pages laufen plötzlich alle Links ins Leere. Wir bauen Landingpages und kleine Tools mit Astro, OpenCode und GitHub Pages. Hier stehen die Tipps und Tricks, die uns im Alltag wirklich Zeit sparen, von der ersten Zeile bis zum Deploy.

Warum Astro und GitHub Pages so gut zu Vibe Coding passen

Astro baut statische Seiten. Das Ergebnis ist ein Ordner mit HTML, CSS und Bildern. Genau so etwas kann GitHub Pages kostenlos ausliefern. Für Vibe Coding ist das ideal. Der Agent arbeitet in einem kleinen, klaren Projekt. Jeder Fehler zeigt sich spätestens im Build. Und eine Landingpage enthält nur öffentliche Inhalte, also ist das Risiko gering.

OpenCode ist der Coding Agent, mit dem wir das täglich machen. Er läuft im Terminal, ist Open Source und arbeitet mit vielen Modellanbietern. Wir nutzen Open Weight Modelle wie GLM oder Qwen über Ollama Cloud oder Z.AI. Welche Modelle sich für welche Aufgabe eignen, vergleichen wir bei den Vibe Coding Modellen.

Tipp 1 Mit einem Astro Template starten

Lasst den Agent nicht bei null anfangen. Ein leeres Projekt lädt zu wilden Strukturen ein. Ein Template gibt Ordner, Layouts und Konventionen vor, an die sich das Modell hält. Das empfiehlt auch die Astro Doku. Für GitHub Pages gibt es sogar ein offizielles Minimal Template mit fertigem Workflow.

npm create astro@latest -- --template github-pages

Integrationen kommen danach immer über npx astro add ins Projekt, zum Beispiel für Tailwind oder Sitemap. Dann passt Astro die Config selbst an. Lässt der Agent die package.json und die Config von Hand ändern, geht das öfter schief.

Tipp 2 Eine AGENTS.md mit init anlegen und schärfen

Startet OpenCode im Projektordner und tippt /init. OpenCode liest das Projekt und schreibt eine AGENTS.md mit Befehlen, Struktur und Eigenheiten. Diese Datei landet in jeder Session im Kontext. Committet sie ins Repository, dann arbeitet das ganze Team mit denselben Regeln.

Der automatische Entwurf ist ein Anfang. Die wichtigen Regeln für Astro und GitHub Pages ergänzt ihr selbst. So sieht das bei uns aus:

# Astro Landingpage

## Befehle
- npm run dev startet den Dev Server
- npm run build baut die Seite nach dist/
- npx astro check prüft Typen und Templates

## Regeln
- Integrationen nur mit npx astro add installieren
- Texte liegen in src/content, nie direkt im Layout
- Interne Links immer mit dem base Pfad bauen
- Nach jeder Änderung muss npm run build grün sein

Persönliche Regeln, etwa zur Sprache oder zum Ton, gehören in die globale Datei unter ~/.config/opencode/AGENTS.md. Die ist nur für euch und nicht für das Team. Wer schon eine CLAUDE.md im Projekt hat, muss nichts umbauen. OpenCode liest sie als Fallback, solange keine AGENTS.md existiert.

Tipp 3 Die Astro Doku als MCP Server einbinden

Modelle kennen Astro gut, aber nicht immer den aktuellen Stand. Gerade bei Content Collections, Actions oder Sessions schlagen sie gern alte APIs vor. Astro betreibt dafür einen kostenlosen MCP Server mit der aktuellen Doku. In OpenCode reicht ein Eintrag in der opencode.json im Projekt:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "Astro docs": {
      "type": "remote",
      "url": "https://mcp.docs.astro.build/mcp",
      "enabled": true
    }
  }
}

Ergänzt dann in der AGENTS.md eine Zeile wie „Bei Fragen zu Astro APIs zuerst die Astro Docs prüfen“. So nutzt der Agent den Server auch wirklich. Alle Details stehen in der Anleitung Building Astro sites with AI tools.

Tipp 4 Erst planen und dann bauen lassen

OpenCode hat zwei Modi. Mit der Tab Taste wechselt ihr in den Plan Modus. Dort darf der Agent nichts ändern und beschreibt nur, wie er vorgehen würde. Erst wenn der Plan passt, wechselt ihr mit Tab zurück in den Build Modus.

• Plan für alles, was mehr als eine Datei betrifft: neue Seiten, neue Komponenten, Umbau der Navigation.
• Direkt bauen für kleine Fixes: ein Tippfehler, eine Farbe, ein Abstand.
• Dateien gezielt nennen: Mit @ sucht ihr Dateien im Projekt und hängt sie an den Prompt.
• Bilder mitgeben: Screenshots oder Entwürfe zieht ihr per Drag and Drop ins Terminal.
• Zurückrollen ohne Git Stress: /undo macht die letzte Änderung rückgängig, /redo holt sie zurück.

Tipp 5 Rechte für den Agent begrenzen

Ohne eigene Einstellungen darf OpenCode fast alles. Für Vibe Coding im eigenen Repository solltet ihr das enger fassen. Die permission Einstellung in der opencode.json kennt drei Werte: allow, ask und deny. Die letzte passende Regel gewinnt, also kommt die allgemeine Regel zuerst.

{
  "$schema": "https://opencode.ai/config.json",
  "permission": {
    "bash": {
      "*": "ask",
      "npm run *": "allow",
      "npx astro *": "allow",
      "git status*": "allow",
      "git diff*": "allow",
      "git push *": "deny",
      "rm *": "deny"
    }
  }
}

Build und Checks laufen damit ohne Rückfrage. Alles andere fragt nach, Push und Löschen sind gesperrt. Den Push macht ihr selbst, nachdem ihr den Diff gesehen habt. Gut zu wissen: .env Dateien darf OpenCode standardmäßig nicht lesen. Alle Optionen erklärt die OpenCode Doku zu Permissions. Tiefer geht unsere Anleitung OpenCode Permissions richtig einstellen.

Tipp 6 Inhalte und Layout in Astro trennen

Legt alle Texte in Markdown unter src/content ab. Das Layout besteht aus Komponenten, die diese Inhalte darstellen. Dann kann der Agent Texte ändern, ohne das Layout zu zerlegen. Und ihr könnt Texte pflegen, ohne den Agent zu fragen. Wie das bei einer echten Marke aussieht, zeigt unser Beitrag zur Landingpage mit Astro und Vibe Coding.

Tipp 7 site und base für GitHub Pages richtig setzen

Das ist der häufigste Fehler bei Astro auf GitHub Pages. Lokal läuft alles, live fehlen CSS und Bilder, und jeder Link führt auf eine 404. Der Grund: Ohne eigene Domain liegt eure Seite unter https://name.github.io/repo-name/. Astro muss das wissen.

import { defineConfig } from 'astro/config'

export default defineConfig({
  site: 'https://name.github.io',
  base: '/repo-name',
})

Mit gesetztem base brauchen alle internen Links diesen Pfad als Präfix. Genau hier bauen Agents gern Fehler ein, weil sie Links wie /about schreiben. Deshalb steht die Regel in unserer AGENTS.md. Heißt euer Repository name.github.io, braucht ihr kein base. Alle Ursachen und Lösungen stehen in Astro auf GitHub Pages zeigt 404 oder kein CSS.

Tipp 8 Mit der offiziellen Astro Action deployen

Für den Deploy braucht ihr eine Workflow Datei unter .github/workflows/deploy.yml. Astro pflegt dafür eine eigene GitHub Action. Sie erkennt euren Paketmanager am Lockfile, baut die Seite und lädt sie hoch. Ein zweiter Job stellt sie auf GitHub Pages bereit.

name: Deploy to GitHub Pages

on:
  push:
    branches: [ main ]
  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: withastro/action@v6

  deploy:
    needs: build
    runs-on: ubuntu-latest
    environment:
      name: github-pages
      url: ${{ steps.deployment.outputs.page_url }}
    steps:
      - name: Deploy to GitHub Pages
        id: deployment
        uses: actions/deploy-pages@v5

Drei Dinge vergessen viele. Committet das Lockfile, also package-lock.json oder pnpm-lock.yaml. Stellt im Repository unter Settings und Pages die Source auf GitHub Actions. Und prüft die Versionen der Actions regelmäßig in der Astro Anleitung für GitHub Pages. Dependency Updates erledigt bei uns Renovate.

Tipp 9 Eigene Domain mit CNAME Datei einrichten

Für eine eigene Domain legt ihr eine Datei public/CNAME an. Darin steht nur eine Zeile mit eurer Domain, etwa www.eure-domain.de. Dann setzt ihr site auf die neue Domain und entfernt base komplett. Die Präfixe in den Links fallen damit auch weg. Gebt dem Agent diesen Umbau als einen Auftrag im Plan Modus. Sonst bleiben alte Links mit Präfix stehen.

Tipp 10 Wiederkehrende Checks als eigenen Command speichern

Ihr tippt immer wieder denselben Prompt? Macht einen Command daraus. Eine Markdown Datei unter .opencode/commands/ wird zum Slash Befehl. Mit Ausrufezeichen und Backticks fügt OpenCode die Ausgabe eines Shell Befehls direkt in den Prompt ein.

---
description: Build und Checks für die Astro Seite
agent: build
---
Ergebnis vom Build:

!`npm run build`

Ergebnis von astro check:

!`npx astro check`

Behebe alle Fehler. Ändere keine Texte in src/content.

Als check.md gespeichert, startet ihr das mit /check. Der Agent sieht die echten Fehlermeldungen und muss nicht raten. Mehr Varianten mit Argumenten zeigt die OpenCode Doku zu Commands. Vier fertige Commands zum Kopieren stehen in OpenCode Commands erstellen.

Tipp 11 Den Dev Server im Hintergrund laufen lassen

Ein kleines Detail seit Astro 7. Erkennt Astro einen Coding Agent, startet astro dev auf macOS und Linux automatisch im Hintergrund. Der Agent blockiert sein Terminal also nicht mehr mit dem Server. Eine Lock Datei verhindert doppelte Server. Über den Endpunkt /_astro/status kann der Agent prüfen, ob der Server bereit ist. Wer das nicht will, setzt ASTRO_DEV_BACKGROUND=0.

Tipp 12 Quality Gates vor den Deploy setzen

Vibe Coding geht schnell. Kaputt geht es genauso schnell. Der Build im Workflow ist die erste Hürde, denn schlägt er fehl, wird nichts veröffentlicht. Für eine Landingpage reicht das nicht. Prüft auch, ob die Seite im Browser wirklich funktioniert.

• Typen und Templates: npx astro check als eigener Schritt im Workflow.
• End to End Tests: Cypress prüft Navigation, Links und Formulare gegen die gebaute Seite. Für Basistests mit einer Zeile im CI gibt es unser Cypress Base Plugin.
• Review vor dem Merge: Lest den Diff, bevor ihr pusht. Der Agent schreibt schnell, ihr entscheidet.

Warum Tests für jedes Webprojekt Pflicht sind, steht im Beitrag End to End Tests für jedes Webprojekt. Und warum Regeln mit jedem neuen Modell wichtiger werden, erklärt KI Guardrails und bessere Modelle.

Tipp 13 OpenCode direkt in GitHub Issues nutzen

OpenCode lässt sich auch in GitHub einbinden. Mit opencode github install richtet ihr App, Workflow und Secrets ein. Danach reicht ein Kommentar mit /oc oder /opencode in einem Issue oder Pull Request. OpenCode läuft dann im GitHub Actions Runner, legt einen Branch an und öffnet einen Pull Request.

Das eignet sich gut für kleine Aufgaben wie Textkorrekturen oder ein Review. Das Modell und den API Key legt ihr selbst fest, der Key gehört in die Secrets des Repositorys. Fangt mit Reviews an und gebt erst danach Schreibrechte. Die Einrichtung beschreibt die OpenCode Doku zu GitHub. Schritt für Schritt erklären wir sie in OpenCode GitHub Action einrichten. Wer Git Kontext direkt im Agent will, findet beim GitKraken MCP Server für OpenCode eine Alternative.

Tipp 14 Die Grenzen von GitHub Pages kennen

GitHub Pages ist kostenlos, aber kein Hosting für alles. Diese Grenzen nennt GitHub selbst:

• Die veröffentlichte Seite darf höchstens 1 GB groß sein.
• Es gibt ein weiches Limit von 100 GB Bandbreite im Monat.
• Ein Deployment bricht nach 10 Minuten ab.
• Online Shops, SaaS und Seiten, die vor allem Verkäufe abwickeln, sind nicht erlaubt.
• Passwörter und Zahlungsdaten haben auf GitHub Pages nichts verloren.

Für Landingpages, Dokumentation, Portfolios und Talks passt das sehr gut. Die vollständige Liste steht bei den GitHub Pages Limits. GitHub ist ein US Anbieter. Nehmt das Hosting deshalb in eure Datenschutzerklärung auf. Projekte mit Kundendaten gehören auf Server in Deutschland.

Alle Vibe Coding Tipps für Astro auf einen Blick

Tipp	Datei oder Befehl	Nutzen
Template nutzen	npm create astro@latest	Klare Struktur für den Agent
Projektregeln	/init und AGENTS.md	Gleiche Regeln für Team und Agent
Aktuelle Doku	Astro Docs MCP in opencode.json	Keine veralteten APIs
Plan Modus	Tab Taste	Erst denken, dann ändern
Rechte	permission in opencode.json	Kein Push und kein Löschen ohne euch
Pfade	site und base in astro.config	Keine 404 auf GitHub Pages
Deploy	withastro/action im Workflow	Jeder Push geht automatisch live
Checks	.opencode/commands/check.md	Echte Fehler statt Raten
Quality Gates	astro check und Cypress	Nur funktionierende Seiten gehen live

Wie wir Teams beim Vibe Coding mit Astro begleiten

Astro, OpenCode, GitHub Actions und Cypress nutzen wir täglich. Ein Setup wie oben steht schnell. Die Arbeit steckt in den Details: Regeln, die der Agent wirklich befolgt, Rechte, die zum Team passen, und Tests, die vor dem Deploy greifen. Genau dabei helfen wir. Den Einstieg erklärt unser Beitrag Vibe Coding anfangen. Begleitung im Projekt gibt es in der Vibe Coding Beratung, Frontends mit Astro bauen wir im Frontend Development.

Für Developer gibt es den NCA KI Workshop für Developer mit Agentic Coding für die Produktion. Wie Roland mit OpenCode und freien Modellen live vor Publikum baut, zeigt der Bericht vom UPSCALER Event in Essen. Das Vorgespräch ist kostenlos. Wir schätzen den Aufwand ehrlich und rechnen transparent nach Minuten ab.

Häufige Fragen zu Vibe Coding mit Astro und GitHub Pages

Welche Vibe Coding Tipps helfen 2026 bei Astro am meisten?

Am meisten bringen eine gepflegte AGENTS.md, der Plan Modus vor größeren Änderungen und die Astro Docs als MCP Server. Dazu kommen begrenzte Rechte für den Agent und ein Build, der vor jedem Deploy grün sein muss. Damit vermeidet ihr veraltete APIs, ungewollte Änderungen und kaputte Seiten im Live Betrieb.

Ist GitHub Pages 2026 kostenlos für Astro Seiten?

Ja, für öffentliche Repositories ist GitHub Pages kostenlos. Die Seite darf höchstens 1 GB groß sein, und es gibt ein weiches Limit von 100 GB Bandbreite pro Monat. Online Shops und SaaS sind nicht erlaubt. Für Landingpages, Portfolios und Dokumentation reicht das in der Regel locker aus.

Warum funktionieren Links auf GitHub Pages 2026 nicht?

Meist fehlt der base Pfad. Ohne eigene Domain liegt die Seite unter name.github.io/repo-name. Setzt in der astro.config den Wert site auf eure GitHub Adresse und base auf den Repository Namen. Alle internen Links brauchen dann diesen Pfad als Präfix. Mit eigener Domain entfernt ihr base wieder.

Welche Modelle eignen sich 2026 für OpenCode und Astro?

Für Landingpages und kleine Tools reichen Open Weight Modelle wie GLM oder Qwen sehr gut. Wir nutzen sie in OpenCode über Ollama Cloud oder Z.AI. Große Coding Modelle laufen dabei aus der Cloud. Bei öffentlichen Inhalten wie einer Landingpage ist das unkritisch, bei Kundendaten arbeitet ihr lokal mit Testdaten.

Brauche ich 2026 Programmierkenntnisse für Vibe Coding mit Astro?

Für eine erste Seite nicht unbedingt. Grundlagen in HTML, Git und dem Terminal helfen aber sehr. Spätestens beim Deploy, bei Fehlern im Build oder bei kaputten Links müsst ihr verstehen, was der Agent tut. Wer das lernen will, startet mit kleinen Projekten und klaren Regeln für den Agent.

Was gehört in die AGENTS.md für ein Astro Projekt?

Die Befehle für Dev, Build und Checks, die Ordnerstruktur und eure Regeln. Wichtig für Astro sind Integrationen nur über astro add, Texte nur in src/content und Links immer mit base Pfad. Startet mit /init und ergänzt den Entwurf von Hand. Committet die Datei, damit das ganze Team davon profitiert.

Kann OpenCode direkt aus GitHub heraus arbeiten?

Ja. Nach opencode github install reagiert OpenCode auf Kommentare mit /oc oder /opencode in Issues und Pull Requests. Es läuft im GitHub Actions Runner, legt Branches an und öffnet Pull Requests. Modell und API Key bestimmt ihr selbst. Startet mit Reviews und vergebt Schreibrechte erst danach.