ポートフォリオで伝えたい設計判断と改善の過程

先に結論

ポートフォリオでは、何を作ったかに加えて、誰のどの問題を想定し、どんな制約で設計を選び、何を検証したかを示します。代表作一つでも、本人の担当と改善の過程を説明できる構成に整えることが大切です。

• 最初に目的、デモ、本人の担当へ案内する。

• 採用案と見送った案を、作品の条件に照らして比較する。

• 検証済み・未検証・今後の予定を分け、公開情報と実行手順を確認する。

対象：エンジニア転職に向けて既存の個人制作・共同制作を整理する人。読書記録アプリは説明用の架空例です。採用企業による評価や提出要件は個別に異なります。

代表作は、画面の完成度と判断の説明を一緒に見せる

ポートフォリオを作るとき、目立つ機能や画面の美しさだけで作品を選ぶと、自分の仕事の進め方が伝わらないことがあります。代表作にしたいのは、目的、実装した範囲、選んだ方法、確かめた結果を自分で説明できる作品です。小さなアプリでも、利用場面から設計を考え、制約の中で判断した過程を示せれば、面接で話す材料になります。

最初に応募先の募集業務を読み、作品のどこを見てもらいたいかを決めます。画面開発の職種なら操作や状態の変化、サーバー側の職種ならデータ処理や異常時の扱い、運用に関わる職種なら設定や復旧手順などが説明候補です。一つの作品ですべての能力を証明しようとせず、今回の応募で話す中心を選ぶと説明が散らばりにくくなります。

公開した作品が採用でどの程度評価されるかは、企業や募集職種、選考の進め方で異なります。この記事は、提出すれば選考を通過する作品の条件を示すものではありません。既存作品を初めて見る人に、制作目的と本人の担当が伝わるよう整理するための実務的な提案です。提出を求められている場合は、指定された形式や公開方法を優先してください。

後半では、個人制作の読書記録アプリを架空例として説明します。実在する利用者への取材や、導入効果を測った事例ではありません。学習用の試作も、その前提を明記すれば目的と工夫を説明できます。経験を大きく見せるために利用者数や好意的な感想を作るのではなく、何を確かめられ、何が未検証かを分けて示しましょう。

想定する利用者を、具体的な一場面から説明する

「誰でも使える便利なアプリ」という紹介は広すぎて、機能を選んだ理由が伝わりにくくなります。例えば読書記録なら、読んだ冊数を集計したい人と、途中まで読んだ本を探したい人では、必要な画面が違います。代表する利用場面を一つ決め、「どんなときに、何を探し、どこで困るのか」を短い文にします。

架空例では、「複数の本を並行して読み、再開するときに読んでいた位置と自分のメモを探したい人」を想定します。この場合、書籍情報を大量に登録できることより、途中の本が分かり、前回のメモへ戻れることが中心になります。作品の冒頭にこの場面を書けば、一覧の並び順や入力項目をなぜそうしたのかを説明する土台になります。

実際の利用者に聞いていないなら、これは制作時の仮説だと明記します。自分自身が困った経験から始めた場合も、「自分の利用を想定した」と書けば十分です。利用者全体の要求を確認したような表現に変える必要はありません。誰かに試してもらったなら、人数を誇張せず、何を依頼し、どの操作を観察したかを記録します。

解決したいことが決まったら、今回は扱わないことも簡潔に残します。読書記録の例なら、書籍の売買、他の人との交流、出版社向けの管理は対象外です。見せる機能を絞るための境界が分かれば、未実装の機能が単なる作り忘れなのか、意図した範囲なのかを読み手が区別できます。範囲の説明は、次の設計判断にもつながります。

READMEの入口は、目的・使い方・見どころの順に整える

GitHubの公式資料は、READMEをプロジェクトの内容、有用性、使い始め方などを伝える場所として説明しています。ポートフォリオでも、リポジトリを開いた人が最初に読む案内として活用できます。細かな内部仕様へ入る前に、何を作ったか、どこで動作を見られるか、本人のどの工夫を見てほしいかを案内しましょう。 （出典：GitHub Docs｜リポジトリのREADMEファイルについて）

冒頭は数文で作品の目的を説明し、次にデモ、画面の説明、コードへの入口を置きます。共同制作なら、この位置に本人の担当も添えます。読む人がすぐに動かせない場合に備え、代表的な操作の画面と、何が起きているかの説明も用意します。画像だけでは状態の意味が伝わりにくいため、入力、処理、結果を短い文章で補います。

