Claude Codeでポートフォリオサイトを作る方法：Astro実装と公開前チェック

Claude Codeで作るポートフォリオの考え方

ポートフォリオサイトは、作品を並べるだけの名刺ではありません。採用担当者、発注候補、登壇依頼者が「この人に頼むと何が起きるか」を短時間で判断するための営業ページです。だから最初に必要なのは派手なアニメーションではなく、肩書き、強み、実績、連絡方法、信頼材料が迷わず読める構成です。

ここでは Claude Code公式ドキュメント の考え方に沿って、Claude Codeを「コードを丸投げする相手」ではなく、ローカルのコードベースを読み、ファイルを編集し、ビルド確認まで一緒に進めるエージェントとして使います。harness（エージェントの足場）という言葉が出てきたら、ツール実行、文脈管理、権限確認をまとめる作業環境のことだと考えるとわかりやすいです。

実装は Astro を使います。Astroは静的サイト、つまりビルド時にHTMLを生成して配信できるサイトに向いています。個人のポートフォリオなら、問い合わせフォーム以外はサーバー処理が不要なことが多く、表示速度と保守の軽さを優先できます。Astroの基本構成は Project structure で確認できます。

このガイドは、Claude Codeが初めての人でも手順を追えるように、要件整理、ファイル構成、コピペできるコード、SEO、画像、失敗例、公開前チェックまでまとめます。Claude Codeそのものに慣れていない場合は、先に Claude Code入門ガイド を読んでから戻るとスムーズです。

完成形とファイル構成

今回作るのは、トップページ1枚で完結する小さなポートフォリオです。ページはHero、About、Projects、Services、Contactに分けます。いきなりCMSや認証を入れると、Claude Codeに渡す文脈が膨らみ、レビューすべき差分も増えます。最初は静的データで作り、必要になってからブログや問い合わせAPIを追加するほうが安全です。

flowchart TD
  A["要件メモ"] --> B["src/data/profile.ts"]
  B --> C["src/pages/index.astro"]
  C --> D["src/styles/global.css"]
  D --> E["npm run build"]
  E --> F["公開前レビュー"]

最小構成は次のとおりです。src/data/profile.ts にプロフィールと案件情報を集め、index.astro は表示に集中させます。データと見た目を分けると、Claude Codeに「文言だけ直して」「カードの並びだけ変更して」と小さく依頼できます。

my-portfolio/
  package.json
  astro.config.mjs
  src/
    data/
      profile.ts
    pages/
      index.astro
    styles/
      global.css
  public/
    ogp.png
    projects/
      task-dashboard.webp
      booking-site.webp

画像は public/ に置けば、そのまま /projects/task-dashboard.webp のように参照できます。MDNの img 要素リファレンス にあるように、画像には代替テキストを付け、下部の画像には loading="lazy" を使うと読み込みを遅らせられます。ファーストビューのメイン画像だけは遅延読み込みにしないほうが、LCP（Largest Contentful Paint、最も大きな表示要素が出るまでの時間）を悪化させにくいです。

Claude Codeに渡す依頼文

Claude Codeに最初から「おしゃれなポートフォリオを作って」と頼むと、見た目の好みだけで大きな差分が出やすくなります。実務では、目的、読者、ファイル、制約、完了条件を先に渡します。これだけで出力の品質がかなり安定します。

Astroで個人ポートフォリオサイトを作ります。
目的は採用担当者と小規模案件の発注者に、実績と連絡先を3分以内で伝えることです。

要件:
- 1ページ構成。Hero, About, Projects, Services, Contact を含める
- データは src/data/profile.ts に集約する
- src/pages/index.astro と src/styles/global.css を実装する
- Reactや重いUIライブラリは使わない
- 画像にはalt属性を入れる
- モバイル幅でもCTAボタンが折り返して読めるようにする
- 最後に npm run build で確認する

まず実装方針と変更予定ファイルを短く説明してから編集してください。

