２日間で全社員がわかる仕様ガイドを7件全社公開した
はじめに
10月頭にGitHub Copilotが導入されてから、手でコーディングする時間が大幅に減少しました。今まで全て手作業だったら5日かかっていたであろう実装が、3日目にはプルリクエストを作成できる状態になっています。
コーディング時間が減った代わりに、私が注力しているのが「リポジトリ解析をして、そこからわかったことを全社に公開する」作業です。11月28日からリポジトリ解析を開始し、12月18日から全社公開を始めました。全社公開にはConfluenceを使用しています。
リポジトリ解析でどんなものを調べるのか
PCアプリ、Androidアプリ、iOSアプリの各リポジトリについて、以下のような項目を調査しています。
- リポジトリがなんのアプリケーションを構成しているのか
- ファイル構造
- 技術スタック
- 技術的負債になっている箇所
- 個人的に気になった機能が実装されている箇所
- 特定の機能の制約
- アプリの全体像（機能一覧）
- OSを跨いだ機能の違い（Android/iOS/PCの差異）
特に意識しているのは、ソースコードを見なくても機能を理解できるようにプロンプトを書くことです。
従来の調査書・実装計画書との違い
以前の記事で紹介した調査書・実装計画書は、開発向けの技術資料として個人やチーム内で使用していました。一方、今回作成している仕様理解ガイドは、以下の点で異なります。
| 項目 | 調査書・実装計画書 | 仕様理解ガイド |
|---|---|---|
| 目的 | 実装効率化 | 問い合わせ対応削減 |
| 対象読者 | エンジニア | 非エンジニア含む全社 |
| 記載内容 | 技術的な実装詳細 | アプリの全体像、OS間の違い |
| 公開範囲 | 個人・チーム内 | Confluenceで全社公開 |
| アプリ全体像 | 記載なし | 機能一覧を含む |
| OS間の違い | 記載なし | Android/iOS/PCの差異を明記 |
現時点でエンジニア向けガイドを16件作成し、そのうち7件を全社公開しています。1ガイドあたり約5分で作成でき、トークン消費量も調査タスクによっては0.5%程度の増加に抑えられています。
おすすめのAIモデル
GitHub Copilotでさまざまなモデルを試してきましたが、最も読みやすい文章を生成したのは**Claude系(Opus, Sonnet)**でした。
例えば、GPT-5 miniのような無料モデルで文章を作成するとかなり簡潔な出力になりますが、Claudeに書き直させると表やクラス図のアスキーアートが追加され、視覚的にも理解しやすくなります。Sonnetでも十分読みやすい文章が生成されるため、コストパフォーマンスを考えるとSonnetの利用をおすすめします。
さらに、トークンに余裕がある場合は、Claudeだけでなく他のモデルと併用で作成すると精度がより高まります。
以下は、状況に応じたAIモデルの選定フローです。
私がやっていたのが、GPT5.2にガイド作成に必要な情報を書かせ、Claudeにガイドの内容を膨らませると言う工程です。
GPT5.2はこれまでのモデルと比較しても、自分のやっている作業を慎重に自己レビューし、間違いがないか確認しています。実際にロジックコードを書かせても完成度が高くなっていると感じていますし、ドキュメントでも同じことを実感します。
ただし、やはりドキュメントが簡潔になりがちなので、Claudeに読みやすく書き換えてもらった方が、数日後読み返した時にも頭に入りやすいです。
なぜリポジトリを解析するのか
私が携わっているアプリケーションは非常に多機能です。しかも、他のアプリストアでよく見かけるようなアプリではなかなか見かけない、独自性の高い機能がいくつも搭載されています。
そのため、ソースコードを読んでも理解するのが大変でした。私が入社して特に困ったのが、「どんな機能があるのかわからない」ということでした。
そこにAIが導入されたため、試しにリポジトリを解析させてみました。すると、ガイド的なドキュメントがあるかないかで、コードやアプリ自体に対する理解が格段に深まったことを実感しました。
実際に、普段Androidチームにいる私が、iOS特有のとある機能についてサーバサイドエンジニアに軽く説明できたこともあります。ガイドを作っていなければ、何も見ずに説明することは不可能だったでしょう。
実装で使うトークンを温存しながら、「仕様理解ガイド」を個人的に作成しています。
なぜ全社に公開するのか
一言で言うと、**「実装時間を守る防衛策を練るため」**です。
問い合わせ対応の現状
エンジニアのもとには、毎月何件もカスタマーサービス部を経由してお客様からの問い合わせが入ります。よく観察してみると、前にも対応したことがあるような機能に関する問い合わせも含まれています。
これまでは、お問い合わせがある度に実際の動作とソースコードを確認してエンジニアが回答していました。私もこれまでにいくつも対応してきましたが、「毎回ソースコードを確認するのは非効率」だと感じていました。
特に厄介な仕様問い合わせ
さらに、バグ報告以前に仕様に関する問い合わせまで含まれています(体感で1〜2割)。これが意外と厄介です。
社内のConfluenceには、何年も前にその機能を実装した時のミーティング議事録やDesignDocがあります。しかし、これを読んだところで一発で内容を理解できるものだとは言い難く、結局ソースコードを確認する羽目になっていました。
エンジニアができる防衛策
こうした状況を受けて、非エンジニアが検索してその仕様について理解し、回答できるようにすることが「エンジニアができる防衛策」だと考えました。
以下は、従来の対応フローとガイド活用後の比較イメージ図です。
次のセクションでは、そんな防衛策の実行手順を紹介します。
全社向けガイドの作り方
全社向けガイドは、2段階で作成しています。
ステップ1: エンジニア向けガイドの作成
まず、エンジニアが理解できる詳細なガイドを作っておきます。根拠となるソースコードを記述し、探索の手間を省くことを重視します。
実際に使用しているプロンプト例
エンジニア向けレポート作成時:
Androidリポジトリを確認し、[ユーザ情報表示機能]について以下の観点から調査して
- 機能の概要
- 実装しているコード
- 使用できるようになる条件
- 技術的課題
ファイル形式
- Markdown
- 初めてこのプロジェクトにジョインしたエンジニアでも理解できるように記述する
- (格納場所のPath)
特に以下のプロンプトを付け足すことが重要です。
初めてこのプロジェクトにジョインしたエンジニアでも理解できるように記述する
この一文があるかないかで、出てきたMarkdownの読みやすさが大きく変わります。頭にスムーズに内容が入ってくるかどうかの違いが明確にわかります。
ステップ2: 非エンジニア向けに翻訳
エンジニア向けガイドをそのまま公開すると、ソースコードの話がかなり多くて、普段コーディングをしない人がたどり着いた時に読むのを諦めて、結局エンジニアに質問される可能性があります。
そこで、Copilotに「部署関係なく全社員が理解できるようにまとめて」と指示し、専門知識なしでも読めるようにしました。
実際に使用しているプロンプト例
全社員向け要約版作成時:
(エンジニア向けのレポートを添付する)
部署関係なく全社員が理解できるようにまとめて
出てきたファイルを確認すると、ソースコードの話は丸々カットされ、「この機能はどんなもので、どういった理由があって制約事項ができているのか」がパート分けされていました。
ガイドの運用ルール
Confluenceでガイドを管理する際は、以下のルールで運用しています。
- 親ページの作成: ガイド専用の親ページを作り、作成場所を統一
- 子ページとして追加: 各ガイドは親ページの子ページとして追加
- フォルダ分け: エンジニア向けの詳細ページと全社員向けの要約版はフォルダで分ける
- インデックスの設置: 親ページにインデックスを貼り、目的のガイドにリンクジャンプできるようにする
以下は、Confluenceでの階層構造のイメージです。
このような構造化により、検索性と可読性を向上させています。
社内からの反応
個人が自由に書き込める分報に、公開したページのリンクを載せて案内しました。
すると、PdMやカスタマーサービス、営業メンバーからいいねスタンプや驚き顔スタンプが送られてきました。特に「神」スタンプをもらった時は達成感を感じました。
この反応を見る限り、みんな口に出していないだけで、仕様がわかるページが欲しかったのだと見ることができます。
今すぐ始められる3ステップ
Step 1: 小さく始める（所要時間: 5分）
-
よく問い合わせが来る機能を1つ選ぶ
- まずは小規模な機能から
- 「なぜこの制約があるのか？」がよく聞かれるもの
-
GitHub Copilot Chatを開く
- VS Codeのサイドバーから起動
-
「この機能の仕様ガイドを作成してください」と依頼
- プロンプトに「初めてジョインしたエンジニアでも理解できるように」を追加
Step 2: エンジニア向けガイドを作る（所要時間: 5分）
-
調査項目を入力
- 機能の概要、実装コード、使用条件、技術的課題など
-
生成された内容を確認・修正
- ソースコードの引用が正しいか確認
- 不足箇所を追記
Step 3: 非エンジニア向けに翻訳（所要時間: 5分）
-
Copilotに「部署関係なく全社員が理解できるようにまとめて」と依頼
-
専門用語が残っていないか確認
-
Confluenceに公開
- 社内Slackで告知
FAQ
Q1. トークンが足りなくなったらどうする？
A: 以下の優先順位で調整しています：
- 実装・バグ修正（最優先）
- コードレビュー
- ガイド作成（余裕があれば）
トークン消費を抑えるため、ガイド作成時はSonnetを使用し、Opusは重要案件のみに限定しています。調査タスクによっては0.5%程度の増加で済むため、想像以上にコストは抑えられます。
Q2. ガイドを読んでもらえないことはない？
A: 以下の工夫をしています：
- 分報で告知: 新規ガイド公開時は必ず分報でリンク共有
- 検索性の向上: Confluenceのラベル機能やインデックスを活用
- 読みやすさ重視: 専門用語を極力排除し、図表を積極的に使用
実際に「神」スタンプなど、多くのポジティブな反応をもらっています。
Q3. ガイドが古くなったらどうする？
A: 機能変更時に必ず更新するようにしています。また、親ページにインデックスを設置することで、どのガイドがいつ更新されたか一目で分かるようにしています。Confluenceのバージョン管理機能も活用し、変更履歴を追跡可能にしています。
まとめ
AIを使ってリポジトリ内容を解析し、仕様をみんながスッと理解できるページ作りに努めてきました。社内の反応を見ると、このような取り組みが求められていることは確かなようです。
この取り組みにより、以下の効果を実感しています：
- 非エンジニアでも仕様を理解できるガイドの作成（全社公開7件）
- 自分自身のアプリ理解が深化（他チームの機能も説明可能に）
ガイド作成のトークン消費は想像以上に少なく、調査タスクによっては0.5%程度の増加で済むこともあります。私にとってもアプリに対する理解を深めるプラスの効果を与えてくれる有意義な取り組みです。
これでエンジニアに来るお問合せが減るかどうかは、今後のお楽しみです。
今後も、気になった機能を見つけたらガイドを作成し、ナレッジの蓄積を続けていきます。
関連記事
開発向けドキュメント（調査書・実装計画書）の作成プロセスを解説。本記事とは異なり、エンジニア向けの技術資料作成に焦点を当てています。
Claudeで作成したドキュメントをo1-previewでレビューする品質管理フロー。実際の指摘事例も掲載しています。
Discussion
今まさに僕がやろうとしていることの実践例があってありがたい🙏
契約の関係でGemini 3 を使おうとしています。