詳しい設定方法、データ構造、検証記録は、見出しで分けて必要な箇所へ移動できるようにします。最初の画面に説明をすべて並べる必要はありません。読む人が作品の概要をつかんでから、関心のある設計やコードへ進める構成を意識します。ファイル名だけのリンクより、「入力を検証する処理」のように内容が分かる案内の方が辿りやすくなります。

更新した日と、説明している版を合わせておくことも大切です。画面が古く、実際のデモでは項目が変わっていると、作品の理解を妨げます。大きな変更のたびに全部の説明を書き直すのではなく、冒頭、操作例、環境設定のどこに影響するかを見直しましょう。リンク切れと説明のずれは、応募前の確認で優先して直す項目です。

構成図は、データが通る経路と責任の境界を示す

構成を説明する図に、使ったサービスのロゴをたくさん並べても、役割が分からなければ読み手は判断できません。まず、利用者の操作がどこへ届き、どの処理がデータを読み書きし、結果をどう返すかを整理します。小さなアプリなら、画面、サーバー、保存先の関係から始めるだけでも、主要な処理を説明できます。

図には、作品の中で実装した部分と、外部サービスへ任せた部分を分けて表示します。ログインや通知を外部へ任せたなら、その事実を示し、自分が実装した認証基盤のように書かないようにします。連携時に自分が扱った設定、失敗時の案内、権限の確認などは、別途本人の担当として説明できます。利用したことと作ったことを混同しない構成にします。

データが保存される場所以外に、どこで入力を確認するか、誰のデータを表示するかも説明候補です。図を複雑にせず、読み手が一つの操作を追えることを重視してください。内部の全関数を並べる必要はありません。詳しく見てほしい処理があれば、その部分だけ別の図や短い文章で補足すると、概要と実装を往復しやすくなります。

公開用の図には、実際の秘密情報や管理画面の識別子を載せる必要はありません。値を省略しても、どの種類の設定が必要かは説明できます。勤務先の構成を流用する場合は特に注意し、公開してよいと確認できないものを使わないようにします。自分の学習用作品は自分の構成として示し、実務システムの実績に見える表現を避けてください。

技術を選んだ理由は、見送った案との比較で説明する

「人気があるから」「高速だから」という理由だけでは、作品の条件との関係が分かりません。実装に使える時間、想定するデータ量、自分が保守できる範囲、学びたい内容などを先に書きます。その条件で何を選び、どんな手間を引き受けたかを示すと、技術の一般論ではなく、自分の判断を説明できます。

例えば架空の個人制作で、検索機能のために別の検索サービスを導入する案と、既存の保存先の機能で始める案を検討したとします。まだ小さな試作で、まず読書メモを探す操作を確かめたいなら、構成を増やさず作る判断も考えられます。ただし、検索条件や扱う量が増えたら再検討する、と条件を添えます。どちらの案も無条件に優れているとは説明しません。

学習を目的に、あえて慣れていない技術を選ぶ場合もあります。その場合は、最短で作るための選定ではなく、その技術で何を学ぶかを目的にしたと明記します。運用コストだけで説明すると不自然になる選択でも、学習目的が分かれば読み手は判断の前提を理解できます。学んだ点と、まだ自力で説明できない点を分けて残してください。

見送った案は全部書く必要はありません。作品の設計を理解するのに役立つ比較を一つ選びます。採用理由だけでなく、採用した案の弱点、回避できなかった制約、見直す条件も記載します。実際には検討していなかった別案を、制作時に厳密に比較したかのように追加するのではなく、後からの振り返りならその時点も示しましょう。

データの設計は、入力から更新・削除まで一つの例で追う

データ構造を表で見せるなら、項目の一覧だけでなく、どの利用場面で必要になるかを説明します。読書記録の架空例では、本の情報と、利用者が書く読書メモを別に扱うかが判断点になります。一冊に複数のメモを残す場合、後から同じ本へ戻る場合、誤って登録した本を削除する場合を想像すると、必要な関係を考えやすくなります。

また、同じ題名の本や、同じ本を二度読む場合に何を同一とみなすかも説明できます。題名だけで重複を判定するのか、版や識別情報を扱うのか、個人の読書記録を別に作るのかで動作は変わります。試作で決めていない点は未対応として残し、その制約が操作にどう影響するかを書きます。想定していない機能まで完成したように見せないでください。