ポイントは「最初に方針を出してから編集」と書くことです。初心者ほど、生成されたコードの意図を見失いやすいので、Claude Codeの計画を一度読む時間を作ります。より細かい指示の作り方は Claude CodeでAstroサイトを作る と Claude CodeでSEOを改善する も参考になります。

プロジェクト作成とデータファイル

新規プロジェクトなら、まずAstroを作成します。既存プロジェクトで作業する場合は、このコマンドを実行せず、現在のリポジトリ構成をClaude Codeに読ませてから進めてください。

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

次にプロフィールを1ファイルにまとめます。名前、肩書き、自己紹介、スキル、案件、連絡先をここに置くと、ページ側のHTMLが読みやすくなります。実名を出したくない人は、最初は屋号やハンドルネームでも構いません。ただし、仕事につなげたいなら連絡手段と実績の説明は具体的にしましょう。

// src/data/profile.ts
export const profile = {
  name: "Masa Tanaka",
  role: "フロントエンドエンジニア / Claude Code活用支援",
  location: "Tokyo, Japan",
  summary:
    "Astro、React、TypeScriptを使って、速く読めて運用しやすいWebサイトを作ります。小さな改善を計測しながら積み上げるのが得意です。",
  skills: ["Astro", "TypeScript", "React", "CSS", "SEO", "Content Ops"],
  links: {
    email: "masa@example.com",
    github: "https://github.com/example",
    x: "https://x.com/example",
  },
} as const;

export const projects = [
  {
    title: "予約導線を改善した店舗サイト",
    description:
      "スマートフォンでのメニュー閲覧と予約CTAを整理し、問い合わせ前の迷いを減らしました。",
    image: "/projects/booking-site.webp",
    alt: "予約ボタンとメニューが見やすい店舗サイトのスクリーンショット",
    tags: ["Astro", "SEO", "Responsive"],
    url: "https://example.com/booking",
  },
  {
    title: "タスク管理SaaSのダッシュボード",
    description:
      "カード、ステータス、検索導線を再設計し、初回利用者が次の操作を選びやすい画面にしました。",
    image: "/projects/task-dashboard.webp",
    alt: "タスクカードが並ぶSaaSダッシュボードのスクリーンショット",
    tags: ["TypeScript", "UI Design", "Dashboard"],
    url: "https://example.com/dashboard",
  },
  {
    title: "技術ブログのリニューアル",
    description:
      "記事テンプレート、内部リンク、OGP画像の運用を整え、継続更新しやすい構成にしました。",
    image: "/projects/blog-renewal.webp",
    alt: "記事一覧とカテゴリが整理された技術ブログのスクリーンショット",
    tags: ["Astro", "Content", "Performance"],
    url: "https://example.com/blog",
  },
] as const;

ここで重要なのは、スキルを単語だけで終わらせないことです。React 85% のような自己採点より、「予約導線を改善した」「記事テンプレートを整えた」のように、誰の問題をどう解いたかを書いたほうが伝わります。

トップページを実装する

次の index.astro は、そのまま貼って動かせる最小例です。フォーム送信までは実装せず、メールリンクにしています。個人サイトの初期版では、問い合わせAPIやスパム対策を急いで作るより、まず公開して見られる状態にするほうが価値があります。

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

