私が務めていた会社はいわゆるSES企業で、複数の業務委託を経験しました。

未経験や文系でも見込みがあれば雇い、充実な研修制度で育て上げてくれる会社で、
私は大学は情報系ではあるものの特にインターン経験も実務経験もなかったのですが、ここまで育て上げてくれました。

この会社ではたくさんの素敵な人と出会えましたが、今回転職を決意したわけで、そのきっかけを書いてみます。

転職を考えたきっかけ

これからの自分のキャリアを考え始めた。

私は光栄なことに昨年に技師という役職をいただきました。
技師は技術で他社員を牽引することが求められます。

私は自己研鑽欲が強いものの、一人だとなかなか継続する意思を強く持てないところがあります。
そのため、みんなを巻き込む形で、これまで勉強会や読書会などの積極的に活動を行ってきました。
そういった活動を評価していただき役職をいただきました。本当に嬉しいことです。

そして、役職をいただいたことで私は考えたのです。

ーーいまの私は「技術」で「牽引」することができているのか。

確かに技術は好きで、新しい技術記事を読み漁ったり、試したり、質の高いコードや設計を考えるために本を読んだり…といったことはします。ですが、ふと自身を見返して考えたとき、体系的に人に教えられるような知識を持っている自信がなく、「技術」で秀でている自覚が持てなかったのです。

私の以前までの自身の評価は、今まで会ってきた先輩や先方のエンジニアとの相対評価で構成されていました。他人と比較しすぎるのは良いことではありませんが、それでもエンジニアとしての市場価値、一般的な価値がどのくらいなのかは気になります。

技師を名乗るのであれば、今見ている範囲に閉じてはダメだ。そう思ったのが活動を始めたきっかけでした。

活動をする上で、複数のカジュアル面談に挑戦しました。

他の会社にはどういうエンジニアがいるのか、どんな技術力を持っているのかを知りたかったのです。
そしてできれば外の世界での自分の相対位置を知りたかった。

カジュアル面談をする上で、自身のスキルを棚卸しできたのもとても良かったです。
今までどういう案件をやってきたか、そこで経験したこと、自分ができることを見つめ直すことができました。

カジュアル面談をする上で副業で雇ってもよいという会社とも御縁をいただき、1エンジニアとして挑戦することもできました。

一緒に働いて行きたかった後輩が辞めた

私が4年目のときにとても有望な後輩が入ってきました。
しばらくあとで同じ案件に配属され、いくつか一緒にプロジェクトを進めました。

私と同じで技術に対するこだわりと向上心があり、彼と設計の話をするのは楽しかったものです。
3年も歳が離れていますが、とても優秀で、彼から学びを得たことも数え切れないほどです。

数年後、彼と一緒に技師としてこの会社の技術力を背負って行き、もっと仲間を増やすことをモチベーションに感じていたある日、彼が転職を決意したと話を聞きました。

ーーあぁ、人は辞めるんだな。

思いました。今後また有望な若手が入ってきたとしても、その人がずっと居てくれるか分からない。
いま在籍している尊敬できる先輩も、いつまで居るか分からない。

人に、会社に、依存するのは良いことではないと考えることができました。

もちろん、その後輩やお世話になった先輩とは辞めたあとも仲良くしたいと思っていますし、今後また一緒に働く機会にでも恵まれたら嬉しいなとは思います。

しかし、私は私として誇れる自分になり、人から会社から自立しなくてはと思ったのです。

同じ景色を見てくれる人が見つからなかった

前述した2つのきっかけでも触れたように、私は「技術」を強みにしたキャリアを築きたい欲求と、それを「仲間と一緒」に研鑽し、成し遂げたい欲求があります。一人で頑張り抜けるほど強い人間では全くなく、隙あらばだらけてしまう人間だから。

思い返してみれば、私のこういった思考は会社の中では最初から少し浮いていたように思います。新人のときに計画した部門横断の学んだこと共有会は数回で頓挫した苦い経験もあります。もちろん、これが良い悪いを語りたいわけではないです。人それぞれ大事にしたいことは違うし、スタンスも違います。ただ違うというだけ。