入力が正常な場合だけでなく、空の値、不正な値、保存中の再操作、削除後の参照も確認します。どこで検証し、失敗したときに何を表示するかを一つの操作に沿って説明すると、データと画面のつながりが伝わります。専門的な用語を増やすより、利用者の操作を始点にして、実装がその操作をどう扱ったかを示しましょう。

図や表を作った後は、実際のコードと一致するか確認します。説明資料を整える過程で理想的な構成を書いてしまい、現状の実装が追いつかないことがあります。現在の構造、検討中の変更、まだ作っていない機能を分ければ、未完成な点も次の改善計画として話せます。完成度を装うより、現状を正確に説明できる方が対話を進めやすくなります。

検証結果は、操作・期待する状態・実際の結果を揃える

「テスト済み」と一行だけ書くと、どこまで動くことを確認したのか分かりません。代表的な操作を選び、どんなデータを用意し、どんな状態になることを期待し、実際にどうなったかを記録します。動作環境や確認した版も添えれば、後から変更があったときに、どの結果をもう一度確認するべきか分かります。

読書記録の架空例なら、本を登録してメモを保存し、一覧へ戻って再度開く流れが通常の確認です。次に、メモが空の場合、保存に失敗した場合、対象を削除した後に古いリンクを開いた場合を確かめます。正常に使えた画面だけでなく、エラー後に利用者が何をすればよいかまで考えると、実装上の工夫を説明しやすくなります。

自動テストがあるなら、何を機械的に確認し、何を手動で見たかを分けます。件数だけを前面に出すより、入力の検証、データの更新、画面の主要操作など、守ろうとした振る舞いを示してください。すべての条件を確認したように見せず、外部サービスの実際の障害や大量アクセスなど、再現していない条件も明記します。

不具合が見つかった場合は、再現条件、原因として確かめたこと、修正、再確認を一組で残します。初めから不具合がなかったように履歴を整える必要はありません。原因がまだ分からない場合は、その状態を記録し、推測と確認済みの情報を区別します。採用担当者が後で同じ操作をしたときにも、既知の制約だと分かる説明があると親切です。

架空の読書記録アプリ：検証項目の設計例（実施結果ではありません）

改善履歴は、変更前の困りごとと確認方法を残す

改善を伝えるには、追加した機能名より、何が使いにくかったかを示します。例えば、読書メモを保存した後に結果が分からず、同じ操作を繰り返してしまう問題を見つけたとします。変更内容は保存状態の表示やボタンの扱いですが、説明したいのは、その変更によってどの迷いを減らそうとしたかです。

誰かに試してもらった場合は、自由な感想と観察した操作を分けます。「使いやすいと言われた」だけで全体の改善効果を結論付けず、「保存後に再度ボタンを押した」「一覧への戻り方を質問された」といった観察を残します。少人数での試行なら、利用者全体に同じ問題が起きると断定せず、次に確かめる仮説として扱います。

変更後の確認も、同じ利用場面に戻して行います。以前は迷った操作が今回どうなったかを見ないと、新しい見た目になっただけかもしれません。計測していないのに操作時間の削減率を書く必要はありません。改善を判断した根拠が、自分の試行なのか、第三者の操作観察なのか、自動テストなのかを区別して説明してください。

改善履歴は日付の一覧だけでなく、重要な一件を詳しく残す方法が使えます。発見した問題、変更した理由、残っている制約をまとめると、面接で話す起点になります。制作後に見直したことがない作品なら、応募前に一つの操作を改めて確認し、説明不足や動作の問題を直すところから始められます。更新回数を増やすこと自体は目的ではありません。

共同制作とAIの支援は、本人が担当した範囲を示す

共同制作の作品は、全体の成果と本人の担当を分けて見せます。画面、API、データ設計、テスト、進行管理などのうち、どの部分を主に担当し、どの部分を他の人と相談したかを書きます。チームの人数だけでは役割は伝わりません。本人が説明できる処理や、やり取りした論点へ案内すると、共同制作の中での仕事が見えます。

他の人のコードをレビューした場合も、作成者のように紹介せず、確認した観点を示します。自分の変更が別の担当領域へ影響したなら、どのように相談して調整したかも説明候補です。意見が分かれた場面を使うときは、相手の能力を評価する話へ広げず、制約、選択肢、決め方に焦点を置きます。

