AIと乗り切った1,500ページ超のヘルプサイト基盤刷新とさらにその先の話

2026-05-09 フロントエンドカンファレンス名古屋

Transcript

1. AIと乗り切った 1,500ページ超のヘルプサイト基盤刷新 (とさらにその先の話) 2026-05-09 フロントエンドカンファレンス名古屋 mugi / Cybozu Inc.
2. @mugi_uno mugi / Hajime Mugishima Cybozu Inc.
3. 名古屋ー！！！ • 実は前職が名古屋でした。2-3週間住んでたこともある。 • 味仙で注 文 前に 青 菜炒めが出てきたのを鮮明に覚えている
4. とある 日
5. kintone のヘルプサイトを 刷新したいという話がある
6. フロントエンド部分 全部おねがいできません？
7. そもそもなぜ刷新を？
8. より良いヘルプを届けられる体制にしたい • 10年以上に渡るメンテナンスによる課題 • 対応の属 人 化 / オンボーディングコストの増加 • 仕様書が 足 りない / 古いものも多い • jQuery, ES5 などのレガシーなフロントエンド • 翻訳コストが 高 いため外部SaaSなどを活 用 したい • 複数プロダクトで基盤を共有していることによるコストとリスク 　 ↓ 刷新により負債を解消しつつ、併せて管理体制も 見 直したい • kintone 側の変化スピードに合わせて ヘルプサイト側でもより良いヘルプを柔軟に提供したい
9. AI がある今ならやれる (かもしれない) • 理想はあれども刷新にはそれなりにコストがかかる • 本来なら 人 も時間もたくさん... 　 ↓ AI が使える今なら少 人 数でガッとやれるのでは？ • 人 員確保やコミュニケーションのコストを 一 部踏み倒せる • 手 を出せていなかったが、今ならチャレンジする余地がある
10. ヘルプサイトか… まあ静的ページの集まりだろうし 今ならAIもあるしなんとかなるやろ フロントエンド部分 全部おねがいできません？
11. まかせといて フロントエンド部分 全部おねがいできません？
12. kintone ヘルプサイトの刷新とは
13. kintone ヘルプサイト - https://jp.kintone.help/ Hugo(Go製のサイトジェネレータ)で作られた静的サイト
14. 多 言 語対応 日 本語を含む最 大 ６ヶ国語に対応 大 半は 手 動翻訳でそれぞれ別のコンテンツを保持している
15. マルチリージョン • kintone はグローバル展開しており、微妙に機能差異がある • JP, US, CN という3リージョンに応じたヘルプサイトが存在する • これは 言 語とは別の話。リージョンごとに多 言 語に対応している JPリージョン 用 ヘルプサイト USリージョン 用 ヘルプサイト
16. そもそも実は kintone だけのヘルプサイトではない • "kintone ヘルプサイト" と呼んではいるが、 "契約/ 支 払い"・"共通のシステム管理" などは別のプロダクト • ヘルプサイト基盤は 一 部共 用 しているがサイトはドメインから異なる →これらは別のプロダクトのサイトだが、刷新の対象
17. 完全に別のプロダクトとも基盤を共 用 している サイボウズが提供する別のプロダクトともヘルプサイト基盤は共 用 (e.g. グループウェアの "Garoon" など） →これらは基盤を共 用 しているが刷新の対象外
18. つまり…？ • 実質３サイトの刷新が必要 • それぞれのサイトにおいて最 大 ３リージョンの考慮が必要 • 各リージョンにおいて６ 言 語で利 用 できる • すべてを考慮した移 行 元の総コンテンツ数は約4,000ファイル • そして移 行 元基盤には刷新対象外のサイトのコードも混在
19. ˞͕͜͜࡮৽ର৅
20. まかせといて フロントエンド部分 全部おねがいできません？
21. まかせといて フロントエンド部分 全部おねがいできません？ ஍ࠈͷ֖͕։͔Εͨʜ ~ Welcome t He l ~
22. このセッションで話すこと • ドメイン知識 / 技術スタック共に皆無なコードベースに AIと共にどう 立 ち向かうか • 大 量コードのマイグレーションを AI を活 用 してどう 行 うか • AI x 刷新において、どうナレッジを残して未来に繋げるか
23. AIとのコード/仕様の理解
24. 何はともあれコードおよび仕様の理解が必要 • 自 分はHugoは触れたことがなく 一 切知らなかった • もちろんヘルプサイトのコードベースも初めてでドメイン知識もない • 中 身 を知らずに指 示 を出すのは不可能に近い • AIに正しいプロンプトを与えるための材料を 自 分が持っていない
25. 知識ゼロの状態でコードベースに感じることは？
26. 「 自 分が何をわかっていないのかがわからない」
27. たとえば… Markdownでこう書くと… なんかこれが出てくる
28. たとえば… • FW/ライブラリの機能？ • 独 自 実装？ • そもそも対応するコードはどれ？ 断 片 的な情報から気合でgrep (class名とか) Markdownでこう書くと… なんかこれが出てくる
29. それっぽいコードにたどり着いても… 「どうやら _markup/render-heading.html に書くと変換されるらしい」
30. それっぽいコードにたどり着いても… 刷新前 _markup/render-heading.html から 一 部を抜粋
31. それっぽいコードにたどり着いても… anrhorizeって何? ".Text" はどこから来る? findRe..? .Anchor?? この分岐条件ってどこから来るんだ…? Level…? Markdownの 見 出しレベル?? classを付与できる?? そもそも "|" の役割は? safeURLは誰が提供してるの？ range..?ループ? 刷新前 _markup/render-heading.html から 一 部を抜粋
32. 最初の作業 / AIとの無限の壁打ち 片 っ端からAIを質問攻めにしてドメイン知識をコード理解を得る
33. AI によって「アタリをつける」作業を省略できる • 自 分が調べようとしているコードが「どの技術スタックの概念か」 については、アタリをつけて調べ始めるしかない ※シニアはこのあたりのエスパー能 力 が異様に 高 かったりする • 知らないコードべースの理解はこれの無限の繰り返し • AI にこの部分を丸投げできる e.g. Cursorに雑に投げる
34. 基盤の刷新作業 with AI
35. 刷新後の技術スタック Astro • 既存コンテンツとの親和性が 高 め • 仕様を満たすためのカスタマイズがしやすい • 広く普及しておりナレッジが世の中に豊富 TypeScript, React, Vitest, etc... • その他技術スタックも可能な範囲でモダン化 • 攻めたものは使わない
36. 刷新で抑えておきたかったポイント 柔軟に対応できるように進めたい • 当初想定していない仕様の発覚 / 刷新中の仕様追加が予想された • 仕様 自 体の調整も 一 つの解。ただ、やれるならやりたいですよね（お気持ち） 刷新後のメンテナンスを考慮したい • そもそもの刷新理由のひとつでもある
37. とはいえ「ちゃんと終わる」のが 大 事 目 標期 日 までにちゃんと終わらせたい • ヘルプサイトは多くのチーム・メンバーが関わってくる • 合意を取った期 日 までにちゃんと刷新を間に合わせたい 大 枠として「これでいけそう」という状況まで持っていきたい • 方 向性は妥当か・全体コストはどの程度か・リスクはどこか... • 不明確な部分が多いため、後からの 手 戻りの懸念が 高 い • まずは60-70%の粗削りでも全体像を把握したい
38. 戦略 - ひとまず構造を踏襲して 走 り切る 刷新前のレイアウトやパーツを踏襲しAstroコンポーネントに書き換える • 刷新とリファクタを混ぜずに 走 り切る • ただし、刷新対象外プロダクト向けのコードだけはここで落とす 構成を踏襲する e.g. 左メニュー Hugo: treenav.html Astro: TreeNav.astro
39. パーツ単位での刷新ドキュメントを残させる AIに投げて 一 発で完璧なものを出すのは不可能 • 仕様的に不明瞭なもの • そもそも Astro で簡単に再現できないもの • 物量が多いことでのセッション/エージェントごとの成果物のブレ 成果物の横に詳細なドキュメントをすべて残させる • Hugo → Astro での関数や変数の変換対応 • 既存を踏襲する中でリファクタが推奨されると思われる箇所 • TODOとして 見 送った事項, 構造を変更した箇所, 外部依存が何か など...
40. ҎԼͷϧʔϧʹैͬͯ)VHPͷQBSUJBMϑΝΠϧΛ"TUSPίϯϙʔωϯτʹม׵͍ͯͩ͘͠͞ɻ
    
    جຊϧʔϧ
    
    ग़ྗϑΝΠϧ
    
    
    
    
    "TUSP
    ίϯϙʔωϯτ
    A\$PNQPOFOU/BNF^BTUSPA
    
    
    
    
    มߋه࿥
    A\$PNQPOFOU/BNF^NEA
    
    
    
    
    ྆ํͷϑΝΠϧΛඞͣ࡞੒͢Δ͜ͱ
    
    ม਺ͷѻ͍
    
    
    
    
    )VHP
    ͷαΠτม਺
    ˠ
    AFOWA
    ϓϩύςΟ
    )VHP
    ͷϖʔδม਺
    ˠ
    AQBHFA
    ϓϩύςΟ
    
    \˞ͦͷଞɺ"*ͱͷนଧͪͰཧղͨ͠಺༰Λݩʹͨ͠ॻ͖׵͑ϙϦγʔΛॻ͘^
    
    มߋه࿥ϑΝΠϧͷ಺༰
    ҎԼͷ߲໨Λඞͣه࿥͍ͯͩ͘͠͞ɿ
    
    ؔ਺ɾม਺ͷஔ׵ରԠද
    
    50%0
    Ϧετ
    ະ࣮૷΍ཁ֬ೝࣄ߲
    
    ߏ଄ͷมԽ
    EFGJOFUFNQMBUF
    ͷ෼཭ͳͲ
    
    ͦͷଞͷࠩ෼
    ଐੑ໊ͷมߋɺۭന੍ޚͳͲ
    
    ֎෦ґଘ
    εΫϦϓτͷѻ͍ͳͲ
    \˞มߋه࿥ϑΝΠϧͷϑΥʔϚοτྫΛৄࡉʹॻ͘^ プロンプトのイメージ（ 一 部を抜粋） ドキュメントの出 力 具体的な実装ポリシー 記録ファイルの内容
