エンジニアのポートフォリオを作ろうと思っても、「何を載せれば経験が伝わるのか」「READMEにはどこまで書くのか」と迷うことがあります。作品数を増やすことだけが目的になると、見る人が知りたい担当範囲や動作確認の情報が見つからず、かえって強みを読み取りにくくなります。
ポートフォリオは、公開できる成果物と説明を通じて、何を考え、どこを担当し、どのように確認したかを読み手がたどれるようにするものです。この記事では、掲載作品の選び方、READMEの構成、画面や構成図の見せ方、公開前の安全確認を整理します。
エンジニアのポートフォリオで伝えること
ポートフォリオの役割は、作品を並べることではなく、読み手が成果物の目的や作り方を確認できる入口を用意することです。GitHubのREADMEは、プロジェクトが何に役立つか、利用者が何をできるか、どう使うかを説明する場所として案内されています。まず作品一覧から個別のREADMEへ進み、必要ならデモやコードを確認できる流れを作ります。
職務経歴書と成果物紹介の役割を分ける
職務経歴書は、担当業務、期間、役割、使った技術、得られた結果を応募先へ伝える文書です。一方、ポートフォリオは、公開可能なコードや画面、設計の説明を使って、その一部を具体的に確かめてもらう補助資料として整理できます。業務で作ったシステムをそのまま公開できるとは限らないため、公開許可のない情報をポートフォリオへ移してはいけません。
経験や担当範囲の整理方法は、職務経歴書・スキルシートの記事で扱っています。ポートフォリオでは経歴全体を繰り返すのではなく、選んだ成果物について「何を作ったか」「自分が何をしたか」「どこで確認できるか」を補います。
一覧からREADME・成果物へたどれる導線を作る
最初の画面には、作品名、短い説明、担当範囲、リポジトリやデモへのリンクをそろえます。作品が複数ある場合は、最初に見てほしいものを1〜3件程度に絞ると、読み手が選びやすくなります。件数は一律の正解ではなく、説明を読める分量と更新できる範囲から決めます。
公開リポジトリを使うなら、READMEをリポジトリの入口に置きます。GitHubはリポジトリ訪問者にプロジェクトの目的や使い方を伝えるものとしてREADMEを説明し、リポジトリ直下など所定の位置にあるファイルを表示します。公開前に、READMEが意図した位置に表示されているかを画面上で確認してください。
公開する作品を選び、自分の担当範囲を整理する
作品選びでは、規模や技術の新しさだけでなく、公開してよいこと、内容を自分の言葉で説明できること、読み手が概要を確認できることを基準にします。完成度を誇張するより、どこまで動き、何が未対応なのかを明確にする方が、説明と実物の食い違いを防げます。
公開できることと説明できることを基準に選ぶ
候補ごとに、目的、主な利用者、主要機能、自分の担当範囲、公開URL、現在の状態を書き出します。READMEやデモがなくても、追加できるかを考えます。説明が難しい外部ライブラリや複雑な構成を無理に盛るより、設計を選んだ理由と確認内容を説明できる作品を優先します。
業務成果物の場合は、会社や顧客との契約、秘密保持、公開許可、個人情報の扱いを確認します。コードを置き換えただけで機密性がなくなるとは限りません。画面、ログ、テストデータ、ドメイン名、構成図にも組織や個人を特定できる情報が含まれることがあります。判断できないものは公開せず、公開可能な題材で作り直す選択肢を検討します。
個人制作・共同制作・教材を基にした作品を区別する
共同制作では、チーム全体の成果と自分が担当した部分を分けて説明します。自分以外のコードをすべて自作したように書いたり、共同制作者の氏名や作業内容を同意なく公開したりしないよう注意します。教材やチュートリアルを基にした作品は、参考元を示し、追加・変更した点と元の内容を区別します。
「設計から実装まで一人で担当」「本番運用で利用」など、読み手が実績と受け取る表現は、事実に沿う場合だけ使います。学習用に動かしたものなら「学習用に作成」と記し、未実装の機能や未確認の動作は、そのまま未対応・未確認として扱います。
READMEに作品の目的・使い方・工夫をまとめる
READMEは、初めて見る人が概要をつかみ、必要なら手元で確認できる順序にすると読みやすくなります。すべての見出しが必須というわけではありません。デモを公開していない場合は無理にURLを作らず、動作確認の手順やスクリーンショットで何が分かるかを記します。
何を誰のために作ったかと主要機能を示す
冒頭では、作品の目的と解決したい課題を数行で伝えます。その後に、主要機能や操作の流れを簡潔にまとめます。「便利なアプリです」のような抽象語だけで終えず、誰がどの操作をすると何を確認できるのかを書きます。利用者像が仮定なら、実際の利用者がいるように表現せず「想定利用者」と明記します。
使用技術を採用理由と担当箇所に結び付ける
技術名を並べるだけでは、どこで使ったかが分かりません。言語やフレームワーク、DBなどを、役割・利用箇所・採用理由と合わせて説明します。バージョンを書く場合は、設定ファイルや実行環境で確認できた値を使います。依存関係を更新した後にREADMEだけ古いままにならないよう、公開前に照合します。
動かすための前提・手順・確認できる状態を書く
セットアップ手順には、必要なソフトウェア、環境変数の設定方法、起動コマンド、確認用URLなどを記載します。実際に初期状態から確認していない手順を「動作確認済み」と書いてはいけません。実行できない環境の場合は、確認していない範囲を明示します。認証情報は値そのものを例に含めず、`.env.example`などにはダミー値だけを置きます。
# プロジェクト名
何を解決するための作品かを2〜3行で説明します。
## 主な機能
- [機能名]: [確認できること]
## 担当範囲
- [自分が実装・設計した箇所]
- [共同制作の場合はチーム担当との区分]
## 使用技術
- [技術名・確認済みバージョン]: [使った場所と理由]
## セットアップ
1. [必要な前提条件]
2. [環境変数の用意。値は記載しない]
3. [実際に確認した起動手順]
## 確認方法
- [実施したテストや操作]
- 未確認の範囲: [あれば明記]
## 制約・今後の課題
- [現在できないこと、既知の制約]
## ライセンス・クレジット
- [選択したライセンスや利用素材の条件。未設定なら未設定と記載]このテンプレートを基に、作品に合わせて構成を調整します。当てはまらない見出しは省き、リンク先やコマンドが現状と一致するかを確認してから公開します。
工夫・確認結果・未対応の課題を分けて書く
工夫した点は「課題」「選択肢」「選んだ方法」「確認したこと」の順で書くと、判断の流れが伝わります。確認結果は実施したテストや手操作と対応づけます。測定値や性能比較を載せるなら、環境、データ量、測定方法、実行回数なども記録できる場合に限ります。測っていない「高速化した」「利用者が増えた」といった表現は避けます。
未対応事項を隠す必要はありません。現在の制約と、次に取り組む予定を分けて示せば、未完成の作品であることも正確に伝えられます。ただし、予定を実装済みの機能として一覧に混ぜないようにします。
画面と構成図で成果物を理解しやすくする
画像や図は、説明だけでは伝わりにくい操作や構成を補うために使います。画像の枚数を増やすより、何を見ればよいかをキャプションで示すことが大切です。表示中の個人情報や社内データ、実在ユーザーの情報が含まれないかも確認します。
主要な操作が分かる画面と説明を選ぶ
画面キャプチャを載せるなら、作品の目的が分かる画面、中心的な操作、その結果のうち必要なものに絞ります。スマートフォンやPCなど表示条件が重要な場合は、画面サイズや確認環境を記します。デモURLを用意する場合も、停止中の環境やログインが必要な画面で読者を迷わせないよう、アクセス条件や現在の公開状態を確認してください。
構成図で処理の流れと各要素の役割を示す
構成図は、実際の構成に合う範囲で、利用者からアプリケーション、DBや外部サービスへ至る流れを示します。使っていないクラウド製品やサービスを見栄えのために加えず、矢印の向きやデータの流れが実装と一致するかを確かめます。業務システムの構成を基にする場合は、公開許可や組織情報の露出を慎重に確認します。
作品一覧と説明を読み手の順序に合わせて整える
作品一覧は、読む人が短時間で概要を比較できるよう、各項目の粒度をそろえます。説明の長さや並び順は、見せたい経験と応募先に合わせて調整します。ポートフォリオ自体の装飾に時間をかけすぎず、リンク切れや説明の食い違いをなくすことを優先します。
一覧では概要・担当範囲・確認先をそろえる
一覧カードや表に、作品名、目的、制作時期（必要な場合）、担当範囲、主要技術、確認先を同じ順で置きます。書ききれない背景や判断は個別READMEへ移し、一覧には読み進めるための情報を残します。公開できるデモがない場合は、コードや説明文など、実際に確認できるリンクを案内します。
README・コード・デモの説明に矛盾がないか確かめる
READMEの機能一覧、画面、コード、デモが同じ状態を示しているかを確認します。機能を削除したのに説明が残っていないか、起動手順のコマンド名が変わっていないか、リンクが非公開リポジトリを指していないかを点検します。更新日を表示するなら実際の更新に合わせます。
ブランチやプルリクエストの説明も作品の開発過程を伝える材料になります。Gitを使った変更管理の基本は、Gitブランチ運用の記事を参照してください。
公開前に秘密情報・権利・閲覧状態を確認する
公開設定を変更する前に、リポジトリのファイルだけでなく、過去のコミット、Issue、画面、ログ、画像にも目を通します。公開リポジトリでは、見る人がコードを確認できるだけでなく、複製して手元へ保存できる場合もあります。一度公開した内容は、設定を非公開に戻すだけで第三者のコピーまで消せるとは限りません。
ファイル・履歴・画像・ログの公開内容を点検する
APIキー、パスワード、アクセストークン、秘密鍵、接続文字列、実データ、個人情報が含まれていないかを確認します。`.gitignore`に追加しても、すでにGitへ登録したファイルや過去コミットの値が自動で消えるわけではありません。GitHubのpush protectionなど利用可能な予防機能も検討できますが、検知機能を使っていても最終確認の代わりにはなりません。
認証情報を誤って公開した場合は、まず該当キーやパスワードを失効・ローテーションします。ファイルから消すだけでは不十分な場合があります。履歴の書き換えは共同作業者のcloneやブランチに影響するため、影響範囲と連携を確認してから進めます。
GitHubの案内でも、漏えいした秘密情報は先に無効化またはローテーションすること、履歴の書き換えには共同作業者との調整や副作用があることが説明されています。対応方法は漏えいした情報の種類や公開範囲によって変わるため、認証情報の管理者や組織の手順に従ってください。
業務成果物や共同制作物、素材の公開条件を確認する
業務のコード、社内資料、顧客データ、ロゴ、写真、フォント、教材コードなどは、公開・再配布してよいかを個別に確認します。公開リポジトリを作ったことだけで、すべてのコードや素材が自由に利用できるライセンスになったとは限りません。第三者の成果を含める場合は、ライセンスや利用条件、必要な表示を確認し、判断できないものは掲載しないでください。
リンク・表示・実行手順と実績の根拠を見直す
最後に、ログアウト状態や別ブラウザーなど読み手に近い条件で、公開ページ、README、画像、デモの閲覧可否を確認します。新しい環境から手順をたどれるか、必要な認証情報をREADMEへ書いていないか、実績の数値を説明できる記録があるかも見直します。チェックをしていない項目は「確認済み」とせず、公開を止めて解消するか、未確認であることを明示します。
GitHub Docs: About READMEs／Licensing a repository／Removing sensitive data from a repository／Push protection
まとめ
エンジニアのポートフォリオは、作品をたくさん並べることよりも、公開できる成果物を選び、目的・担当範囲・使い方・確認内容を読み手がたどれるように整えることが大切です。職務経歴書では経歴を整理し、ポートフォリオでは具体的な成果物の説明を補うなど、資料ごとの役割を分けます。
READMEや画面、構成図の説明は、実装や確認結果と一致させます。実績を誇張せず、未対応・未確認の範囲も明記してください。公開前には、秘密情報、過去の履歴、業務上の許可、共同制作者や素材の権利、閲覧状態を確認し、安全と公開条件を判断できない成果物は公開しないようにします。
コメント