生成AIを使った場合は、画面案、コードの下書き、テスト案、文章の整理など、支援を受けた範囲を説明できるようにします。そのうえで、本人が何を確認し、どこを修正し、どんな問題を見つけたかを残します。生成されたコードをそのまま使い、動く理由や制約が分からない部分があるなら、説明できる状態へ読み直すことが先です。

応募先がAI利用の申告や制作条件を指定している場合は、その条件に従います。作品を自力で全部書いたように見せる必要も、補助を使ったという理由だけで自分の判断を省く必要もありません。本人が担った設計、確認、修正の範囲が読み手に分かることを重視してください。共同制作の公開については、他の参加者の成果を掲載してよいかも確認しましょう。

デモは、初めて来た人が試せる状態で用意する

自分の環境で動くことと、初めて開いた人が試せることは別です。応募前に、開発者としてログインした状態を離れ、一般の閲覧者として入口を確認します。必要な操作、試してよいデータ、戻り方が分かるでしょうか。初期データがないため真っ白になる画面なら、デモ用の記録を用意するか、空の状態で何をすればよいかを説明します。

デモ用アカウントを用意する場合は、本番や管理用の権限から切り離し、架空のデータだけを扱えるようにします。誰でも変更できる共有デモなら、他の閲覧者の操作で内容が変わる前提も考えます。自由に情報を入力させる必要がなければ、操作できる範囲を絞る方法があります。採用担当者に実際の個人情報や決済情報の入力を求めない構成にしましょう。

外部サービスの停止や無料枠の制限で常時動かせないなら、デモが利用できない場合の説明を用意します。代表画面、短い操作動画、実行手順などが候補です。ただし、録画だけで現在も稼働しているように見せず、記録した日や対象の版を示します。画面を見られることと、コードを実行して検証できることを別の入口として案内してください。

説明を読むために長い環境構築を要求しないことも大切です。詳しい評価のために実行する人へは必要な手順を提供し、まず作品を知りたい人へは概要と画面を用意します。二つの読み方を分けると、設定の説明を省きすぎず、初めて見る人の負担も抑えられます。リンク先が開くかは、提出する資料から辿って確認しましょう。

実行手順には、環境・設定・確認方法まで含める

コードを公開するなら、取得後に何をすれば動作するかを書きます。必要な実行環境、依存関係の導入、設定値の用意、起動、最初の画面の確認を順番に整理します。自分の端末に既に入っている道具を前提にすると、別の人が途中で止まりやすくなります。新しい作業場所で手順を試し、説明に書いていなかった準備がないか確かめてください。

設定値の例は、意味が分かるダミーの値にし、本物の認証情報を同梱しないようにします。外部サービスのアカウントが必要なら、その旨と、どの機能が依存するかを書きます。すべてを用意しなくても一部の画面を試せる場合は、その範囲を案内できます。実行できない理由が、手順不足なのか、意図した依存条件なのかを読み手が判別できることが重要です。

テストの起動方法、終了方法、デモデータを戻す方法も、必要に応じて加えます。特にデータ削除や初期化を伴う操作は、どこに影響するかを説明してください。実行手順の途中で、読み手の既存データへ予想外の変更が起きる構成は避けます。作業専用の環境で試せるようにすると、確認する側も取り組みやすくなります。

依存関係や環境を更新したときは、説明した手順がそのまま使えるかを確かめます。「最新版を入れる」だけでは、確認した環境と違う組合せになることがあります。検証した版を残し、更新していない制約を示しましょう。動作する条件を明確にすることは、どんな環境でも動くと主張することより、作品の状態を正確に伝える助けになります。

公開前に、画像・コード・履歴に含まれる情報を点検する

公開の確認は、今のコードだけで終わらせず、設定ファイル、過去の履歴、画面に映る情報も対象にします。認証情報、個人の連絡先、勤務先や顧客の資料が混ざっていないかを見ます。画像で一部を隠したつもりでも、別の画面や説明に同じ情報が残っていることがあります。公開予定のファイルをまとめて確認する作業を、提出前に一度設けましょう。

もし認証情報を公開してしまった場合、現在のファイルから文字を消すだけで対応を終えないことが重要です。GitHubの公式資料は、公開されたシークレットへの初動として失効や更新を検討し、履歴を書き換えても他のコピーなどに残る可能性があることを説明しています。具体的な対応は、影響するサービスの手順と関係者の管理ルールに沿って進めてください。 （出典：GitHub Docs｜リポジトリからの機微なデータの削除）

