60
65

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

@miruky(miruky)Team Coffee

ポートフォリオ用の綺麗なGitHubリポジトリの作り方 ―すぐに使えるテンプレート付き

60
Posted at

はじめに

こんばんは、mirukyです。
今回は、転職・就職活動で差がつくGitHubリポジトリの作り方を体系的にまとめます。

エンジニア採用において、GitHubはもはや「履歴書の補足資料」ではなく 「実力を証明するポートフォリオそのもの」 です。しかし、多くのエンジニアのリポジトリは以下のような状態になりがちです。

  • READMEが初期状態のまま（# project-name だけ）
  • コミットメッセージが fix update aaa の羅列
  • テストもCIも無し
  • デモ環境がなく、動くかどうか分からない

本記事では、採用担当者が「この人と一緒に働きたい」と思うリポジトリを、ゼロから構築する方法を解説します。読み終えたらすぐに個人開発を始められるよう、テンプレートとコード例をふんだんに盛り込みました。

目次

  1. 採用担当者はGitHubの何を見ているか
  2. リポジトリの全体構成
  3. READMEの書き方
  4. ブランチ戦略とコミットメッセージ
  5. GitHub Actionsで自動化する
  6. IssueとPull Requestを活用する
  7. ドキュメントを充実させる
  8. デプロイとデモ環境
  9. 技術選定のポイント
  10. やりがちなNGパターン
  11. GitHub プロフィールREADMEの作成
  12. おわりに

1. 採用担当者はGitHubの何を見ているか

1-1. 採用目線のチェックポイント

採用担当者やテックリードがポートフォリオを評価する際、 コードの量や使用技術よりも「開発プロセスの質」 を重視する傾向があります。

評価ポイント 見ているもの 評価が高い例
コードの品質 命名規則、関数の分割、エラーハンドリング 一貫したスタイル、適切な抽象化
設計力 ディレクトリ構成、アーキテクチャ 関心の分離が明確
開発プロセス コミット履歴、PR、Issue Conventional Commitsに沿った履歴
ドキュメント力 README、コメント、ADR 第三者が5分で動かせるREADME
自動化への意識 CI/CD、Linter、Formatter GitHub Actionsでテスト・デプロイ自動化
継続性 コントリビューションの頻度 草（コントリビューショングラフ）が定期的に緑

1-2. 量より質

リポジトリは「多くの中途半端なもの」より「少数の完成されたもの」が圧倒的に評価されます
3つの未完成プロジェクトより、1つの完成されたプロジェクトの方が遥かに好印象です。とくにREADMEが整備され、CIが通り、デモが動く状態であれば、それだけで十分なアピールになります。

2. リポジトリの全体構成

2-1. 理想的なディレクトリ構成

実際のチーム開発を意識した構成にすることで、「この人は実務でも同じように開発できる」と思ってもらえます。

以下はWebアプリケーションを想定した構成例です。

my-portfolio-app/
├── .github/                    # GitHub関連の設定
│   ├── workflows/              # GitHub Actions ワークフロー
│   │   ├── ci.yml              # CI（テスト・Lint）
│   │   └── deploy.yml          # デプロイ
│   ├── ISSUE_TEMPLATE/         # Issue テンプレート
│   │   ├── bug_report.yml      # バグ報告用
│   │   └── feature_request.yml # 機能要望用
│   ├── PULL_REQUEST_TEMPLATE.md
│   └── dependabot.yml          # 依存関係の自動更新
├── docs/                       # ドキュメント
│   ├── architecture.md         # アーキテクチャ設計
│   ├── adr/                    # Architecture Decision Records
│   │   └── 001-choose-nextjs.md
│   └── api.md                  # API仕様
├── src/                        # アプリケーションコード
│   ├── components/
│   ├── hooks/
│   ├── lib/
│   ├── pages/ (or app/)
│   └── types/
├── tests/                      # テストコード
│   ├── unit/
│   ├── integration/
│   └── e2e/
├── public/                     # 静的ファイル
├── .env.example                # 環境変数のサンプル（秘密情報は含めない）
├── eslint.config.js             # Linter設定（flat config）
├── .prettierrc                 # Formatter設定
├── .gitignore
├── docker-compose.yml          # ローカル開発環境
├── Dockerfile                  # コンテナ定義
├── LICENSE                     # ライセンス
├── package.json
├── tsconfig.json
└── README.md                   # プロジェクトの顔

2-2. 最低限必要なファイル

どんなプロジェクトでも、以下のファイルは必ず用意しましょう。

