Créer un site portfolio avec Claude Code et Astro : guide pratique

Définir le rôle réel du portfolio

Un portfolio n’est pas seulement une vitrine graphique. C’est une page de décision pour une personne qui veut savoir rapidement si vous pouvez l’aider : recruteur, client indépendant, organisateur de conférence ou partenaire potentiel. La première version doit donc montrer clairement votre rôle, vos preuves, vos projets et le moyen de vous contacter.

Dans cet article, Claude Code sert de partenaire de développement local. La documentation officielle de Claude Code explique qu’il peut lire une base de code, modifier des fichiers et exécuter des commandes. C’est précisément ce dont on a besoin pour construire une version simple, vérifier le résultat, puis demander une revue ciblée.

Le site sera construit avec Astro et du CSS simple. Pour un portfolio personnel, le HTML statique est souvent suffisant : c’est rapide, facile à héberger et plus simple à auditer. La structure officielle Astro project structure donne aussi un cadre clair à Claude Code.

Si vous débutez, commencez par le guide interne Claude Code pour débuter. Pour le contexte Astro, gardez aussi développer avec Astro et Claude Code sous la main.

Périmètre de la première version

Nous allons créer une page unique avec Hero, About, Projects, Services et Contact. Un CMS, un backend de formulaire ou des animations complexes pourront venir plus tard. La première livraison doit être lisible, publiable et facile à faire évoluer.

flowchart TD
  A["Brief du portfolio"] --> B["src/data/profile.ts"]
  B --> C["src/pages/index.astro"]
  C --> D["src/styles/global.css"]
  D --> E["npm run build"]
  E --> F["Revue avant publication"]

Séparez les données et l’affichage. src/data/profile.ts contient le profil et les projets; index.astro affiche la page. Cette séparation permet ensuite de demander à Claude Code une petite modification, par exemple “améliore uniquement le texte des projets” ou “change le layout des cartes”.

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

Les images placées dans public/ sont accessibles via /projects/booking-site.webp. La référence MDN de l’élément img rappelle l’importance du texte alt. Pour les images plus bas dans la page, la page MDN sur le lazy loading explique l’attribut natif loading="lazy".

Prompt à donner à Claude Code

Un bon résultat commence par une demande précise. Évitez “fais-moi un portfolio moderne”. Donnez l’audience, les fichiers, les limites et la condition de fin.

Je veux créer un site portfolio personnel avec Astro.
L’audience est composée de recruteurs et de petits clients qui doivent comprendre mon travail en moins de trois minutes.

Exigences:
- Une page avec Hero, About, Projects, Services et Contact
- Stocker le profil et les projets dans src/data/profile.ts
- Implémenter src/pages/index.astro et src/styles/global.css
- Ne pas ajouter React ni une grosse bibliothèque UI
- Toutes les images doivent avoir un alt
- Les CTA doivent rester lisibles sur mobile
- Terminer par npm run build

Avant de modifier les fichiers, résume le plan et les fichiers concernés.

Demander le plan avant l’édition permet de bloquer un élargissement inutile du périmètre. Si Claude Code propose un CMS ou une animation lourde, demandez pourquoi. Pour la revue après implémentation, vous pouvez compléter avec optimisation SEO avec Claude Code.

Code de départ

Pour un nouveau projet, créez l’application Astro. Dans un dépôt existant, demandez d’abord à Claude Code de lire l’arborescence.

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

Créez ensuite les données du portfolio. Les descriptions doivent parler du problème résolu, pas seulement des technologies.

// src/data/profile.ts
export const profile = {
  name: "Masa Tanaka",
  role: "Frontend engineer / accompagnement Claude Code",
  location: "Tokyo, Japan",
  summary:
    "Je crée des sites rapides et maintenables avec Astro, React, TypeScript et une approche contenu orientée amélioration continue.",
  skills: ["Astro", "TypeScript", "React", "CSS", "SEO", "Content Ops"],
  links: {
    email: "masa@example.com",
    github: "https://github.com/example",
  },
} as const;

