Cloud RunとVitePressで構築するヒトとAIが貢献可能な社内ドキュメント配信基盤 – Findy Tech Blog

企業テック

はじめに

データソリューションチームの土屋 (@shunsock)です。

データソリューションチームでは、従来、GUIベースのドキュメント管理ツールを利用していました。しかし、検索体験の悪さや画像の画質低下といった課題を抱えていました。

そこで、CLIベースのドキュメントホスティングシステムを独自に構築しました。

本稿では、CLIベースで構築したドキュメントホスティングシステムの設計と実装について紹介します。

課題

ファインディでは従来、GUIベースのドキュメント管理ツールを全社で、開発チームの一部がCLIベースのドキュメント管理ツールを利用していました。データソリューションチームでは、全社で利用しているドキュメント管理ツールを利用していたのですが、次のような問題点がありました。

API利用ができない

APIそのものは提供されているサービスだったのですが、社内規定で利用できませんでした。この影響で、API経由で解決できそうな課題の解決も既存ツールでは難しいという判断になりました。

機能不全に陥った検索システム

課題となっていたのは検索システムの弱さでした。従来のドキュメントツールは全社的に利用されていたため、さまざまな部署のドキュメントが一箇所に集約されていました。

しかし、検索結果に他チームのドキュメントが多数混在してしまい、必要な情報を見つけるのが難しい状況でした。通常はタグなどでドキュメントを検索可能にしますが、その機能がありませんでした。

具体的には、「設計書」と検索すると「他チームの設計書」に埋もれて「自チームの設計書」が見つけられないといった事象が発生していました。

最低限のログ機能

既存サービスでは、ドキュメントの最新のアップデートの時間以外の情報が表示されません。なので、誰がいつドキュメントを更新したのかを追跡できませんでした。

これにより、ドキュメントの信頼性が低下し、情報の正確性を保証することが困難でした。

画像品質の悪化

さらに、画像の品質劣化はドキュメントの可読性に大きく影響し、業務に支障をきたしていました。

次の写真は、実際に既存システムにアップロードされた画像です。元の画質は 1920x1080px なのですが、明らかに劣化しています。この写真がCMSの小さいカラムの中で表示されるので、読めなくなってしまうのです。

画像の文字が潰れた時は、別のシステムで画像を載せてそこのリンクを貼るといった運用をしていました。

要件

上記の課題を達成するために、次の要件を定義しました。

  1. ドキュメントのバージョン管理
  2. 必要な情報が見つかる検索エンジンの搭載
  3. 画像の画質の保持
  4. 閲覧できるユーザーの制限

また、ドキュメントホスティングシステムは直接ROIに響かないため、低コストで実装する必要がありました。今回紹介するシステムは私一人の片手間で開発したものです。

実現方法

1 – 3 は 静的サイトジェネレーターで、4はCloudRun & IAPで実現しました。

システムアーキテクチャ

今回は、チームでも利用の活発なGoogle Cloudを利用しました。Google Cloud Run上にVitePress (後述) をホスティングし、IAP (Identity-Aware Proxy) を利用してアクセス制御を行います。ドキュメントやインフラストラクチャはGitHubで管理しています。

次に、前述した要件に対してどのように解決したかを説明します。

ドキュメントのバージョン管理

ドキュメントホスティングフレームワーク「VitePress」で解決しました。VitePressは、Markdownをベースにした静的サイトジェネレーターです。

このシステムをGitHubで管理し、バージョン管理を実現しました。

必要な情報が見つかる検索エンジンの搭載

現行の検索エンジンが問題になっていた要因として、検索対象の広さがありました。今回のプロジェクトで検索対象が自チームのみになり、解消されました。

ちなみに、VitePressでは検索機能の実装が簡単です。config.mtsに次のように記述すると検索が有効になります。

import { defineConfig } from 'vitepress'