そういった環境で一緒に同じ景色を見て走ってくれる人が見つけるのが、大変でした。

全く見つからなかったわけではないです。私の考えに同意を示してくれる人、活動に協力してくれる人は居ました。
そういった人たちとともに切磋琢磨し、活動し、ときには失敗したのはとても良い経験です。賛同してくれた方々には本当に感謝しています。

しかし、人は辞めます。そして人を変えることは出来ません。
自分が、特定の人や会社などの環境に依存することなく、自分でやりたいことを満たせる人間になろうと考えました。

最後に

今回、初めての転職ということで文章を書いてみました。

文章を書くことは得意ではなく、今回は特に想いのまま綴ったため読みづらい文章だったかと思います。
ここまで読んだくださった方、大変ありがとうございます。

明日から転職先として御縁をいただいた会社で再スタートとなるため、少ししたら入社エントリも書いてみたいと思います。
日々自分の限界を超えるような挑戦の毎日だと思いますが、自分のペースで頑張っていきます。

背景

スライドを Web 公開するサービスには以下がありますが、どうにも私は UI が好きではなくて…

• Slideshare
• Speakerdeck
• Docswell

特にスマホで閲覧する際、ナビゲーションボタンが大きすぎてスライドの内容が見づらいと感じていました。

Docswell は他の 2 つよりシンプルな UI で、日本人の開発者によるサービスということもあり、個人的には応援したいサービスです。

Slidev の紹介

Slidev は、Markdown で記述した内容をスライドとして表示できるツールです。Qiita や VSCode の拡張機能、Obsidian でも同様の機能がありますが、 Slidev の最大の強みは 拡張性と汎用性の高さ です。

• カスタマイズ性が高い：テンプレートを用意すれば、統一感のあるデザインのスライドを作成可能
• Vue.js コンポーネントを埋め込める：独自のインタラクティブ要素を追加できる
• 発表者モードや Picture-in-Picture などの機能：発表時に便利な機能が充実

ローカル環境で npm run dev を実行すればスライドを確認でき、ビルドすれば SPA としてホスティングも可能です。

今回は 公式ドキュメント を参考に、Slidev をブログに組み込んでみます。

使用要素

今回使用する主な技術スタックは以下のとおりです。

• Slidev
• Vue.js
• pnpm workspace
• Markdown / YAML Front Matter
• GitHub Pages
• GitHub Actions

ディレクトリ構成

├── list.mjs
├── package.json
├── packages
│   ├── 221124-name-development
│   │   ├── index.html
│   │   ├── node_modules
│   │   │   └── slidev-theme-one -> ../../theme
│   │   ├── package.json
│   │   ├── pages
│   │   │   └── title.md // タイトルスライド
│   │   ├── public
│   │   │   └── {画像ファイル}
│   │   └── slides.md // スライド本体
│   ├── 221208-extends-disadvantage
│   ├── {YYMMDD}-{title}
│   └── theme
│       ├── README.md
│       ├── layouts
│       │   ├── cover.vue
│       │   ├── default.vue
│       │   ├── fact.vue
│       │   ├── intro.vue
│       │   └── splash.vue
│       ├── package.json
│       └── styles
│           ├── index.ts
│           └── layout.css
├── pnpm-lock.yaml
└── pnpm-workspace.yaml

発生した課題とその解決策

Slidev はデフォルトで 1 スライド＝1 npm package という構成になっているため、通常はスライドごとに別々のリポジトリを作成する必要があります。複数スライドを作ろうと思ったらその都度リポジトリが増えるわけですね。それは嫌だ…

この問題に対して、以下の 2 つの方法を検討しました。

1. 1 つのスライドで頑張る（不採用）

複数スライドを 1 つにまとめて、リンクでジャンプできるようにする方法です。しかし、スライドが増えるほど管理が大変になるため、不採用としました。

2. モノレポ構成にする（採用）

pnpm workspace を使用し、複数のスライドを 1 つのリポジトリで管理する方法を採用しました。以下の記事を参考にしています。先駆者が既に開拓してくれていました。ありがたい。

