1. はじめに
こんにちは。AI Central 事業部にてエンジニアをしております、ぽちぽちです。
AI Central 事業部では新規事業として、お客様の VoC データなどを LLM により構造化し、経営戦略・製品開発戦略等のアクションプランへ落とし込む「AI Central Voice」を開発しています。このようなサービスを作る上で、LLM を製品に組み込むことはもちろん、エンジニア、非エンジニア問わずチーム全員で意識的に LLM を活用し生産性を上げることを意識して、日々業務をこなしております。
今回はAI Central事業部にて、サービスのアーキテクチャやサービス仕様などを記載した開発ドキュメントをどのように管理し、生産性と品質を両立させているかについてご紹介していきます。具体的には
- 課題に対してチームが取ったドキュメント戦略
- LLM による開発ドキュメント自動更新の仕組み構築と開発フローへの適用
- 仕組みを導入する上でのチームの巻き込み方
等について具体的にどうのようにやったのかをご紹介いたします。開発ドキュメントに悩んでいる方々にとって参考になれば幸いです。なお、以降は簡略化のため「ドキュメント=開発ドキュメント」として説明していきます。
2. なぜドキュメント管理？
新規事業では業務委託や本体事業部からの一時的なリソース借用など、人の出入りが激しいです。適切なドキュメント管理をすることで新規メンバーのキャッチアップ速度向上や属人化防止、サービス品質向上への効果が見込めます。
しかし、ドキュメント管理は面倒な作業であり、特に機能追加や変更が頻繁な0→1フェーズのサービス開発では優先度が低くなりがちです。
3. AI時代のドキュメント戦略
そこで我々は LLM を活用し、ドキュメントメンテナンスのコストを最小化しつつ、形骸化しないドキュメント戦略を考案しました。
3.1. 従来のドキュメント管理の課題
戦略立案にあたり、まず従来のドキュメント管理における課題を整理しました：
- 情報の不整合： GitHub、Notion 等に分散した情報の同期が取れなくなる。
- ドキュメント品質のばらつき： 作成者によりドキュメントの品質にばらつきが生じる
- 手動更新の負担： コード変更のたびの手動更新が開発者の負担になる
- 検索性・活用性の悪さ： 必要な情報の所在が不明確で必要な情報を見つけられない
0→1フェーズのサービス開発では、技術的負債を適切に管理しながら高速に開発を進める必要があります。初期実装が変わらないことは稀であり、新規メンバーも増える中、機能・組織ともに変化が激しいフェーズでは、属人化を防ぎ、サービスの現状を正確に理解できる最新のドキュメントが重要です。
3.2. ドキュメント戦略の立案
これらの課題を解決するため、以下の方針でドキュメント戦略を策定しました：
- Single Source of Truth： すべての情報を GitHub リポジトリ内で一元管理
- 統一されたドキュメントポリシー： ヒトと AI 双方が同品質のドキュメントを作成できるポリシーの策定
- ドキュメント更新の自動化： LLMを活用した継続的なドキュメント自動更新の仕組み
- ドキュメント活用基盤の構築： ヒト/AIがドキュメントを活用できるような基盤/仕組みづくり
4. どのようにドキュメント戦略を適用したか？
立案したドキュメント戦略を具体的にどのように適用したかご紹介していきます。
4.1. Single Source of Truth
当初、チーム内ドキュメントは Notion や Github リポジトリに分散していました。そこで、Github リポジトリ内にwikiディレクトリを作成し、開発ルール、機能詳細、技術的負債など全ての情報を markdown で一元管理することにしました。
wikiでの一元管理にあたり、弊社では Devin を利用していたため、DevinWiki の内容をベースに加筆修正し、技術的負債も追記して機能の現状をより正確に表現しました。また、Notion 内のチーム開発ルール等も markdown 化して移行しました。
4.2. 統一されたドキュメントポリシー
次に、チーム内で統一されたドキュメントポリシーを作りました。 wiki にドキュメントを追加するとなっても全ての情報を wiki に追加すれば他のドキュメントは書かなくてよいというわけではありません。README にはそこに書くべき内容があり、 コード内ドキュメントにも書くべき内容があります。それらを改めてまとめ、チーム内のドキュメントポリシーとして策定し、その内容もチーム内開発ルールとして、 wiki に追加しました。
詳細は割愛しますが、5W1Hの観点でドキュメントポリシーを議論し整理しました：
4.3. ドキュメント更新の自動化
ドキュメント更新の自動化には Claude Code Github Actions を活用しました。Claude Code Github Actions は GitHub Actions ワークフロー内で Claude Code を実行できるツールです。インストール方法は公式ドキュメントに従い、claude code コマンドをローカル環境にインストールし、/install-guithub-appを実行するだけで導入できます。ここでは AI Central 事業部でのドキュメント自動更新の仕組み構築に焦点を当てます。
また、似たアウトプットとして Devin の Deep Wiki がありますが、これは全自動でコードを読み取り wiki を作成するため、開発ルールまで管理し、全ての情報を一元管理したかったので今回は見送りました。その他、Gemini CLI などのコーディングエージェント等も検討いたしましたが、開発フローと統合しやすく、現場では Claude Code がよく利用されていたことから、Claude Code Github Actions を採用いたしました。
様々な試行錯誤を経て、ドキュメント自動更新の仕組みは以下のように構築しました：
- PR 毎のドキュメント自動更新： リリース単位での更新は変更差分が多くコンテキストが複雑化し精度が低下したため、PR 単位での更新に決定
- 任意タイミングでの実行： 独自コマンド
@cc-update-wikiを PR 内でメンションするだけで更新できるワークフローを設計 - PR テンプレートへの組み込み： PR テンプレートに
@cc-update-wikiを追記し、PR 作成時に必要に応じて自動更新できるよう修正
ワークフローにすると以下のようになります。
また、ドキュメント自動更新のためのワークフローのサンプルを追記しておきます。
name: Update Wiki on: issue_comment: types: [created] pull_request_review_comment: types: [created] pull_request_review: types: [submitted] pull_request: types: [opened] jobs: update-wiki: if: | ( (github.event_name == 'issue_comment' && contains(github.event.comment.body, '@cc-update-wiki')) || (github.event_name == 'pull_request' && contains(github.event.pull_request.body, '@cc-update-wiki')) || (github.event_name == 'pull_request_review_comment' && contains(github.event.comment.body, '@cc-update-wiki')) || (github.event_name == 'pull_request_review' && contains(github.event.review.body, '@cc-update-wiki')) ) runs-on: ubuntu-latest permissions: contents: write pull-requests: write id-token: write steps: - name: Checkout repository uses: actions/checkout@v4 with: fetch-depth: 1 - name: Run Claude PR Action uses: anthropics/claude-code-action@beta with: anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }} timeout_minutes: "20" trigger_phrase: direct_prompt: | あなたはテクニカルドキュメントの専門家です。提供された変更履歴を分析し、wiki ディレクトリ内の関連するマークダウンファイルを更新または新規作成し、このPRにコミットしてください。 PR内の変更ファイル: $CHANGED_FILES 以下のガイドラインに従ってください： 1. PR内のファイル変更内容を分析し、wiki配下の影響を受ける可能性のあるドキュメントを特定する 2. ドキュメントは日本語で記述する 3. 以下の形式でドキュメントを構成する： - 概要 - 実装の詳細（アーキテクチャ、データフロー） - 注意事項（該当する場合） - 技術的負債や今後対応予定の内容（具体的な課題と対応方針） 4. wikiを変更する必要がなければ、その旨をGithubにコメントしてください。その場合も、なぜ変更が不要と判断したかの理由を簡潔に説明してください。 ## ドキュメント更新の例 良いドキュメント更新の例： \`\`\`markdown # テスト属性機能 ## 概要 テスト属性機能は、テスト属性を作成・削除する機能です。 ## 実装の詳細 ### データモデル - \`TestAttribute\`: テストデータに付与される属性を表すモデル - \`id\`: 主キー - \`xxx_attribute_id\`: 関連する属性ID - \`value\`: 属性値 ### 提供メソッド - \`create_test_attribute()\`: テスト属性の作成 - \`delete_test_attribute()\`: テスト属性の削除 ## 注意事項 - 属性定義が存在しない場合はエラーになります - 属性値は属性定義で指定された型に従う必要があります ## 技術的負債と今後の対応 - パフォーマンス最適化: 大量のテスト属性を一括作成する機能の追加 - バリデーション強化: 属性値の型チェックの改善 \`\`\`
上記はこちらのサンプルコードをベースに、独自のコマンド + プロンプトの例を入れています。（2025年8月時点での情報を基にサンプルを構築しています。実際に利用される場合は自己責任でお願いいたします。）上記のプロンプトのポイントは
- ドキュメントのガイドラインを明示
$CHANGED_FILESなどの有益な変数の利用 (ref)- ドキュメントフォーマットの例示
です。特に「ドキュメント更新 ガイドライン」の 4. wikiを変更する必要がなければ、その旨をGithubにコメントしてください。その場合も、なぜ変更が不要と判断したかの理由を簡潔に説明してください。 は非常に効果的で、不要な変更を防ぐことができます。加えて、$CHANGED_FILES などの有益な変数の利用を行うことで、効率的に変更内容を LLM に伝えることができ、最後に実際のドキュメントフォーマットを例示することで、ドキュメントに一貫性をもたせることができます。
このワークフローが正常に実行されると、PR 上では以下のように Claude からコメントが追加され、PR に wiki を更新したコミットが追加されます。
このように、 ドキュメント更新を独自コマンドとしてワークフローに組み込むことで、他のClaude Code Actions のワークフローとコンフリクトさせることなく、実行させることができます。
4.4. ドキュメント活用基盤の構築
最後の仕上げとして、LLM がドキュメント活用できるようにするための仕掛けを加えました。やることは簡単です。Claude Code を利用していれば、 CLAUDE.md に以下の文を追記するだけです。
`wiki`に提供機能の説明やチーム開発ルールをmarkdownで記載しています。必要に応じて、これらを参照してください。
上記の要求でもドキュメント量が極端に多くなければ、LLM はwikiディレクトリ内のファイル名等から参照すべきドキュメントを適切に選択している印象です。
これにより、現在提供している機能の内容やチーム開発ルールなど、開発に必要なあらゆる内容について質問しても適切に回答してくれるようになりました。
試しにデプロイフローについて聞いてみると、このように回答が来ました。コードからは読み取れないブランチ戦略なども wiki から読み取り正確に回答してくれています。
5. 導入してみて
Claude Code Github Actions によるドキュメント自動更新の仕組みを導入し、しばらく運用し、良かったことと改善できそうなことをそれぞれまとめます。
5.1. 良かったこと
- ドキュメント更新の負担を大幅減： PR 毎にドキュメントが更新されるので、変更点も最小化することができ、かつレビュワーにとってもドキュメントの内容をチェックしやすくなりました。
- ドキュメントに対する意識の向上： 技術的負債のドキュメントへの追記などの PR が目立つようになりました（下に添付のスクショ参照）。これは、ドキュメントに適切に情報を記載する意識が向上したためだと思っています。
- ドキュメント品質の向上： 網羅的にドキュメント整備され、適宜更新されているので、LLM に質問を投げかけた時の回答体感精度の向上や、自身が知らない機能もドキュメントを読めば大方理解できるようになりました。
- 技術的負債の明確化： 現在のサービスが戦略的に取ってきた技術的負債をドキュメントに落とし込むことで、それらの優先順位をつけることができ今まで以上に品質改善しやすくなりました。
↓ チームメンバーが作成した、技術的負債をドキュメントに追記したPRです。いつも丁寧な仕事をしてくれて感謝していると同時に、エンジニアとして私も日々刺激を受けています。
5.2. 改善できそうなこと
- ドキュメント活用が不十分： ヒアリングをしているとドキュメントをまだまだ有効活用できていない人もいる印象です。ドキュメントは活用されてこそ、初めて整備する意味が生まれるので、特に LLM を用いたドキュメント活用術についてもチームに普及していく必要がありそうです。
- 歴史的な機能変遷や設計意図の欠如： これは意図的に今回のスコープから外しましたが、Design Docs などの過去に行なった機能の設計意図も同じようにリポジトリ管理していっても良いと思っています。
- コード内ドキュメントの品質向上： コード内ドキュメントの品質も、同じような仕組みで改善できそうな気がしています。こちらも同様に人によって品質のばらつきがあるため、将来的にはコード内ドキュメントも合わせて改善できればと思っています。
6. ドキュメント管理に悩む人へ
最後にドキュメント管理へ悩む人へ実際に私が試行錯誤してきた知見を共有します。
- 小さく始める： チームの大きさに関わらず、小さく始めることをおすすめします。私はバックエンドがメインかつ新規事業ということもありドキュメントの数もそこまで多くなかったので、バックエンドのドキュメント整備から着手しました。歴史のあるサービスの場合、例えば新機能開発の時だけ試験運用するなどでも良いかもしれません。小さく始めれば、もし問題があっても影響は少ないですし、何よりも改善サイクルを高速に回すことができます。何か成功事例があり、メンバーがそのメリットを理解してくれれば、その後の展開は容易になります。
- メンバーを巻き込む： ドキュメントは広く使われてこそ意味があります。うまくメンバーを巻き込み、仕組みを一緒に作り、体験してもらいましょう。例えば私はドキュメントに対して同じ問題意識をもつメンバーとサイドプロジェクトとして本件に取り組み、仕組みができた後はチームメンバーからフィードバックをもらいながら改善しました。
- ポリシーの策定/修正： 仕組みの変化は時にチームを混乱させる場合があります。特に今回導入したドキュメント更新の仕組みでは、大きくドキュメントのあり方/管理方法を変えたため、それに対応できないメンバーが出てくる可能性があります。それを防ぐため、"4.2. 統一されたドキュメントポリシー"での記載の通り、5W1Hの観点でドキュメントポリシーを議論しまとめ、認識をそろえたことで大きな混乱もなくスムーズに移行できました。
7. まとめ
AI Central 事業部での生産性と品質を両立するためのドキュメント管理方法について、ご紹介いたしました。私自身、サービスの早い変化に追従するために苦労することがありましたが、このようにドキュメントを一元管理し、かつそれを自動更新する仕組みを導入することで、コード実態とドキュメントの乖離がなくなり、簡単にキャッチアップできるようになりました。
ですが、まだこれは始まりにすぎません。ドキュメント管理は自動化すれば解決するような問題ではありません。メンバー一人ひとりが強い意思でメンテナンスしていかなければ、すぐにこのフローは形骸化し、ドキュメントは陳腐化してしまいます。そのためにもメンテナンスされているドキュメントをより広く有効活用してもらい、ドキュメントを最新の状態に保つためのインセンティブを持たせる必要があります。
"5.2. 改善できそうなこと"でも記載しましたが、私はネクストステップとして、このドキュメント活用方法をチーム内で展開しようと思っています。将来的にドキュメント活用方法の知見がまとまり、皆さんにご共有できるようになりましたら、またテックブログ等でご紹介したいです。