41. 出 力 されたもの Hugo⇔Astroの対応 残タスク その他注意事項など 1:1でドキュメントを残す
42. 作業ログ・ナレッジを執拗に残す 後からのブラッシュアップを前提として、とにかくログを残していく • 場当たり的な仕様確認・調整・解決を繰り返すコストは 高 い • とにかく書き換えを進めて懸念事項などは貯めていく • 一 定の進捗に到達した時点でまとめて精査 • 局所的ではなく、ある程度俯瞰した形での意思決定ができる • 大 量のTODO/未決事項がログとして残るが、AIに精査も押し付けられる
43. 
    ࡞ۀͷྲྀΕ
    ࡞ۀ͝ͱʹ
    NJHSBUJPOEPDT\
    ܻͷ࿈൪^a@\࡞ۀ໊^
    σΟϨΫτϦΛ࡞੒͠ɺ࣍ͷϑΝΠϧΛ࡞੒͢Δ
    
    QMBONE
    
    ৄࡉͳ࣮ߦϓϥϯʢ࡞ۀ։࢝લʹ࡞੒ʣ
    
    QSPNQUNE
    
    Ϣʔβʔ͔ΒͷࢦࣔͱɺͦΕʹର͢Δճ౴ͷཤྺɻࢦ͕ࣔ͋Δͨͼʹߋ৽͢Δ
    ྫ
    AAA
    NJHSBUJPOEPDT@DSFBUFDPNQPOFOU
    ᵓᴷᴷ
    QMBONE
    
    
    
    
    ࣮ߦϓϥϯ
    ᵋᴷᴷ
    QSPNQUNE
    
    
    ࡞ۀཤྺ
    AAA
    
    ·ͣɺQMBONE
    ʹ࡞ۀͷϓϥϯχϯάΛ࡞੒͠ɺϢʔβʔʹఏ࣮ࣔ͠૷ڐՄΛಘΔ
    
    ڐՄ͕ಘΒΕΔ·ͰɺϢʔβʔͱ૬ஊͭͭ͠ϓϥϯχϯάΛ܁Γฦ͠·͢
    作業時に使っていた Slash Command のイメージ (現在なら Skills を推奨） 勝 手 に変更に着 手 させない 作業のたびにファイルを残す プロンプトも含めたログを残す
44. 
    ࡞ۀ࣌ͷυΩϡϝϯτࢀর͓Αͼߋ৽ϧʔϧ
    ·ͣɺ࡞ۀ࣮ࢪલʹ͸ඞͣ࣍ͷϑΝΠϧͷ಺༰Λ֬ೝ͢Δ
    
    NJHSBUJPOEPDTSVMFTNE
    
    "TUSP
    ։ൃͷӬଓతͳϧʔϧʢҠߦ׬ྃޙ΋࢖༻ʣ
    
    NJHSBUJPOEPDTNJHSBUFSVMFTNE
    
    ৽ͨͳҠߦϧʔϧ΍஫ҙ఺
    
    
    ࡞ۀத͓Αͼ׬ྃޙͷυΩϡϝϯτͷߋ৽
    NJHSBUJPOEPDT
    ഑Լͷ
    
    ͭͷϑΝΠϧΛద੾ʹ࢖͍෼͚ɺඞཁʹԠͯ͡࠷৽Խ͢Δ
    
    SVMFTNE
    "TUSP
    ։ൃͷӬଓతͳϧʔϧ
    
    
    
    ϚΠάϨʔγϣϯؔ࿈ͷ৘ใ͸Ұ੾ؚ·ͳ͍
    
    
    
    ίϯϙʔωϯτઃܭݪଇɺ඼࣭؅ཧࢦ਑ͳͲ
    
    NJHSBUFSVMFTNE
    ϚΠάϨʔγϣϯ࡞ۀ࣌ͷϧʔϧ
    
    
    
    )VHP
    ͔Βͷม׵نଇɺҠߦ࣌ͷ஫ҙ఺
    
    
    
    %0.
    ߏ଄ͷอ࣋ɺίϯϙʔωϯτ໊ͷରԠͳͲ
    
    NJHSBUFNFNPNE
    ϚΠάϨʔγϣϯͷਐḿ؅ཧ
    
    
    
    ࡞ۀঢ়گɺະղܾࣄ߲ɺ50%0
    
    
    
    ֤࡞ۀͷ֓ཁͱֶशࣄ߲ ナレッジを蓄積させる 作業のたびに更新して育てる 刷新完了後も残すナレッジは分ける 作業時に使っていた Slash Command のイメージ (現在なら Skills を推奨）
45. 作業のたびにログを蓄積 ナレッジを育てて類似作業を効率化
46. 最終的に 生 成されたナレッジに含まれるもの • リージョン・多 言 語化などのドメイン知識 • 技術スタック • リポジトリ内のどこに何があるか • 変更を加える際の注意点・守るべきルール • 特徴的な実装パターン • 外部連携や特殊なカスタム実装に関する概要 • ... ※やや過剰(書きすぎ)となる傾向があるため、最終的な内容の精査と圧縮は必須
47. 刷新中にナレッジに救われた例 / PDF 生 成 • 典型的な「 見 落としてしまっていた」仕様 • コンテンツを 一 部PDFで出 力 する必要があり、 リポジトリ外の専 用 スクリプトで特殊な変換が 行 われていた （そして仕様上、絶対に落とせない） • Hugoでしか動作しないスクリプトだったが、 ナレッジを組み合わせることで AIによってほぼすべての書き換えが 行 えた 意識外からのPDF
48. コンテンツのマイグレーション
49. 大 量のコンテンツマイグレーション • 刷新前 ( Hugo ) ではコンテンツはMarkdownファイルで管理 • 刷新後 ( Astro ) ではMDX形式に変換が必要 刷新前/Markdown 刷新後/MDX 似てはいるが 一 定の変換が必要（FrontMatter, Component, 独 自 記法, etc...）
50. AI での直接書き換えは 非 現実的 • 最終的なマイグレーション対象は 1,500 ファイル超 • 多すぎてコンテキストは確実に 足 りない • 分割して処理したとしても膨 大 な時間とコストがかかる • 問題が後から 見 つかった場合の再実 行 が厳しすぎる
51. マイグレーションスクリプトを作らせる • AI にマイグレーションスクリプトを作らせる • 冪等性があり、何度でも再実 行 できる • 実装にもよるが、数千ファイル程度なら問題なく処理できる
52. 最初に試したプロンプト 
    )VHP
    ͔Β
    "TUSP
    ΁ͷίϯςϯπϚΠάϨʔγϣϯεΫϦϓτͷ࡞੒
    ੩తαΠτδΣωϨʔλͰ͋Δ
    )VHP
    ޲͚ʹॻ͔Εͨ
    NE
    ϑΝΠϧΛɺ
    "TUSP
    Ͱར༻Մೳͳ
    NEY
    ϑΝΠϧʹม׵͢ΔεΫϦϓτΛ࡞੒͍ͯͩ͘͠͞ɻ
    
    ม׵ͷ࢓༷
    
    ίϯϙʔωϯτ
    ʙίϯϙʔωϯτͷม׵ϧʔϧʙ
    
    'SPOU.BUUFS
    ʙ'SPOU.BUUFSͷม׵ϧʔϧʙ
    
    ʙʙʙ
    ʙͦͷଞɺม׵ʹؔ͢Δ࢓༷ʙ
    
    ม׵ྫ
    ʙ
    ม׵લͱม׵ޙͷίʔυͷྫ
    ʙ 要は「全部作れ」という指 示
