Portfolio-Website mit Claude Code und Astro bauen: Umsetzung und Checkliste

Zuerst die Aufgabe des Portfolios klären

Eine Portfolio-Website ist keine reine Bildergalerie. Sie ist eine Entscheidungsseite für Recruiter, potenzielle Kunden, Veranstalter oder Kooperationspartner. In wenigen Minuten muss klar sein, wer du bist, welche Probleme du gelöst hast, welche Arbeit man sehen kann und wie man dich erreicht.

Claude Code wird hier als lokaler Entwicklungspartner genutzt. Die offizielle Claude Code Dokumentation beschreibt, dass Claude Code Code lesen, Dateien ändern, Befehle ausführen und mit Entwicklungswerkzeugen arbeiten kann. Genau deshalb eignet es sich gut für eine kleine, überprüfbare erste Version.

Für die Umsetzung nutzen wir Astro und schlichtes CSS. Ein Portfolio kann meist als statisches HTML ausgeliefert werden. Das ist schnell, einfach zu hosten und leichter zu prüfen als ein unnötig großes Frontend. Die offizielle Astro-Projektstruktur gibt außerdem eine klare Ordnung vor.

Wenn du Claude Code noch nicht kennst, lies zuerst den internen Claude Code Einstieg. Für Astro hilft zusätzlich Astro-Entwicklung mit Claude Code.

Umfang der ersten Version

Wir bauen eine einzelne Seite mit Hero, About, Projects, Services und Contact. CMS, Login, Animationen und Formular-Backend kommen später, wenn es dafür einen echten Grund gibt. Die erste Version soll veröffentlicht werden können und einfach zu verbessern sein.

flowchart TD
  A["Portfolio-Briefing"] --> B["src/data/profile.ts"]
  B --> C["src/pages/index.astro"]
  C --> D["src/styles/global.css"]
  D --> E["npm run build"]
  E --> F["Review vor Launch"]

Lege Profil und Projekte in src/data/profile.ts ab. index.astro rendert nur die Seite. Diese Trennung macht spätere Claude-Code-Aufgaben kleiner: Text überarbeiten, Karten neu sortieren, CSS anpassen, ohne jedes Mal alles zu berühren.

my-portfolio/
  src/
    data/profile.ts
    pages/index.astro
    styles/global.css
  public/
    ogp.png
    projects/booking-site.webp

Bilder in public/ sind als /projects/booking-site.webp erreichbar. Die MDN-Referenz zum img Element erklärt, warum gutes alt wichtig ist. Für Bilder weiter unten auf der Seite ist Lazy loading mit loading="lazy" sinnvoll.

Ein brauchbarer Prompt für Claude Code

Ein vager Auftrag erzeugt ein vages Portfolio. Definiere Zielgruppe, Dateien, Grenzen und Abschlusskriterium.

Ich möchte mit Astro eine persönliche Portfolio-Website bauen.
Die Zielgruppe sind Recruiter und kleine Kunden, die meine Arbeit in unter drei Minuten verstehen sollen.

Anforderungen:
- Eine Seite mit Hero, About, Projects, Services und Contact
- Profil und Projekte in src/data/profile.ts speichern
- src/pages/index.astro und src/styles/global.css umsetzen
- Kein React und keine schwere UI-Bibliothek hinzufügen
- Alle Bilder brauchen alt-Text
- CTA-Buttons müssen auf Mobilgeräten lesbar bleiben
- Am Ende npm run build ausführen

Fasse vor dem Editieren kurz den Plan und die zu ändernden Dateien zusammen.

Der Plan vor dem Editieren ist wichtig. Wenn Claude Code zusätzliche Pakete, ein CMS oder eine API-Route vorschlägt, kannst du den Umfang rechtzeitig begrenzen. Für eine spätere Prüfung passt der interne Leitfaden SEO mit Claude Code.

Kopierbarer Startcode

Für ein neues Projekt startest du mit Astro. In einem vorhandenen Repository sollte Claude Code zuerst die bestehende Struktur lesen.

npm create astro@latest my-portfolio
cd my-portfolio
npm run dev