<html lang="ja">
  <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}の実績とサービスをまとめたポートフォリオサイトです。`} />
    <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">実績を見る</a>
          <a class="button secondary" href={`mailto:${profile.links.email}`}>相談する</a>
        </div>
      </section>

      <section class="section" aria-labelledby="about-title">
        <h2 id="about-title">できること</h2>
        <p>{profile.role}として、設計、実装、改善提案、公開前レビューまでを一緒に進めます。</p>
        <ul class="skills">
          {profile.skills.map((skill) => <li>{skill}</li>)}
        </ul>
      </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">詳しく見る</a>
              </div>
            </article>
          ))}
        </div>
      </section>

      <section class="section contact" aria-labelledby="contact-title">
        <h2 id="contact-title">Contact</h2>
        <p>サイト制作、改善レビュー、Claude Code導入の相談はメールで受け付けています。</p>
        <a class="button primary" href={`mailto:${profile.links.email}`}>{profile.links.email}</a>
      </section>
    </main>
  </body>
</html>

このコードでは、h1 は1ページに1つ、各セクションは h2、カード内は h3 にしています。見出し階層を整えると、検索エンジンだけでなくスクリーンリーダー利用者にも構造が伝わります。アクセシビリティを深掘りしたい場合は Claude Codeでアクセシビリティ改善 も合わせて確認してください。

CSSで見た目を整える

初期版ではTailwind CSSやアニメーションライブラリを入れず、CSSだけで十分です。依存関係を増やすほど、Claude Codeが変更すべきファイルや判断材料も増えます。まずは読みやすさ、余白、ボタン、カード、モバイル対応を固めましょう。

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

* {
  box-sizing: border-box;
}

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

a {
  color: var(--accent-dark);
}

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

.hero {
  min-height: 82vh;
  display: grid;
  align-content: center;
  padding: 80px 0 56px;
}

.eyebrow {
  color: var(--accent-dark);
  font-weight: 700;
  margin: 0 0 12px;
}

h1 {
  font-size: clamp(2.6rem, 7vw, 5.8rem);
  line-height: 1;
  margin: 0 0 24px;
}

h2 {
  font-size: clamp(1.8rem, 4vw, 3rem);
  margin: 0 0 20px;
}

.lead {
  max-width: 760px;
  color: var(--muted);
  font-size: 1.2rem;
}

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

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

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

.button.secondary {
  background: transparent;
  color: var(--accent-dark);
}

.section {
  padding: 64px 0;
}

.skills li,
.tag-list li {
  border: 1px solid var(--line);
  border-radius: 999px;
  padding: 6px 12px;
  background: var(--panel);
}

.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%;
  height: auto;
  aspect-ratio: 16 / 9;
  object-fit: cover;
}

.project-body {
  padding: 20px;
}

.contact {
  border-top: 1px solid var(--line);
}

@media (max-width: 640px) {
  .hero {
    min-height: auto;
    padding-top: 56px;
  }

  .button {
    width: 100%;
  }
}

色は単色の濃淡だけにしないほうが、ポートフォリオらしさが出ます。ここでは生成AI系の紫グラデーションに寄せず、背景は紙のような淡色、アクセントは青緑にしました。自分の作品画像が強いなら、UIの色は少し控えめにしたほうが実績が目立ちます。

3つの実用ユースケース

ポートフォリオは見る相手によって、必要な情報が変わります。Claude Codeには、単にページを作らせるのではなく、「誰が、何を判断するか」まで渡すと改善案が具体的になります。

ユースケース	読者が見たいもの	入れるべき要素
転職・副業応募	技術範囲、担当範囲、成果	使用技術、担当工程、チーム規模、GitHubリンク
フリーランス受注	相談できる課題、費用感、連絡しやすさ	サービス一覧、よくある相談、メールCTA、納品例
登壇・執筆依頼	専門テーマ、過去の発信、プロフィール	登壇テーマ、記事リンク、短い自己紹介、写真
学習記録	成長過程、再現できる制作物	学習ログ、失敗メモ、デモURL、改善予定

たとえば転職向けなら、作品カードに「何を作ったか」だけでなく「自分が担当した範囲」を書きます。フリーランス向けなら、いきなり料金表を細かく出すより、「既存サイトの表示速度改善」「LPのCTA改善」「Claude Code導入レビュー」のように相談しやすい入口を作ります。

ClaudeCodeLabでは、こうした導線を記事、無料PDF、教材、相談メニューにつなげる設計を重視しています。自分のポートフォリオでも、単に「お問い合わせ」ではなく、無料診断、制作相談、レビュー依頼など、次の一歩がわかるCTAにすると収益化につながりやすくなります。相談導線を作る場合は トレーニング・相談ページ のように、誰向けで何を扱うのかを明確にしましょう。

SEOと画像で最低限やること

SEOは、検索順位を魔法のように上げる作業ではありません。検索する人が使う言葉をページ内に自然に入れ、タイトル、description、見出し、画像、内部リンクを整理する作業です。ポートフォリオなら「フロントエンドエンジニア ポートフォリオ」「Astro 制作」「Claude Code 活用支援」のように、読者が実際に検索しそうな言葉を選びます。

Claude Codeには次のようにレビューさせます。

このAstroポートフォリオをSEOとアクセシビリティの観点でレビューしてください。
確認してほしい項目:
- titleとdescriptionが具体的か
- h1/h2/h3の階層が崩れていないか
- 画像altが内容を説明しているか
- 内部リンクと外部リンクが自然か
- CTAがファーストビューと末尾にあるか
- モバイル幅でボタンやカードが読みにくくならないか
修正案は理由付きで、必要な差分だけ出してください。

画像は見栄えだけでなく信頼材料です。作品のスクリーンショットがない場合は、無理に抽象的な背景画像を使うより、画面キャプチャ、構成図、Before/Afterの比較表を作ったほうが伝わります。手順記事ならスクリーンショット、コード例が多い記事なら概念図、比較記事なら比較表を入れる、というルールはポートフォリオにも応用できます。

よくある落とし穴

一つ目の失敗は、最初から凝りすぎることです。3D演出、スクロール連動、重い動画を入れる前に、名前、実績、連絡先が3秒で見えるかを確認してください。表現が強すぎると、見る人は作品ではなく演出のほうに注意を持っていかれます。

二つ目は、コード例や実績が抽象的なことです。「Reactができます」より、「予約画面の離脱を減らすためにフォーム項目を整理した」のほうが仕事につながります。Claude Codeには、作品説明を「課題、担当、実装、結果」の4点で書き直すよう依頼すると改善しやすいです。

三つ目は、公開前チェックを飛ばすことです。リンク切れ、閉じていないコードフェンス、OGP画像の未設定、モバイルで折り返さないボタンは、初心者のポートフォリオでよく見ます。公開前に npm run build を通し、実機幅でHero、Projects、Contactを確認しましょう。

四つ目は、AIに秘密情報を渡すことです。実案件のスクリーンショット、顧客名、売上、未公開URL、.env の値は、そのまま貼らないでください。公開してよい情報に置き換え、必要なら「架空データで表現して」と指示します。

公開前チェックリスト

最後に、Claude Codeにチェックだけを依頼します。実装とレビューを同じ大きな依頼にまとめると、見落としが出やすくなります。レビュー専用のターンを作るのが実務では効きます。

• titleに「誰の何のサイトか」が入っている
• descriptionが120文字以内で、読者のメリットがわかる
• Heroに名前、肩書き、CTAがある
• Projectsに3件以上の具体例がある
• 作品ごとに課題、担当、成果が書かれている
• 画像にalt、width、heightがある
• OGP画像が設定されている
• 内部リンクと外部リンクが最低1つずつある
• npm run build が成功する
• スマートフォン幅でボタンとカードが重ならない

このチェックリストは、記事制作にもそのまま使えます。ポートフォリオの公開後にブログを足すなら、レスポンシブデザイン実装 と内部リンク設計をセットで見直すと、作品ページから記事、記事から相談への流れを作りやすくなります。

この記事で紹介した内容を実際に試した結果

今回の最小構成は、Astroの標準的な src/pages、public、CSS読み込みの形に合わせ、初心者が差分を追いやすい粒度にしました。実務で同じ流れを使うと、Claude Codeへの依頼は「要件整理」「実装」「SEOレビュー」「公開前チェック」に分けたほうが安定します。特に効果があったのは、プロフィール情報を src/data/profile.ts に寄せたことです。文言修正と見た目修正を分離できるため、AIの差分レビューがかなり楽になります。

ポートフォリオは一度作って終わりではありません。案件が増えたらProjectsを更新し、検索されたい言葉が変わったらtitleと見出しを見直し、相談が来ないならCTAを変えます。Claude Codeはその継続改善の相棒として使うと価値が出ます。まずは小さく公開し、反応を見ながら育てていきましょう。