export const projects = [
  {
    title: "Refonte du parcours de réservation",
    description:
      "Menu mobile, explication des services et CTA ont été clarifiés pour réduire l’hésitation avant la prise de contact.",
    image: "/projects/booking-site.webp",
    alt: "Capture d’un site de réservation avec cartes de services et bouton principal",
    tags: ["Astro", "SEO", "Responsive"],
    url: "https://example.com/booking",
  },
  {
    title: "Dashboard SaaS de tâches",
    description:
      "Cartes, filtres de statut et états vides ont été retravaillés pour guider les nouveaux utilisateurs.",
    image: "/projects/task-dashboard.webp",
    alt: "Capture d’un dashboard SaaS avec cartes de tâches et filtres",
    tags: ["TypeScript", "UI Design", "Dashboard"],
    url: "https://example.com/dashboard",
  },
] as const;

Voici une page Astro minimale. Le contact passe par email pour éviter de construire un backend trop tôt.

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

<html lang="fr">
  <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}: projets, services et contact.`} />
    <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">Voir les projets</a>
          <a class="button secondary" href={`mailto:${profile.links.email}`}>Démarrer une discussion</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">Lire la suite</a>
              </div>
            </article>
          ))}
        </div>
      </section>
    </main>
  </body>
</html>

Le CSS suivant suffit pour une base propre et responsive.

/* 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%;
  }
}

Cas d’usage concrets

Un portfolio doit être adapté au lecteur principal.

Cas d’usage	Ce que le lecteur vérifie	Ce que la page doit montrer
Recherche d’emploi	Compétences, rôle, preuves	Stack, responsabilités, liens demo ou GitHub
Freelance	Capacité à résoudre un problème	Services, exemples, CTA email, livrables
Conférences ou rédaction	Expertise et bio courte	Sujets, articles, photo, profil
Journal d’apprentissage	Progression et projets reproductibles	Notes, erreurs, démos, prochaines étapes

Pour un emploi, insistez sur votre rôle réel. Pour du freelance, proposez une entrée claire : audit de landing page, amélioration de performance, revue Claude Code, création de site statique. Pour la prise de parole, reliez rapidement le sujet, les articles et la bio.

ClaudeCodeLab relie aussi contenu gratuit, ressources téléchargeables et accompagnement payant. Un CTA utile ne dit pas seulement “contactez-moi”; il précise le type de problème que vous pouvez traiter. La page training et consultation donne un exemple de parcours monétisable sans vider l’article de sa valeur.

SEO, accessibilité et pièges

Le SEO d’un portfolio repose sur la clarté. Utilisez les mots que vos lecteurs emploieraient : “portfolio frontend”, “développeur Astro”, “accompagnement Claude Code”, ou un mot local si vous vendez une prestation locale. Placez-les naturellement dans le titre, la description, le h1 et les projets.

Relis ce portfolio Astro pour le SEO et l’accessibilité.
Vérifie title, description, hiérarchie h1/h2/h3, alt des images, liens internes,
liens externes, CTA et lisibilité mobile.
Retourne seulement les problèmes, les raisons et la plus petite correction utile.

Les pièges fréquents sont simples. Trop construire avant d’expliquer qui vous êtes. Écrire “je connais React” au lieu de raconter un problème résolu. Publier sans vérifier npm run build, les liens, l’image OGP et le mobile. Enfin, donner à l’IA des informations privées comme noms clients, URLs internes, revenus ou valeurs .env. Utilisez des captures anonymisées et des données fictives.

Résultat testé et suite

Le choix le plus stable est de placer les données dans src/data/profile.ts. En pratique, cela sépare les changements de texte des changements de mise en page, ce qui rend les revues Claude Code plus courtes. Avant publication, exécutez npm run build, puis vérifiez Hero, Projects et Contact sur mobile.

Un portfolio n’est jamais terminé. Ajoutez de meilleurs visuels, réécrivez les projets faibles, testez un CTA plus précis et reliez vos articles internes. Avec Claude Code, la meilleure méthode n’est pas un énorme prompt unique, mais une suite de petites améliorations vérifiées.