Danach kommt die Datendatei. Beschreibe Projekte konkret: Problem, eigene Rolle, Umsetzung, Ergebnis. Eine reine Liste von Technologien überzeugt selten.

// src/data/profile.ts
export const profile = {
  name: "Masa Tanaka",
  role: "Frontend Engineer / Claude Code Implementierungspartner",
  location: "Tokyo, Japan",
  summary:
    "Ich baue schnelle, wartbare Websites mit Astro, React, TypeScript und Content-Workflows, die messbare Verbesserungen ermöglichen.",
  skills: ["Astro", "TypeScript", "React", "CSS", "SEO", "Content Ops"],
  links: {
    email: "masa@example.com",
    github: "https://github.com/example",
  },
} as const;

export const projects = [
  {
    title: "Buchungsseite optimiert",
    description:
      "Mobiles Menü, Leistungsbeschreibung und Reservierungs-CTA wurden neu geordnet, damit Besucher schneller den nächsten Schritt finden.",
    image: "/projects/booking-site.webp",
    alt: "Screenshot einer Buchungsseite mit Servicekarten und Reservierungsbutton",
    tags: ["Astro", "SEO", "Responsive"],
    url: "https://example.com/booking",
  },
  {
    title: "SaaS Task Dashboard",
    description:
      "Karten, Statusfilter und Empty States wurden überarbeitet, damit Testnutzer den Workflow schneller verstehen.",
    image: "/projects/task-dashboard.webp",
    alt: "Screenshot eines SaaS Dashboards mit Task-Karten und Filtern",
    tags: ["TypeScript", "UI Design", "Dashboard"],
    url: "https://example.com/dashboard",
  },
] as const;

Die Seite kann minimal so aussehen. Kontakt läuft zunächst über E-Mail, damit kein unnötiges Backend entsteht.

---
import { profile, projects } from "../data/profile";
import "../styles/global.css";
---

<html lang="de">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1" />
    <title>{profile.name} | Portfolio</title>
    <meta name="description" content={`${profile.role}: Projekte, Leistungen und Kontakt.`} />
    <meta property="og:title" content={`${profile.name} | Portfolio`} />
    <meta property="og:description" content={profile.summary} />
    <meta property="og:image" content="/ogp.png" />
  </head>
  <body>
    <main>
      <section class="hero" aria-labelledby="hero-title">
        <p class="eyebrow">{profile.location}</p>
        <h1 id="hero-title">{profile.name}</h1>
        <p class="lead">{profile.summary}</p>
        <div class="actions">
          <a class="button primary" href="#projects">Projekte ansehen</a>
          <a class="button secondary" href={`mailto:${profile.links.email}`}>Gespräch starten</a>
        </div>
      </section>

      <section id="projects" class="section" aria-labelledby="projects-title">
        <h2 id="projects-title">Projects</h2>
        <div class="project-grid">
          {projects.map((project) => (
            <article class="project-card">
              <img src={project.image} alt={project.alt} width="960" height="540" loading="lazy" />
              <div class="project-body">
                <h3>{project.title}</h3>
                <p>{project.description}</p>
                <ul class="tag-list">
                  {project.tags.map((tag) => <li>{tag}</li>)}
                </ul>
                <a href={project.url} target="_blank" rel="noreferrer">Mehr lesen</a>
              </div>
            </article>
          ))}
        </div>
      </section>
    </main>
  </body>
</html>

Das CSS konzentriert sich auf Lesbarkeit, stabile Breiten und responsive Karten.

/* src/styles/global.css */
:root {
  --bg: #f7f3ec;
  --panel: #ffffff;
  --text: #1f2933;
  --muted: #5f6c7b;
  --accent: #0f766e;
  --line: #d8dee4;
}

* {
  box-sizing: border-box;
}

body {
  margin: 0;
  font-family: Inter, system-ui, sans-serif;
  background: var(--bg);
  color: var(--text);
  line-height: 1.75;
}

.hero,
.section {
  width: min(1120px, calc(100% - 32px));
  margin: 0 auto;
}

.hero {
  min-height: 82vh;
  display: grid;
  align-content: center;
}