export default defineConfig({
  
  themeConfig: {
    search: {
      provider: 'local' 
    },
  }
  
})

次の画像は実際の検索画面です。マッチした部分をハイライト付きで確認できます。(業務内容に関わる部分はモザイクをかけています。)

画像の画質の保持

この問題もVitePressの導入で解決しました。

次の画像は本記事で紹介したシステム設計図の写真を元のシステムとVitePressで表示したものです。1枚目が元のシステムで表示したもの、2枚目がVitePressで表示したものです。VitePressでは、画像の品質が保たれていることがわかります。


閲覧できるユーザーの制限

社内ドキュメントを配信するので、閲覧制限を入れる必要がありました。

今回はCloud Run と IAP (Identity-Aware Proxy)を利用して、閲覧できるユーザーを制限しています。

以前は、ロードバランサのリソースを作成しそれにIAPを紐付ける必要がありました。Google CloudからCloud Runに直接IAPを紐付ける機能が執筆時から数ヶ月ほど前に公開されたため、今回のシステムではこの新しい機能を利用しました。この機能のおかげでとても簡素なインフラ構成になりました。

https://blog.g-gen.co.jp/entry/using-iap-with-cloud-run

結果

成果

これらの取り組みにより、設定していた要件をすべて達成しました。さらに、GitHubに集約したことでAIとの協業がしやすくなりました。ここでは、ドキュメント作成・検索におけるAIの活躍を紹介します。

AIによるドキュメント作成

GitHubにドキュメントが集約されたことで、ドキュメントにAIが貢献しはじめました。次の写真は作成したホスティングシステムのHistoryです。直近ではDevinの関与しているコミットが80%を越えています。

次の画像は、NeoVim と copilot.nvim を利用してAIがドキュメント提案をしている様子です。（灰色の部分がAIの提案）

また、次の写真はDevinを利用してドキュメントの更新をしている様子です。編集者は、エディタを開かずにドキュメントを更新しています。

CLI上でのドキュメント検索

GitHubにドキュメントを集約したため、ghコマンドとAIエージェントを組み合せた検索ができます。次の写真ではClaude Codeでドキュメント内のGetting Started (=チュートリアル) を検索しています。

Claude Codeにプロンプトで検索を命令します。ここでは検索にghコマンドが利用できると伝えています。

Claude CodeがGetting Startedの一覧を出力していました。試しにgithub2slack (レビュー依頼の情報をSlackに通知してくれる社内向けアプリ) のGetting Startedの詳細を調べます。

このようにCLI経由の検索が簡単にできるようになりました。この検索機能は、「DesignDocや詳細設計書を参照しながら実装をClaude Codeでする」など様々なシーンで応用が効きます。

今後の展望

作成したシステムは概ね満足できる水準であったものの、いくつか改善点が見付かっています。

例えば、画像ファイルの保存方法です。作成したシステムでは画像を直接GitHubのリポジトリに載せています。チームメンバーに圧縮を依頼し、現段階では問題になっていないです。しかし、今後pushやデプロイ速度低下の懸念があるので、画像配信方法を改善する予定です。

また、GitHub Actions などで一定期間編集されていないドキュメントを集約し、更新を促すオペレーションを回そうと考えています。

総評

今回の仕組みは、「GUI前提のツールでは満たせなかったニーズを、限られた工数で解決できた」好例になったと考えています。

私の本業はデータ基盤の構築ですが、その片手間で開発・運用可能なレベルにシステムを簡素化できたことは、再現性や他チーム展開の観点でも有意義です。

今後もドキュメントを拡充して、オンボーディングの高速化やサイロ化の回避に貢献していきたいです。




元の記事を確認する

AIが職を奪う｢常識｣疑え、勝者は若手－敗者は経験豊富なベテラン幹部 - Bloomberg 前の記事 FigmaとGoogleが提携、Gemini AIを統合してデザインワークフローを革新 次の記事

関連記事