ファイル 役割 重要度
README.md プロジェクトの説明・使い方 ★★★ 必須
LICENSE ライセンス明示 ★★★ 必須
.gitignore 不要ファイルの除外 ★★★ 必須
.env.example 環境変数のサンプル ★★☆ 推奨
Dockerfile 環境構築のコンテナ化 ★★☆ 推奨
.github/workflows/ci.yml CI自動化 ★★☆ 推奨

.env ファイルは絶対にコミットしないでください
APIキー・データベースのパスワードなどの秘密情報が含まれる .env ファイルは .gitignore に必ず追加し、代わりに .env.example にダミー値を入れたサンプルを用意しましょう。過去のコミットに含まれている場合は git filter-repo で履歴から完全に削除する必要があります（詳しくはセクション10-2を参照）。

2-3. .env.example のテンプレート

# ======================
# アプリケーション設定
# ======================
NODE_ENV=development
PORT=3000

# ======================
# データベース
# ======================
DATABASE_URL=postgresql://user:password@localhost:5432/myapp_dev

# ======================
# 外部API
# ======================
# https://example.com/api で取得
API_KEY=your_api_key_here
API_SECRET=your_api_secret_here

# ======================
# 認証（OAuth）
# ======================
# https://github.com/settings/developers で作成
GITHUB_CLIENT_ID=your_client_id
GITHUB_CLIENT_SECRET=your_client_secret

.env.example で差がつく
環境変数にコメントで「どこで取得するか」を書いておくと、第三者が迷わずセットアップできます。これだけで「チーム開発を意識している人だ」という印象を与えられます。

3. READMEの書き方

READMEはリポジトリの顔です。採用担当者が最初に見る場所であり、ここの品質でプロジェクト全体の印象が決まります。

3-1. READMEテンプレート

以下のテンプレートをコピーして、自分のプロジェクトに合わせて編集してください。

# 🚀 プロジェクト名