• Slidev をモノレポで管理する
• GitHub Actions で Slidev をデプロイする
• 本気の登壇をSlidevでやってみて感じた「のびしろ」

資料に加えて、今回調整したポイントを少しだけ紹介します。

packages:
- "packages/*"

packages/ ディレクトリ配下の任意のディレクトリをワークスペースで管理します。

{
  "scripts": {
    "build": "pnpm run -r build",
  }
}

ルートの package.json のビルドコマンドでは、ワークスペースで管理している個別パッケージの build コマンドを並列実行します。

{
  "scripts": {
    "dev": "slidev --open",
    "build": "slidev build --out ../../dist/221124-name-development --base /slides/221124-name-development"
  }
}

個別パッケージでは build コマンドにおいて出力先ディレクトリを、個別パッケージの外の /dist に設定しています。また、base を /slides/221124-name-development に設定することで、パス解決が失敗しないようにします。

ディレクトリ名を直接指定するのはイケてないですね。ここを自分で書くのは大変なので、template 作成用のスクリプトを用意するか、勝手に取得するように改善したいです。

dev は開発用のコマンドです。個別パッケージのディレクトリ配下で実行して表示確認をします。

調整したのはこのくらいですが、モノレポ構成にしたことで後述するいくつかの問題が発生しました。ここからはその解消をしていきます。

課題②：画像のパスがずれる

Slidev は base 設定を使ってルートパスを変更できますが、YAML Front Matter の image パスには適用されません。そのため、不格好ですが sed コマンドを使ってビルド前に md ファイルを直接書き換えました。

{
  "scripts": {
    "fix:image": "find ./packages -name '*.md' | xargs sed -i 's/image: \"\\/public/image: \"\\./g'"
  }
}

※ MacOS では sed -i '' のようにオプションを調整する必要があります。

課題③：サムネイル用の画像が上手く生成できない

サムネイル用に title.md だけ PNG エクスポートさせて、その画像を利用したかったのですが、なぜかタイトルページ単体のエクスポートでは画像が適用されませんでした。

そのため、1 ページ目以外は無駄なのですが全ページを PNG 出力することにしています。

export を実行するには Playwright が必要なので、ローカルで実行する際は必要に応じて pnpm exec playwright install などでインストールします。

ちなみに、png や pdf のエクスポートのコマンドは提供されていますが、dev コマンドで立ち上げた後に画面上の機能から生成する方法が推奨されているようです。今回は CI で自動生成させたいのでコマンドを利用します。

課題④：ブログサイトから動的に参照させたい

ブログサイトからスライドを動的に取得するため、以下の 3 つを用意しました。

1. GitHub Pages をホスティングとして利用
2. GitHub Actions でスライドを自動デプロイ
3. スライドの一覧を JSON で提供する疑似 API

以下ワークフローの設定内容です。

name: Deploy pages
on: push
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - uses: actions/setup-node@v2
        with:
          node-version: '18'
      - name: Install pnpm
        run: npm install -g pnpm
      - name: Cache pnpm modules
        uses: actions/cache@v4
        with:
          path: ~/.pnpm-store
          key: ${{ runner.os }}-pnpm-${{ hashFiles('**/pnpm-lock.yaml') }}
          restore-keys: |
            ${{ runner.os }}-pnpm-
      - name: Install fonts
        run: |
          sudo apt-get install fonts-noto-cjk
      - name: Setting locale
        run: |
          sudo locale-gen ja_JP.UTF-8
          sudo update-locale LANG=ja_JP.UTF-8
      - name: Install dependencies
        run: pnpm install
      - name: Modify path to public
        run: pnpm run fix:image
      - name: Build all packages
        run: pnpm run -r build
      - name: Install Playwright browsers
        run: pnpm exec playwright install chromium
      - name: Export PNG for all packages
        run: pnpm --workspace-concurrency=1 run -r export:png
      - name: Generate index page
        run: pnpm run generate:index
      - name: Deploy pages to GitHub Pages
        uses: crazy-max/ghaction-github-pages@v2
        with:
          build_dir: dist
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Export PNG for all packages のステップでは、並列実行させるとエラーが発生しました。確かな原因は分からなかったので、ひとまず --workspace-concurrency=1 で同時実行数を 1 に指定することで回避しています。