53. 発 生 した事象 → 変換は出来たが動かない • 全ファイルの変換 自 体は正常に 行 えたが、 かなり多くのファイルが Astro では Invalid でエラーとなった • 単純にプロンプトで変換仕様を満たせていなかった • ファイル数が膨 大 なため変換仕様を事前に網羅しきるのは厳しい エスケープ対象の違い ( Astroのほうが厳密) FrontMatterでの値の埋め込み ( Astroでは標準では不可能) HTML構造の不正 ( Astroのほうが厳密)
54. 一 気にやろうと思うと思うと無理がある • トライ＆エラーで 見 つかった仕様の追加実装を試みる • 変換処理がどんどん複雑化し、上 手 くいってた箇所も壊れるように… • ここからテストを 足 しても 手 遅れだった (既存テストFail→直すと追加箇所がFail→… で進まないことが頻発) • AI「できました！！」（できてない）
55. 成功したアプローチ → 責務を分割 • とにかく責務を 小 さく分割して徐々に作る • 特殊な変換仕様が他に影響を与えないように ม׵εΫϦϓτ͸ɺ੹຿Λ෼ׂ͠ɺ֤ॲཧΛݸผͷؔ਺ͱͯ͠ఆ͍ٛͯͩ͘͠͞ɻ
    ؔ਺ؒͷґଘ͸ແ͍Α͏ʹ࣮૷͍ͯͩ͘͠͞ɻ
    ྫ
    
    $-*༻ͷΤϯτϦʔϑΝΠϧ
    DMJUT
    
    4IPSUDPEFT
    ͷม׵ॲཧ
    
    TIPSUDPEFQSPDFTTPSUT
    
    3FOEFS
    )PPLT
    ͷม׵ॲཧ
    
    SFOEFSIPPLQSPDFTTPSUT
    
    ϑϩϯτϚλʔͷม׵ॲཧ
    
    GSPOUNBUUFSQSPDFTTPSUT
    ͦΕͧΕͷؔ਺ʹ͸ςετίʔυΛ༻ҙͯ͠ಈ࡞Λ୲อ͍ͯͩ͘͠͞ɻ
    ·ͣ͸Կ΋࣮ߦ͠ͳ͍ΤϯτϦʔϑΝΠϧ͔Β࡞͍ͬͯͩ͘͞ɻ