[![CI](https://github.com/yourname/project/actions/workflows/ci.yml/badge.svg)](https://github.com/yourname/project/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-blue.svg)](https://www.typescriptlang.org/)

> **一言で説明**: このプロジェクトが何をするものか、1〜2文で。

![デモのスクリーンショットやGIF](docs/images/demo.gif)

## 📖 概要

このプロジェクトは〇〇のために開発しました。
〇〇という課題を、△△というアプローチで解決しています。

### なぜ作ったのか（モチベーション）

- 既存の〇〇には△△という課題があった
- □□を実現するツールが存在しなかった
- ××の技術を実践的に学びたかった

## ✨ 主な機能

- **機能A**: 説明
- **機能B**: 説明
- **機能C**: 説明

## 🛠 技術スタック

| カテゴリ | 技術 |
|:--|:--|
| フロントエンド | Next.js 15 / React 19 / TypeScript |
| バックエンド | Node.js / Hono |
| データベース | PostgreSQL / Prisma |
| インフラ | Vercel / Docker |
| CI/CD | GitHub Actions |
| テスト | Vitest / Playwright |

## 🏗 アーキテクチャ

```
[Client] → [Next.js App Router] → [API Routes] → [Prisma] → [PostgreSQL]
                                        ↓
                                  [External APIs]
```

詳細は [docs/architecture.md](docs/architecture.md) を参照してください。

## 🚀 はじめ方

### 前提条件

- Node.js >= 20.x
- Docker & Docker Compose
- pnpm >= 9.x

### セットアップ

```bash
# リポジトリをクローン
git clone https://github.com/yourname/project.git
cd project

# 環境変数を設定
cp .env.example .env
# .env を編集して必要な値を設定

# 依存関係をインストール
pnpm install

# データベースを起動
docker compose up -d

# マイグレーションを実行
pnpm db:migrate

# 開発サーバーを起動
pnpm dev
```

http://localhost:3000 でアプリケーションにアクセスできます。

### テストの実行

```bash
# ユニットテスト
pnpm test

# E2Eテスト
pnpm test:e2e

# カバレッジレポート
pnpm test:coverage
```

## 📝 デモ

🔗 **ライブデモ**: [https://project.vercel.app](https://project.vercel.app)

| 機能 | スクリーンショット |
|:--|:--|
| ダッシュボード | ![dashboard](docs/images/dashboard.png) |
| 検索機能 | ![search](docs/images/search.png) |

## 📄 ライセンス

このプロジェクトは [MIT License](LICENSE) の下で公開されています。

3-2. READMEの完成度チェックリスト

チェック項目 説明
☐ プロジェクト名と一言説明がある 何のプロジェクトか一目で分かる
☐ バッジがある（CI、ライセンス等） プロジェクトの状態が一目で分かる
☐ スクリーンショットまたはGIFがある 動きが視覚的に伝わる
☐ セットアップ手順が完結している コピペで動かせる
☐ 技術スタックが明記されている 何を使っているか分かる
☐ デモURLがある 実際に動くものを見てもらえる
☐ ライセンスが明記されている 法的に安心

3-3. バッジの追加方法

Shields.io を使って、プロジェクトの状態を視覚的に伝えるバッジを追加できます。

<!-- CI Status -->
[![CI](https://github.com/USER/REPO/actions/workflows/ci.yml/badge.svg)](https://github.com/USER/REPO/actions/workflows/ci.yml)

<!-- カバレッジ（Codecovを利用する場合） -->
[![codecov](https://codecov.io/gh/USER/REPO/branch/main/graph/badge.svg)](https://codecov.io/gh/USER/REPO)

<!-- ライセンス -->
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

<!-- 使用技術 -->
[![TypeScript](https://img.shields.io/badge/TypeScript-5.x-3178C6?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
[![Next.js](https://img.shields.io/badge/Next.js-15-000000?logo=next.js)](https://nextjs.org/)
[![React](https://img.shields.io/badge/React-19-61DAFB?logo=react&logoColor=black)](https://react.dev/)

バッジは「飾り」ではなく「情報」です
CIが通っていることを示すバッジは、コードが正常に動作することの証拠です。採用担当者はバッジの有無で「品質管理の意識」を判断します。

4. ブランチ戦略とコミットメッセージ

4-1. ブランチ戦略

個人開発でも、チーム開発を想定したブランチ運用を行いましょう。

main（本番環境）
  └── develop（開発用）
        ├── feature/add-auth       # 機能追加
        ├── feature/user-profile   # 機能追加
        ├── fix/login-error        # バグ修正
        └── docs/update-readme     # ドキュメント更新
ブランチ 用途 マージ先
main 本番環境にデプロイするコード -
develop 開発中の最新コード main
feature/* 新機能の開発 develop
fix/* バグ修正 develop
docs/* ドキュメント更新 develop

なぜ個人開発でブランチを切るのか？
main に直接プッシュするのは簡単ですが、採用担当者が見たとき「チーム開発の経験がないのかな？」と思われる可能性があります。feature ブランチを切ってPRを作成し、セルフマージする習慣をつけましょう。それ自体が実務スキルの証明になります。

4-2. Conventional Commits

コミットメッセージは、Conventional Commits の仕様に沿って書きましょう。

<型>(スコープ): タイトル

[本文]

[フッター]

主な型（type）

型 用途 例
feat 新機能の追加 feat(auth): Google OAuth ログインを追加
fix バグ修正 fix(api): ユーザー検索の N+1 問題を解消
docs ドキュメント変更 docs: README にセットアップ手順を追加
style コードスタイル変更（動作に影響なし） style: ESLint ルールに合わせて修正
refactor リファクタリング refactor(hooks): useAuth を custom hook に分離
test テストの追加・修正 test(api): ユーザー作成 API のユニットテスト追加
chore ビルド・ツール設定の変更 chore: Node.js を v22 に更新
ci CI設定の変更 ci: GitHub Actions に Lint ジョブを追加
perf パフォーマンス改善 perf(db): クエリにインデックスを追加

良いコミットメッセージの例

# ❌ ダメな例
git commit -m "fix"
git commit -m "update"
git commit -m "修正"
git commit -m "aaa"

# ✅ 良い例
git commit -m "feat(auth): メールアドレスによるパスワードリセット機能を追加"
git commit -m "fix(ui): モバイル表示時にナビゲーションが崩れる問題を修正"
git commit -m "refactor(api): ユーザーサービスの責務を分離しSRPに準拠"
git commit -m "test(auth): ログイン失敗時のエラーハンドリングをテスト"

4-3. コミットメッセージの自動検証

commitlint を導入すると、Conventional Commits に沿っていないコミットを自動で弾けます。

# インストール
pnpm add -D @commitlint/cli @commitlint/config-conventional

# 設定ファイルを作成
echo "export default { extends: ['@commitlint/config-conventional'] };" > commitlint.config.js

husky と組み合わせて、コミット時に自動チェックします。

# husky のインストールと初期化
pnpm add -D husky
pnpm exec husky init

# commit-msg フックを追加
echo 'pnpm exec commitlint --edit "$1"' > .husky/commit-msg

Conventional Commits のメリット

  • コミット履歴が一目で理解できる
  • CHANGELOG（変更履歴）を自動生成できる
  • 採用担当者に「一貫したルールで開発を進められる人」という印象を与えられる

出典：Conventional Commits 1.0.0

5. GitHub Actionsで自動化する

5-1. なぜCIが重要なのか

GitHub Actionsを設定することで、 「このリポジトリのコードは常にテストに通っている」 ことを客観的に証明できます。CIが設定されているリポジトリは、それだけで採用担当者の評価が上がります。

5-2. CI ワークフロー（テスト・Lint）

.github/workflows/ci.yml を作成します。

name: CI

on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main, develop]

# 同じブランチで新しいプッシュがあったら、古いワークフローをキャンセル
concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

jobs:
  lint:
    name: Lint
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: pnpm/action-setup@v4
        with:
          version: 9

      - uses: actions/setup-node@v4
        with:
          node-version: '22'
          cache: 'pnpm'

      - run: pnpm install --frozen-lockfile
      - run: pnpm lint
      - run: pnpm type-check

  test:
    name: Test
    runs-on: ubuntu-latest
    needs: lint  # Lint が通ってからテストを実行
    steps:
      - uses: actions/checkout@v4

      - uses: pnpm/action-setup@v4
        with:
          version: 9

      - uses: actions/setup-node@v4
        with:
          node-version: '22'
          cache: 'pnpm'

      - run: pnpm install --frozen-lockfile
      - run: pnpm test -- --coverage

      # Codecovにカバレッジをアップロード（任意）
      - uses: codecov/codecov-action@v4
        if: always()
        with:
          token: ${{ secrets.CODECOV_TOKEN }}

  build:
    name: Build
    runs-on: ubuntu-latest
    needs: test  # テストが通ってからビルド
    steps:
      - uses: actions/checkout@v4

      - uses: pnpm/action-setup@v4
        with:
          version: 9

      - uses: actions/setup-node@v4
        with:
          node-version: '22'
          cache: 'pnpm'

      - run: pnpm install --frozen-lockfile
      - run: pnpm build

5-3. 自動デプロイ ワークフロー

main ブランチにマージされたら自動でデプロイするワークフローです（Vercelの場合は、GitHub連携で自動デプロイされるためワークフローは不要です）。

以下はCloudflare Pagesへの自動デプロイ例です。

name: Deploy

on:
  push:
    branches: [main]

jobs:
  deploy:
    name: Deploy to Production
    runs-on: ubuntu-latest
    permissions:
      contents: read
      deployments: write
    steps:
      - uses: actions/checkout@v4

      - uses: pnpm/action-setup@v4
        with:
          version: 9

      - uses: actions/setup-node@v4
        with:
          node-version: '22'
          cache: 'pnpm'

      - run: pnpm install --frozen-lockfile
      - run: pnpm build

      - name: Deploy to Cloudflare Pages
        uses: cloudflare/wrangler-action@v3
        with:
          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
          accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
          command: pages deploy out --project-name=my-project

5-4. Dependabot で依存関係を自動更新

.github/dependabot.yml を作成して、依存関係を自動で最新に保ちます。

version: 2
updates:
  # npm パッケージの自動更新
  - package-ecosystem: "npm"
    directory: "/"
    schedule:
      interval: "weekly"
    # PR数を制限
    open-pull-requests-limit: 10
    # コミットメッセージの形式
    commit-message:
      prefix: "chore(deps)"

  # GitHub Actions の自動更新
  - package-ecosystem: "github-actions"
    directory: "/"
    schedule:
      interval: "weekly"
    commit-message:
      prefix: "ci(deps)"

Dependabotが採用担当にアピールするポイント
依存関係が放置されたリポジトリは「メンテナンスされていない」という印象を与えます。Dependabotを設定しておけば、自動的にPRが作成されるため、定期的にマージするだけで「セキュリティ意識の高い開発者」と評価されます。

出典：GitHub Docs - Dependabot

6. IssueとPull Requestを活用する

6-1. なぜ個人開発でもIssueを使うのか

Issueは開発の計画と記録です。個人開発でIssueを使うことで、以下のメリットがあります。

  • 開発の意図が履歴として残る
  • タスク管理能力のアピールになる
  • PRとの紐づけで変更の理由が明確になる

6-2. Issue テンプレート

.github/ISSUE_TEMPLATE/bug_report.yml を作成します。

name: "🐛 バグ報告"
description: "バグを報告する"
labels: ["bug"]
body:
  - type: markdown
    attributes:
      value: |
        バグの報告ありがとうございます。以下の項目を記入してください。

  - type: textarea
    id: description
    attributes:
      label: "バグの概要"
      description: "どのような問題が発生していますか？"
      placeholder: "ログインボタンをクリックしても反応しない"
    validations:
      required: true

  - type: textarea
    id: steps
    attributes:
      label: "再現手順"
      description: "バグを再現する手順を記載してください"
      value: |
        1. '...' に移動する
        2. '...' をクリックする
        3. '...' までスクロールする
        4. エラーが発生する
    validations:
      required: true

  - type: textarea
    id: expected
    attributes:
      label: "期待する動作"
      description: "本来どのように動作すべきですか？"
    validations:
      required: true

  - type: textarea
    id: screenshots
    attributes:
      label: "スクリーンショット"
      description: "問題を説明するスクリーンショットがあれば添付してください"

  - type: dropdown
    id: environment
    attributes:
      label: "環境"
      options:
        - Chrome (最新)
        - Firefox (最新)
        - Safari (最新)
        - Edge (最新)
        - モバイル (iOS)
        - モバイル (Android)
    validations:
      required: true

.github/ISSUE_TEMPLATE/feature_request.yml も同様に作成します。

name: "✨ 機能リクエスト"
description: "新しい機能を提案する"
labels: ["enhancement"]
body:
  - type: textarea
    id: problem
    attributes:
      label: "解決したい課題"
      description: "どのような課題を解決したいですか？"
      placeholder: "〇〇する際に、毎回△△しなければならず不便"
    validations:
      required: true

  - type: textarea
    id: solution
    attributes:
      label: "提案する解決策"
      description: "どのように解決したいですか？"
    validations:
      required: true

  - type: textarea
    id: alternatives
    attributes:
      label: "代替案"
      description: "他に検討した方法があれば記載してください"

  - type: textarea
    id: additional
    attributes:
      label: "補足情報"
      description: "その他の情報やスクリーンショットなど"

6-3. Pull Request テンプレート

.github/PULL_REQUEST_TEMPLATE.md を作成します。

## 概要

<!-- このPRで何を行ったかを簡潔に記載 -->

## 関連Issue

<!-- closes #123 のように記載すると、マージ時にIssueが自動クローズされます -->
closes #

## 変更内容

<!-- 具体的な変更点をリストアップ -->
- 
- 
- 

## スクリーンショット

<!-- UI変更がある場合はスクリーンショットを添付 -->

## テスト

<!-- どのようにテストしたかを記載 -->
- [ ] ユニットテストを追加/更新した
- [ ] 手動テストで動作確認した
- [ ] 既存のテストが全て通ることを確認した

## チェックリスト

- [ ] コードがプロジェクトのスタイルガイドに従っている
- [ ] セルフレビューを行った
- [ ] 必要に応じてドキュメントを更新した
- [ ] 破壊的変更がないことを確認した

6-4. 実践的なワークフロー

個人開発でも以下の流れを徹底しましょう。

1. Issue を作成（何を・なぜ作るか）
      ↓
2. feature ブランチを切る
      ↓
3. コードを書く（コミットは細かく）
      ↓
4. Pull Request を作成（Issue と紐づけ）
      ↓
5. CI が通ることを確認
      ↓
6. セルフレビュー後にマージ
      ↓
7. Issue が自動クローズ

「個人開発だからIssueもPRも不要」は大きな間違いです
採用担当者がリポジトリを見たとき、IssueやPRが一切ないと「main に直接プッシュしている＝チーム開発の経験がない」と判断される可能性があります。たとえ一人でも、Issue → ブランチ → PR → マージ のフローを踏むことで、開発プロセスの理解度を無言でアピールできます。

7. ドキュメントを充実させる

7-1. アーキテクチャドキュメント

docs/architecture.md にプロジェクトの全体像を記載します。

# アーキテクチャ

## 全体構成図

```mermaid
graph TB
    Client[ブラウザ] --> NextJS[Next.js App Router]
    NextJS --> API[API Routes]
    API --> Prisma[Prisma ORM]
    Prisma --> DB[(PostgreSQL)]
    API --> Redis[(Redis Cache)]
    API --> ExtAPI[外部API]
    NextJS --> Vercel[Vercel CDN]
```

## 技術選定の理由

| 技術 | 選定理由 |
|:--|:--|
| Next.js (App Router) | SSR/SSG対応、SEO最適化、React Server Componentsによるパフォーマンス向上 |
| Prisma | 型安全なDB操作、マイグレーション管理、直感的なスキーマ定義 |
| PostgreSQL | JSONB対応、全文検索、信頼性の高いRDB |
| Vitest | Vite互換で高速、Jest互換API |

## ディレクトリ構成の設計意図

```
src/
├── app/          # ルーティングとページコンポーネント（プレゼンテーション層）
├── components/   # 再利用可能なUIコンポーネント
├── hooks/        # カスタムフック（ロジックの再利用）
├── lib/          # ビジネスロジック・ユーティリティ
├── types/        # 型定義
└── server/       # サーバーサイド専用コード（DB操作など）
```

7-2. ADR（Architecture Decision Records）

技術的な意思決定を記録する ADR は、設計力のアピールに最適です。

docs/adr/001-choose-nextjs.md の例：

# ADR-001: フレームワークにNext.jsを採用する

## ステータス

採用（Accepted） - 2026-03-20

## コンテキスト

本プロジェクトはSEOが重要なWebアプリケーションであり、
以下の要件を満たすフレームワークが必要である。

- SSR/SSGに対応していること
- React エコシステムを活用できること
- デプロイが容易であること

## 検討した選択肢

### 1. Next.js
- ✅ SSR/SSG/ISR に標準対応
- ✅ Vercelとの統合が容易
- ✅ App Routerによる最新のReact機能対応
- ⚠️ Vercelへの依存度が高い

### 2. Remix
- ✅ Web標準に忠実
- ✅ Nested Routesによる優れたデータ取得
- ⚠️ エコシステムがNext.jsより小さい

### 3. Astro
- ✅ 静的サイトのパフォーマンスが優秀
- ⚠️ 動的な機能が限定的

## 決定

**Next.js (App Router)** を採用する。

SSR/SSG対応、Reactエコシステムとの親和性、Vercelによる
容易なデプロイのバランスが最も優れているため。

## 結果

- App Routerを軸にした設計が可能になった
- Server Componentsにより初期読み込みを高速化できた

ADRは面接の話題にもなる
「なぜその技術を選んだのですか？」という質問はほぼ確実に聞かれます。ADRに記録しておけば、比較検討のプロセスを論理的に説明でき、設計力の高さをアピールできます。

8. デプロイとデモ環境

8-1. デモ環境が必要な理由

コードがどれだけ美しくても、動いているものを見せるのが最も説得力があります。

8-2. 無料で使えるホスティングサービス

サービス 最適な用途 無料枠 デプロイ方法
Vercel Next.js / React 100GB帯域幅/月 GitHub連携で自動
Cloudflare Pages 静的サイト / フルスタック 無制限帯域幅 GitHub連携で自動
Fly.io コンテナ / バックエンドAPI 従量課金（トライアルあり） fly deploy
Railway フルスタック / DB付き 30日間トライアル（$5） GitHub連携で自動
Render Webサービス / DB 無料インスタンスあり GitHub連携で自動
GitHub Pages 静的サイト / ドキュメント 100GB帯域幅/月 GitHub Actions
Supabase BaaS（DB / Auth / Storage） 500MB DB / 50K MAU ダッシュボードから

フロントエンドのおすすめはVercelまたはCloudflare Pages

  • Vercel: Next.jsとの親和性が最高。設定不要で自動デプロイ・プレビュー環境が使える
  • Cloudflare Pages: 帯域幅無制限。Workers統合でサーバーサイド処理も可能

バックエンドのおすすめはFly.ioまたはRender

  • Fly.io: Dockerコンテナをそのままデプロイ可能。東京リージョンあり
  • Render: GitHub連携が簡単。PostgreSQL無料枠あり

8-3. Dockerを活用したローカル開発環境

docker-compose.yml を用意することで、「docker compose up だけで動く」環境を提供できます。

services:
  app:
    build: .
    ports:
      - "3000:3000"
    environment:
      - DATABASE_URL=postgresql://postgres:password@db:5432/myapp
      - REDIS_URL=redis://redis:6379
    depends_on:
      db:
        condition: service_healthy
      redis:
        condition: service_started
    volumes:
      - .:/app
      - /app/node_modules

  db:
    image: postgres:17-alpine
    ports:
      - "5432:5432"
    environment:
      POSTGRES_USER: postgres
      POSTGRES_PASSWORD: password
      POSTGRES_DB: myapp
    volumes:
      - postgres_data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 5s
      timeout: 5s
      retries: 5

  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"

volumes:
  postgres_data:

Dockerfile の例：

FROM node:22-alpine AS base

# pnpm を有効化
RUN corepack enable

WORKDIR /app

# 依存関係のインストール（キャッシュ活用）
COPY package.json pnpm-lock.yaml ./
RUN pnpm install --frozen-lockfile

# ソースコードをコピー
COPY . .

# ビルド
RUN pnpm build

# 本番用ステージ
FROM node:22-alpine AS production
RUN corepack enable
WORKDIR /app

COPY --from=base /app/package.json /app/pnpm-lock.yaml ./
RUN pnpm install --frozen-lockfile --prod

COPY --from=base /app/.next ./.next
COPY --from=base /app/public ./public

EXPOSE 3000

CMD ["pnpm", "start"]

Dockerfileのマルチステージビルドを使いましょう
上の例のように、ビルドステージと実行ステージを分けることで、最終的なイメージサイズを大幅に削減できます。これも「本番運用を意識した構成」として評価されるポイントです。

9. 技術選定のポイント

9-1. ポートフォリオに最適な技術構成（2025〜2026年版）

「何を作るか」と同じくらい「何で作るか」は重要です。以下は、現在の市場で需要が高く、かつ個人開発で扱いやすい技術構成です。

フロントエンド構成

技術 推奨度 理由
Next.js (App Router) ★★★ 市場シェアNo.1、求人数が多い、SSR/SSG対応
React + Vite ★★★ SPA開発のスタンダード、学習コスト低
TypeScript ★★★ 型安全性、現在のフロントエンド開発では事実上必須
Tailwind CSS ★★☆ 高速なスタイリング、企業での採用率が高い

バックエンド構成

技術 推奨度 理由
Node.js + Hono ★★★ 軽量・高速、TypeScriptファーストなWebフレームワーク
Python + FastAPI ★★★ AI/ML連携に強い、型ヒントでドキュメント自動生成
Go ★★☆ 高パフォーマンス、マイクロサービスに最適
Node.js + NestJS ★★☆ エンタープライズ向け設計、DIコンテナによる高い保守性

インフラ・その他

技術 推奨度 理由
Docker ★★★ 環境構築の標準、どの現場でも使う
GitHub Actions ★★★ CI/CDの標準、GitHubと統合済み
PostgreSQL ★★★ 業界標準のRDB、JSONBで柔軟
Prisma ★★☆ 型安全なORM、マイグレーション管理が容易
Terraform ★★☆ IaCスキルの証明、AWSとの組み合わせで強力

9-2. テーマ選定のコツ

作るもの アピールポイント 難易度
タスク管理アプリ CRUD + 認証 + リアルタイム同期 ★☆☆
ブログ/CMSプラットフォーム SSG/ISR + MDX + SEO対策 ★★☆
ECサイト 決済連携 + 在庫管理 + カート ★★☆
チャットアプリ WebSocket + リアルタイム通信 ★★☆
ダッシュボード データ可視化 + API統合 + フィルタリング ★★☆
AIを活用したアプリ LLM API連携 + RAG + プロンプトエンジニアリング ★★★
CLIツール / OSSライブラリ npm公開 + テスト + CI/CD ★★★

「TODOアプリ」で終わらせない
TODOアプリはチュートリアルで作るものであり、ポートフォリオとしては弱いです。もし作るなら、認証（OAuth）・リアルタイム同期（WebSocket）・オフライン対応（Service Worker）・PWA化まで踏み込むと、差別化できます。

もっとも評価が高いのは 「自分が実際に困っていた課題を解決するアプリ」 です。面接で「なぜこれを作ったのか」を聞かれたとき、自分の体験に基づいた回答ができるため、説得力が全く違います。

10. やりがちなNGパターン

10-1. アンチパターン一覧

NGパターン なぜダメか 改善方法
READMEが空 / 初期状態 プロジェクトの内容が不明 セクション3のテンプレートを使う
.env をコミット 秘密情報の漏洩リスク .gitignore に追加 + .env.example を用意
node_modules をコミット リポジトリが巨大化 .gitignore に追加
コミットメッセージが fix update 変更内容が全く分からない Conventional Commitsを使う
main に直接プッシュ チーム開発のスキルが不明 ブランチ → PR → マージの流れを徹底
テストが一切ない コードの品質が不明 最低限のユニットテストを書く
ライセンスがない 他者が利用できない MITライセンスを追加
未完成のまま放置 やり切る力がないと判断される 小さくても完成させる
チュートリアルのコピペ 独自性がない 機能追加やカスタマイズで差別化
大量のリポジトリが未完成 散漫な印象 完成品を3つに絞ってピン留め

10-2. よくある間違い：APIキーのコミット

# ❌ すでにコミットしてしまった場合の対処法

# 1. まずAPIキーを無効化する（最優先！）
# → 該当サービスのダッシュボードでキーをローテート

# 2. .gitignore に追加
echo ".env" >> .gitignore

# 3. 履歴から削除（git filter-repo を使用）
pip install git-filter-repo
git filter-repo --path .env --invert-paths

# 4. リモートに強制プッシュ
git push --force --all

一度GitHubにプッシュした秘密情報は「必ず漏洩したもの」として扱ってください
GitHubの履歴は一般公開されており、たとえ数秒後に削除しても、ボットに取得されている可能性があります。先にAPIキーをローテート（無効化→再発行）してから、履歴を削除しましょう。

出典：GitHub Docs - リポジトリから機密データを削除する

11. GitHub プロフィールREADMEの作成

11-1. プロフィールREADMEとは

GitHubでは、自分のユーザー名と同じ名前のリポジトリに README.md を配置すると、プロフィールページにその内容が表示されます。

例：ユーザー名が miruky の場合 → miruky/miruky リポジトリの README.md

11-2. プロフィールREADMEのテンプレート

# Hi there 👋 I'm [あなたの名前]

## About Me

- 🔭 現在は **[プロジェクト名]** を開発しています
- 🌱 **[学習中の技術]** を学んでいます
- 💼 **[職種・経歴]** として活動しています
- 📝 **[Qiita / Zenn]** で技術記事を書いています

## Tech Stack

### Languages
![TypeScript](https://img.shields.io/badge/-TypeScript-3178C6?style=flat-square&logo=typescript&logoColor=white)
![Python](https://img.shields.io/badge/-Python-3776AB?style=flat-square&logo=python&logoColor=white)
![Go](https://img.shields.io/badge/-Go-00ADD8?style=flat-square&logo=go&logoColor=white)

### Frameworks & Libraries
![Next.js](https://img.shields.io/badge/-Next.js-000000?style=flat-square&logo=next.js)
![React](https://img.shields.io/badge/-React-61DAFB?style=flat-square&logo=react&logoColor=black)
![FastAPI](https://img.shields.io/badge/-FastAPI-009688?style=flat-square&logo=fastapi&logoColor=white)

### Infrastructure
![AWS](https://img.shields.io/badge/-AWS-232F3E?style=flat-square&logo=amazonaws)
![Docker](https://img.shields.io/badge/-Docker-2496ED?style=flat-square&logo=docker&logoColor=white)
![GitHub Actions](https://img.shields.io/badge/-GitHub_Actions-2088FF?style=flat-square&logo=github-actions&logoColor=white)

## GitHub Stats

![GitHub Stats](https://github-readme-stats.vercel.app/api?username=YOUR_USERNAME&show_icons=true&theme=radical)

![Top Langs](https://github-readme-stats.vercel.app/api/top-langs/?username=YOUR_USERNAME&layout=compact&theme=radical)

## Featured Projects

| プロジェクト | 説明 | 技術 |
|:--|:--|:--|
| [Project A](https://github.com/user/project-a) | 〇〇するアプリ | Next.js, Prisma, PostgreSQL |
| [Project B](https://github.com/user/project-b) | △△を自動化するCLI | Go, Cobra |

## Links

[![Qiita](https://img.shields.io/badge/-Qiita-55C500?style=flat-square&logo=qiita&logoColor=white)](https://qiita.com/YOUR_USERNAME)
[![Zenn](https://img.shields.io/badge/-Zenn-3EA8FF?style=flat-square&logo=zenn&logoColor=white)](https://zenn.dev/YOUR_USERNAME)

11-3. リポジトリのピン留め

GitHubプロフィールでは最大6つのリポジトリをピン留めできます。以下を意識して選びましょう。

優先度 選ぶべきリポジトリ
★★★ 最も完成度が高い個人開発プロジェクト
★★★ デモが動いていてREADMEが充実しているもの
★★☆ OSSへのコントリビューション実績
★☆☆ 技術ブログのリポジトリ（Zenn / Qiita連携）

ピン留めリポジトリ＝あなたの「名刺」です
採用担当者がGitHubプロフィールを見たとき、最初に目に入るのがピン留めされたリポジトリです。必ず最も自信のあるプロジェクトを選びましょう。

出典：GitHub Docs - プロフィールのカスタマイズ

12. おわりに

ここまでお読みいただきありがとうございます。

本記事で解説した内容を改めて整理すると、ポートフォリオとして評価されるリポジトリには以下の要素が揃っています。

要素 本記事のセクション
分かりやすいREADME（デモ・バッジ・セットアップ手順付き） 3. READMEの書き方
整理されたコミット履歴（Conventional Commits） 4. ブランチ戦略とコミットメッセージ
CIによる自動テスト・ビルド（GitHub Actions） 5. GitHub Actionsで自動化する
Issue → PR → マージの開発フロー 6. IssueとPull Requestを活用する
設計意図を記録したドキュメント（ADR等） 7. ドキュメントを充実させる
動くデモ環境 8. デプロイとデモ環境

完璧を目指す必要はありません。まずは1つ、完成度の高いリポジトリを作ることが最も重要です。
本記事のテンプレートを使って、今日から個人開発を始めましょう。

あなたのGitHubが「一緒に働きたい」と思われるポートフォリオになることを願っています。

ではまた、お会いしましょう。

参考リンク

GitHub 公式ドキュメント

コミット・README

ツール

ホスティング

60
65
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
Sign upLogin
60
65

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?