API サーバーですが、このためにサーバーを建てたくはなかったので、GitHub Pages を擬似 API サーバーとして利用する方法を採用しました。

ビルドのタイミングでしかデータは動かないので、簡単な JS を書きスライドの一覧を JSON 形式で index.html として出力します。あとは取得側で 'Content-Type': 'application/json' として解釈してデータを取得すれば、ものぐさ API サーバーの完成です。

import fs from 'fs';
import path from 'path';

const baseUrl = 'https://koukibuu3.github.io/slides';

function getDirectoryContents(dirPath) {
  const contents = fs.readdirSync(dirPath, { withFileTypes: true });
  return contents.map(dirent => {
    if (!dirent.isDirectory()) return null;

    const indexHtml = fs.readFileSync(path.join(dirPath, dirent.name, 'index.html'), 'utf8');
    const title = indexHtml.match(/<title>(.*) - Slidev<\/title>/)?.[1] || dirent.name;

    return {
      title,
      url: `${baseUrl}/${dirent.name}`,
      mainImagePath: `${baseUrl}/${dirent.name}/images/1.png`
    };
  });
}

function main() {
  const directoryContents = getDirectoryContents('./dist');
  const jsonOutput = JSON.stringify(directoryContents, null, 2);
  console.log(jsonOutput);
  fs.writeFileSync('./dist/index.html', jsonOutput);
}

main();

まとめ

Slidev を使い、ブログにスライド閲覧機能を組み込む方法を紹介しました。

• Markdown でスライドを作成
• モノレポ構成で管理しやすくする
• GitHub Pages でホスティングし、GitHub Actions で自動デプロイ
• JSON を使った擬似 API でスライド一覧を提供

この方法なら、シンプルかつ管理しやすい形でスライドを公開できます。実際に動作している例は こちら 、リポジトリは GitHub に公開しています。

リポジトリを導入することで、アプリケーションのドメインロジックをデータ永続化層から切り離し、疎結合を実現します。

そして、しばしば議論になるのが、リポジトリはデータベースのレコード単位で作成するべきか、それともエンティティ単位で作成すべきか という点です。

本記事では、結論として エンティティ単位の設計を推奨 します。その理由を、レコード単位のリポジトリが抱える問題点とともに解説します。

なぜレコード単位のリポジトリでは問題が起きるのか？

結論として、データベースのレコードは単なるデータの塊であり、実際の利用方法を反映していない ためです。実際にデータを利用する際は、適宜結合や選択を行った上で使用する必要があります。

データベースのレコードは単なるデータの塊である

リレーショナルデータベースでは、正規化の程度によってテーブルの数や粒度が異なります。例えば、従業員（Employee）テーブルを考えてみましょう。

▼Before: 正規化されていないテーブル（Employee）

このテーブルには 「部署 ID」 と 「部署名」 の冗長なデータが含まれています。仮に「総務部」の名称を「人事・総務部」に変更する場合、総務部に属するすべての従業員レコードを更新しなければならず、非効率的です。

そこで、正規化 を行い、部署の情報を別テーブルに切り出すのが一般的な対応です。

▼After: 正規化されたテーブル（Employee）

▼After: 正規化されたテーブル（Department）

正規化を行わないと、データの整合性が担保されず、「人事・総務部」と「総務部」のようにデータの不整合が発生する可能性があります。

この正規化されたテーブルに対して、それぞれのレコード単位で EmployeeRepository と DepartmentRepository を作成するのが レコード単位のリポジトリ です。

レコード単位のリポジトリの問題点

例えば、従業員の組織図を作成する場合、 EmployeeRepository と DepartmentRepository それぞれからデータを取得し、手動で結合する必要があります。

問題点:

1. アプリケーション側でデータの結合処理が必要になる
2. リポジトリがデータベースのテーブル構造に依存してしまう

リポジトリを導入する本来の目的は、データ永続化層とドメインロジックを切り離すこと です。しかし、レコード単位のリポジトリでは、アプリケーション側がデータベースのテーブル構造を意識しなければならない という問題が生じます。