画像、フォント、素材、他の人のコードを使ったときは、出所と利用条件を確認します。公開されているという理由だけで、自分の作品として再配布できると判断しないようにします。必要な表示を残し、ライセンスや利用条件が不明な素材は置き換えを検討します。学習用の参考実装を使ったなら、その範囲と自分が変更した部分を説明すると、担当が明確になります。

仕事の成果を紹介できない場合は、機密情報を削ったコピーを安易に公開するより、別の学習用作品や、開示可能な範囲の説明を使う方法があります。許可が確認できない成果物は載せず、面接で話せる内容も事前に整理します。公開しないという制約を理由に担当を誇張する必要はありません。何を説明できるかを決めてから資料を作りましょう。

未実装の機能は、取り組む条件と優先順位を示す

残っている課題をすべて「今後の展望」として並べると、どれが現在の不具合で、どれが新しい機能なのか分かりにくくなります。まず、現状の利用を妨げる問題、使い勝手の改善、対象を広げる新機能を分けます。動作を壊す問題があるなら、紹介文の奥に隠さず、試す前に分かる位置で制約を案内します。

優先順位は、影響する操作と確認した根拠を使って説明します。読書記録の架空例なら、保存失敗が分からない問題を、交流機能の追加より先に扱う判断が考えられます。これはすべてのアプリに共通する優先順位ではなく、その作品の中心である記録と再開を成立させるための選択です。制作目的へ戻って判断すると、説明に一貫性が出ます。

規模が大きくなったら必要になる設計も、現状の問題と混ぜずに書きます。例えば検索を別の仕組みへ移すなら、どの操作やデータ量で現在の構成を見直すかを検討事項として残します。まだ計測していない閾値を断定する必要はありません。「対象データを増やして応答を測り、その結果で判断する」という次の検証を示す方法があります。

作業予定を示すなら、完成日を無理に約束するより、次に確認する仮説と完了とみなす状態を決めます。応募時点で実装済みなのか計画なのかが分かれば、面接で現状を共有できます。将来作る機能が多いことより、今ある作品をどう改善していくかを説明できることに焦点を置きましょう。

面接用には、一つの操作と一つの判断を説明できるようにする

作品の紹介は、最初に目的と本人の担当を伝え、代表的な操作を一つ見せ、その裏側の判断を説明すると整理しやすくなります。すべての画面を順番に案内する必要はありません。時間が短い場合でも、作った理由と自分が考えたことが残るようにします。詳しいコードは、質問が出たときに該当箇所へ進める状態にしておきます。

架空の読書記録アプリなら、途中の本を開いてメモを追記し、保存結果を確認する流れを見せます。その後、「保存できたか分かりにくかったため、処理中と完了の状態を分けた」と判断を説明できます。画面の見た目、データの保存、失敗時の案内が一つの操作でつながるため、話題を広げたいときにも同じ例を使えます。

デモが動かない場合に備え、同じ操作を示す画像や説明へ切り替えられるようにします。動作を保証するために未確認の状態を隠すのではなく、既知の制約と代替の資料を案内する準備です。最後に「見送った案」「検証していない条件」「次に直すこと」を説明できるか確かめます。この三つは、実装を振り返る良い問いになります。

提出直前には、応募資料のリンクから入り、概要、代表操作、本人の担当、構成、検証、実行手順が辿れるかを確認してください。下の表で未確認の項目を埋めれば、作品数を増やさなくても説明の質を上げられます。新作を急ぐ前に、既存の代表作を初めて見る人の目線で整えることが、次の面接準備につながります。

代表作を提出する前の確認表

比較するときの確認項目

• 想定利用者と制作目的を説明しているか

• 自分が判断した設計とその理由があるか

• 共同制作の担当範囲を示しているか

• 公開情報と閲覧・実行手順を確認したか

次に進めること

代表作の紹介文を「目的／構成／選んだ理由／改善した点」の順に作りましょう。面接では画面を見せながら、この四点を自分の言葉で説明できるように準備します。

参照先

• GitHub Docs｜リポジトリのREADMEファイルについて

• GitHub Docs｜リポジトリからの機微なデータの削除

あわせて読む

• 職務経歴書に開発経験を書くときの整理方法

• 技術面接に向けて過去のプロジェクトを振り返る

• 未経験分野への転職で整理したい既存スキル