56. TDD で段階的に作る • 段階的に 小 さく作っていく • 分割した責務ごとにテストから作成して進める • 「実装が確定した箇所」を積み上げていった • 一 旦リファクタさせることで上 手 く実装できるケースもあった (テストが活きてくる） 
    UXBEB
    ελΠϧͷ
    5%%
    Ͱ࣮૷ΛਐΊΔ
    
    ࢓༷͸Ұ࣮ͭͣͭ૷͠ɺඞͣઌʹςετΛॻ͘͜ͱ
    
    ࣮૷ޙʹ͸ςετΛ࣮ߦ͠ɺ͢΂ͯͷςετ͕ύε͢Δ͜ͱΛ֬ೝ͢Δ
57. 最終的な成果物 • 11種類の変換ロジック ( FrontMatter, HTML補正, Escape, 画像パス, ...) • 約700ケース弱のテストコード • 約 1,500ファイルを30秒ほどで変換 • 刷新中にも移 行 対象コンテンツは増えていくが 追加対応が必要になっても問題なく対処していけた
58. 刷新の完了
59. なんとか刷新が完了 🎉 • 翻訳の SaaS 化、対象外コンテンツの削除などもあり 最終的な移 行 コンテンツはおおよそ 1,500 ページ (タイトル回収) • 特に致命的な問題はなく、2025年12 月 には無事に移 行 完了
60. ナレッジによって誰でも変更しやすくなった • 刷新後、チーム外のメンバーがコントリビュートする機会があった • 刷新と同時に育てたナレッジが有効に働き、 メンバーが関与しないままでも Pull Request を作成できた • 他にも、新規メンバーが変更を試みた際も、 オンボーディングコストが低いまま AI によって対応できるように
61. AIとの刷新で得られた学び
62. 刷新 → 答えがあるからAI移 行 は楽？ • ヘルプサイトという性質で逆に厳しいものがあった • "振る舞い" より " 見 た 目 " がメインになってくる • 見 た 目 をAIで担保させるのが現状だとわりと難しい • Chrome DevTools などで新旧の 比 較をさせると ズレてるのに「完璧です！」とか 言 い出す • そもそもコンテキストをかなり 食 う • 最終的にはVRTで愛のある 目 視チェックをしていました
63. 前に進めるために効率良く AI と付き合う • 闇雲に AI にコードを書かせれば良いというわけではない • 理解を深めるために AI を活 用 するのは 非 常に有 用 • 結局、AI を使う側の知識に引っ張られる • 仕様など内容の理解が浅いと明確な指 示 も出せないし、 成果物の妥当性も判断できない • 特にジュニアエンジニアは使い倒していくと良いと思う • 「マイグレーション」はさせずに 「マイグレーションスクリプトを作らせる」といった考え 方
64. 並 行 してナレッジを育て続ける • 刷新初期から、刷新後を 見 越してナレッジを貯めて育て続けた • 刷新後半では育ったナレッジによって AI の精度も 高 くなった • 仕様の確認・意思決定などは 日 常業務内で不定期に訪れる • 簡単に蓄積して整理できる仕組みを早めに整えておくと良い • 刷新の場合は既存仕様を洗い直すため特にチャンスが多い
65. 根本の「やってみよう」という意思決定が変わる そもそも、AIが無かったらこの刷新PJは恐らく存在していなかった • コスト( 人 と時間)が 大 きいと着 手 する敷居が跳ね上がる • "そんなコストかかるなら今のままで耐えればいいのでは…" • 少 人 数 & AI によってねじ伏せた部分が 大 いにある 実際、"いけそうだぞ…？" が 見 えてくるまでが速かった • 全体を把握＆ざっくり全て動作する形に持っていくまで概ね 一 ヶ 月 程度だった • 少 人 数の 一 ヶ 月 であれば「とりあえずやってみたら」の判断はしやすい
66. さらに先の話
67. AI 活 用 は局所最適になりやすい • AI ツールは多くのメンバーが利 用 しているが、 自 分の観測範囲だけの最適化に留まりやすい • コーディングのみ速くなったり • 自 分だけのナレッジだけが育ったり • 他チームと似たSkills作ってたり • AI活 用 度合いが 人 によってバラバラだったり • ヘルプサイト刷新での AI 利 用 はわりとうまくいったが これも「ヘルプサイト」の中での話でしかない
68. 広域への展開 / 推進へ • AI Catalyst 部が爆誕しました • 社内のAI活 用 推進のための啓蒙やナレッジ整理、研修の実施など • ヘルプサイト含む局所での知 見 を プロダクト全体に還元できるような仕組み作り中 • Skills の共有 方 法の整備 • AI活 用 を 見 越した開発プロセスの 見 直し • ... 鋭意、試 行 錯誤中です