データ永続化層から関心を切り離すためのリポジトリであるはずなのに、テーブル構造を知っていないとデータを適切に扱えない。この点が、レコード単位のリポジトリの大きな問題です。

エンティティ単位のリポジトリが導く理想の設計

前述した課題を解決するために、エンティティ単位のリポジトリを推奨します。

リポジトリは用途ごとに設計するべき

リポジトリを設計する際は、そのデータを取得したい目的・用途を考慮 するべきです。

例えば、従業員データを扱う場合でも、用途によって異なるリポジトリが考えられます。

このように、異なる目的ごとに適切なエンティティを設計することで、データベースのテーブル構造を意識せずに済む のです。

OrganizationEmployee と SalaryEmployee を別のエンティティとして用意することで、データベースのレコード構造に依存しない柔軟な設計が可能になります。

まとめ：エンティティ単位の設計を選ぶ理由

• レコード単位のリポジトリでは、アプリケーションがデータベース構造を意識する必要がある
• エンティティ単位のリポジトリを導入することで、ドメインロジックとデータ永続化層を明確に分離できる
• リポジトリはデータの用途に応じて設計するのが望ましい

エンティティ単位の設計を採用することで、より柔軟で保守性の高いアーキテクチャを実現できます。

今回、登場人物を大きく以下の 3 つに分けます。

• 実装者
• レビュアー
• 他のエンジニア

コミットメッセージに Prefix を付ける

コミットメッセージに feat: や fix: などの Prefix（接頭辞）を付けることで、修正内容を一目で明確に伝えられます。

一般的に共通して使われ、使用頻度も多い Prefix は以下の 4 つです。

• feat: 新しい機能の追加
• fix: バグ修正
• refactor: 仕様に影響しないリファクタ
• chore: CI/CD やライブラリなどの基盤修正

チームで共通の仕様が決まっていない場合は、Conventional Commits のガイドラインを活用すると、業界標準に基づく統一的なメッセージが書けます。

Prefix を付けることで得られるメリットの 1 つは、後からコミット履歴を確認する際に、修正内容が一目で把握できる点です。

さらに、どの Prefix を付けるかを意識することで、余計な修正がコミットに混入するのを防ぎ、1 コミットあたりの修正差分を少なく抑える効果もあります。

コミット履歴を確認するのは、レビュアーや、数日後・数カ月後の自分自身かもしれません。そのとき、コミット単位の修正量が適切に抑えられていれば、修正内容を素早く正確に把握することが可能です。

修正内容を素早く正確に把握できれば、レビューで仕様の確認に留まらず、パフォーマンスや処理改善の議論が可能になり、コード品質の向上に繋がります。

コミット単位は機能のまとまりを意識する

私がレビュアーとして実際に見た、改善の余地があるコミット履歴の例を 2 つ紹介します。

例 1：コミット履歴が作業ログになっている例

5 refactor: ビューの処理をリファクタ
4 refactor: コントローラーの処理をリファクタ
3 feat: 12/22 までの作業分コミット/一旦完成
2 feat: 12/21 までの作業分コミット
1 feat: 12/20 までの作業分コミット

これは、実装者の作業の単位でコミットが作られています。1~3 のコミットはその日の作業単位でコミットされています。

レビュアーや他のエンジニアが関心があるのは、どのようにして機能が追加されたかどうかです。

そのため、このようなコミット履歴だと、コミットごとに修正差分を見るときに不完全な差分を見ることになり、実装の全貌を見るためには全ての差分（GitHub の File Changes）を見ることを強いられてしまいます。

そのため、このような自身の作業ログを保存しておくようなコミット単位は避けましょう。他のエンジニアは、あなたがその日どこまで進めたかには関心がありません。

TODO コメントを残した仮実装のコミットを追加し、後で本実装するケースをよく見かけますが基本的には避けるべきです。仮実装のコードは動作が保証されず、レビュアーが本実装のコミットと併せて確認する手間が増えてしまいます。

4~5 のコミットは、1~3 までのコミットのリファクタリングになっています。