.actions,
.tag-list {
  display: flex;
  flex-wrap: wrap;
  gap: 12px;
  padding: 0;
  list-style: none;
}

.button {
  display: inline-flex;
  min-height: 44px;
  align-items: center;
  justify-content: center;
  padding: 0 18px;
  border: 1px solid var(--accent);
  border-radius: 6px;
  text-decoration: none;
  font-weight: 700;
}

.button.primary {
  background: var(--accent);
  color: white;
}

.project-grid {
  display: grid;
  grid-template-columns: repeat(auto-fit, minmax(260px, 1fr));
  gap: 24px;
}

.project-card {
  background: var(--panel);
  border: 1px solid var(--line);
  border-radius: 8px;
  overflow: hidden;
}

.project-card img {
  display: block;
  width: 100%;
  aspect-ratio: 16 / 9;
  object-fit: cover;
}

@media (max-width: 640px) {
  .button {
    width: 100%;
  }
}

Reale Use Cases

Ein Portfolio sollte je nach Zielgruppe anders gewichtet werden.

Use Case	Was der Leser prüft	Was die Seite zeigen sollte
Jobsuche	Technik, Verantwortung, Nachweis	Stack, Rolle, Teamgröße, Demo oder GitHub
Freelance	Problem-Fit und Kontaktweg	Leistungen, typische Anfragen, E-Mail-CTA
Vorträge oder Schreiben	Thema und Glaubwürdigkeit	Themen, Artikel, Kurzprofil, Foto
Lernlog	Fortschritt und Reproduzierbarkeit	Notizen, Fehler, Demo, nächste Schritte

Für Jobs zählt deine konkrete Verantwortung. Für Freelance-Aufträge zählen einfache Einstiegspunkte: Landingpage-Audit, Performance-Review, CTA-Verbesserung, Claude-Code-Workflow-Review. Für Vorträge muss das Thema im ersten Bildschirm sofort erkennbar sein.

ClaudeCodeLab verbindet kostenlose Artikel, Checklisten, Trainingsmaterial und Beratung. Ein guter CTA sagt nicht nur “Kontakt”, sondern nennt das Problem, bei dem du helfen kannst. Die Seite Training und Beratung zeigt, wie ein solcher Weg aussehen kann.

SEO, Barrierefreiheit und Fehler

SEO bedeutet bei einem Portfolio vor allem Klarheit. Nutze Begriffe, nach denen deine Zielgruppe wirklich sucht: “Frontend Portfolio”, “Astro Entwickler”, “Claude Code Beratung” oder lokale Begriffe für Dienstleistungen. Setze sie natürlich in title, description, h1 und Projekttexte.

Prüfe dieses Astro-Portfolio auf SEO und Barrierefreiheit.
Kontrolliere title, description, h1/h2/h3, Bild-alt-Texte, interne Links,
externe Links, CTA und mobile Lesbarkeit.
Gib nur Probleme, Gründe und die kleinste sinnvolle Korrektur zurück.

Typische Fehler sind Überbau, vage Nachweise, fehlende Launch-Prüfung und private Daten im Prompt. Ein schönes 3D-Intro hilft nicht, wenn niemand versteht, was du anbietest. “React” als Wort reicht nicht; beschreibe ein gelöstes Problem. Vor Veröffentlichung sollten npm run build, Links, OGP-Bild und mobile Buttons geprüft sein. Kundennamen, interne URLs und .env-Werte gehören nicht in KI-Konversationen.

Getestetes Ergebnis und nächster Schritt

Der stabilste Teil dieses Aufbaus ist die Trennung von Daten und Layout. src/data/profile.ts macht Textänderungen klein und CSS-Änderungen überprüfbar. In der Praxis werden Claude-Code-Diffs dadurch kürzer und leichter zu genehmigen.

Vor dem Launch solltest du npm run build ausführen und Hero, Projects sowie Contact auf Mobilbreite prüfen. Danach bleibt das Portfolio ein lebendes Produkt: bessere Screenshots, stärkere Projekttexte, klarere CTA und interne Links zu relevanten Artikeln. Claude Code ist dafür am nützlichsten, wenn du kleine, überprüfbare Verbesserungen anforderst.