レビューに出す前にリファクタリングを行う意識はとても素晴らしいですが、リファクタリング対象のコミットが同一の PullRequest にある場合、分けておく必要はありません。1 つのコミットにまとめてしまいましょう。

例 2：指摘に対する修正がコミット履歴にある例

5 fix: 一覧コントローラーのバグ修正
4 fix: 一覧ビューの指摘修正
3 fix: 一覧コントローラーの指摘修正
2 feat: 一覧ビューの新規作成
1 feat: 一覧コントローラーの新規作成

この例では、1〜2 のコミットは機能ごとにまとまっており非常に見やすいです。しかし、3〜5 のコミットはレビュー指摘やバグ修正が個別に積まれており、履歴が冗長になっています。

1〜2 の後、レビュー指摘を受けて 3〜4 の修正を行い、最終的に 5 でバグ修正を行ったというストーリーが想像できます。しかし、こうした履歴は実装者やレビュアーには有用でも、他のエンジニアにとっては不要な情報となりがちです。

そのため、3〜5 のようなコミットは残さず、レビューでの修正内容やバグ修正は元のコミットにまとめる方が望ましいでしょう。これにより、履歴が簡潔になり、全体の把握が容易になります。

修正内容を別コミットに分けておかないと、再レビュー時に指摘に対する修正差分が確認できないという問題があります。この問題の解決策は次のポイントで紹介します。

fixup と rebase でコミットログを綺麗にする

コミット単位を意識しても、途中で修正が必要になる場合があります。その際に履歴を整理するための便利な機能が、fixup と rebase です。

先に述べた以下の 2 つのポイント：

• コミットメッセージに Prefix を付ける
• コミット単位を機能のまとまりで意識する

これらを常に守るのは難しい場合もあります。たとえば、実装途中で漏れに気づいたり、レビュー指摘に対する修正をコミットとして積むケースです。

特に後者のケースは、レビューを効率的に進めるべきにもむしろ積極的に行うべきです。

rebase は非常に色々なことができる機能なので詳細は割愛し、今回は限定的な使い方の紹介に留めます。

指摘に対する修正を行う場合、

dfc67acb feat: 一覧コントローラーの新規作成
1f315272 feat: 一覧ビューの新規作成

一覧コントローラーに修正が必要な場合、該当のコミットに fixup を利用して修正を加えます。

git commit --fixup dfc67acb

これにより、以下のような fixup! 付きのコミットが生成されます

4320bf0d fixup! feat: 一覧コントローラーの新規作成

レビュアーにはこの修正コミットを見てもらい、再レビューをお願いします。

レビューが完了したら fixup で積んだ修正コミットを main ブランチにマージする前に、git rebase を使用して整理します。

git rebase --autosquash -i 1f315272

このコマンドで、fixup! 付きのコミットが元のコミットに自動的にまとめられます。これにより、main ブランチの履歴がすっきりし、他のエンジニアにとって見やすい履歴を保つことができます。

rebase を行ったことによりリモートとコミット履歴に差異が発生するため、push する際は --force-with-lease を付けて強制 push を行います。

git push --force-with-lease

git push --force-with-lease は慎重に扱うべきコマンドです。特にチームでの利用時は、運用ルールを明確にし、誤操作を防ぐ仕組みを整えることが重要です。

レビュー中は修正コミットを fixup として積み、マージ時に rebase でまとめる。この手順を踏むことで、レビュー効率を高めつつ、main ブランチの履歴を綺麗に保つことができます。これにより、他のエンジニアにとっても理解しやすいコミット履歴を実現できます。

まとめ

Git のコミットを通して、コード品質の向上に繋がる使い方のポイントを紹介しました。

エンジニアの業務に占める割合は、コードを書くより読む時間の方が圧倒的に多いです（コードレビュー、仕様調査、バグ調査、etc...）。そのため、読みやすいコードや把握しやすいコミット粒度・メッセージを意識することは、コード全体の品質に大きな影響を与えます。

今回紹介したポイントを日頃の業務に活かし、より良いチーム開発を目指しましょう。些細な工夫が、コード品質とチーム全体の生産性向上に大きく繋がります。

参考