こんにちは！ウォンテッドリーでバックエンドエンジニアをしています、平岡です。

今回は、GitHub上で情報を構造化し、「実行計画」から「開発」までを一気通貫で行うためのAIを活用したドキュメンテーション技術の実践について紹介します。

このテーマに取り組んだ背景

プロジェクトを進めていく上で企画段階からも開発に入っても仕様変更やスコープの変更は発生します。ドキュメントが古いままだとAIに指示をするたびにアドホックなプロンプトを入力することになり、人手が必要になってしまいます。そうなるといくら高性能なAIを活用する機会があっても、そのAIを使う人間がボトルネックになってしまい、生産性を高めていくことが難しくなります。ドキュメントを最新に保つことは、AIだけでなく、そのドキュメントを参照する関係者すべてに鮮度の高い情報を届けることができるため、その作業を効率化できることはチーム全体の生産性向上につながると考え、この取り組みを進めました。

前提：「実行計画」とは

本記事では、プロダクト要求仕様（PRD）をインプットとして受け取り、開発の準備が整うまでの一連の作業を「実行計画」と定義します。

一般的な「要件定義」に近いですが、単に「何を作るか」を決めるだけでなく、エンジニアが迷いなく実装できるタスクレベルまで落とし込むことをスコープに含めています。

前提：情報の構造化の方針

情報を構造化するにあたり、それぞれの要素を以下のように定義・マッピングしてGitHubのIssueで管理します。

• WHY（なぜやるのか）= PRD
• • 解決するべきユーザーの課題、成功/失敗の基準、伸ばしたい数値、やることとやらないこと。
  • GitHub上では Root Issue (Epic Issue) として扱います。
  • 想定する読者は、プロジェクトに関わるステークホルダー全員です。
• WHAT（何を提供するのか）= ユーザーストーリー
• • ユーザーにとっての価値や具体的な機能や、何をすればこのストーリーが完了するかの定義（完了条件）が含まれます
  • GitHub上では、Epicの Sub-issue として登録します。
  • 想定する読者は、プロジェクトに関わるステークホルダー全員です。
• HOW（どう実現するのか）= タスク
• • ユーザーストーリーを完成させるための技術的なアプローチや詳細設計。
  • GitHub上では、ユーザーストーリーをさらに分解した Sub-issue となります。
  • 想定する読者は、ユーザーストーリーを完成させることに直接関わるメンバーです。

Github Projectsを使うと、以下のようにユーザーストーリーとしてのSub-issueを紐付けたものになります。このようにSub-issueで意味的構造を表現しています

基本編：具体的な進め方とAIの活用法

1. どのようにしてAIを活用してGitHubのドキュメントを読み書きするのか？

ウォンテッドリーはClaude Codeが利用できるようになっており、開発者自身のGitHub認証情報とGitHub CLI（gh コマンド）を活用して、開発者自身のアクセス可能なリポジトリのIssueを読み書きします。

2. アイデアの検討段階からドラフトを作成する

完全に要件が決まりきっていないアイデアの段階から、AIをアシスタントとして活用します。 「こんな機能を作りたい」という機能案をAIに伝え、それをユーザーストーリーの形式に落とし込んでもらいます。これをEpicのSub-issueとして登録していきます。

3. ユーザーストーリーにタスクを紐づけ、設計を行う

PdMやデザイナーとの連携を通じてWHAT（ユーザーストーリー）が固まり出したら、それをエンジニアが進めやすい粒度のタスクを登録していきます。

このフェーズでは、以下に示した進め方で詳細設計をIssueの本文に記載します。

プロンプト例（AIへの指示）

 以下のユーザーストーリーを実現するためのAPI設計のIssueを作成してください。
ユーザーストーリー：「求職者として、気になった求人を後から読み返せるようにブックマークできる」
対象リポジトリ: wantedly-backend の既存の設計規約に従うこと
エンドポイント: POST /api/v1/bookmarks
必要なパラメータとレスポンスのJSON構造を含めること。

AIは、以下のようにマークダウン形式で記載をしてくれます。

### エンドポイント
`POST /api/v1/bookmarks`

### リクエストパラメータ
| 名前 | 型 | 必須 | 説明 |
| :--- | :--- | :--- | :--- |
| `job_post_id` | String | ◯ | ブックマークする求人記事のID |

### レスポンス (200 OK)
```json
{
  "data": {
    "id": "bm_123456789",
    "user_id": "usr_987654321",
    "job_post_id": "job_11223344",
    "created_at": "2024-05-20T10:00:00Z"
  }
}
```

ここまでの作業で、WHY - WHAT - HOWの形でドキュメントが登録できました。この後は、開発に入るタイミングで以下のように指示することで実装を進めていくことができます。

https://github.com/wantedly/xxx/issues/12345
このタスクを進めて欲しいです。その際このParent issue（ユーザーストーリー）、
さらにそのParent issue（PRD）も読んで背景を理解した上で進めてください

応用編：ユーザーストーリーを分解する

ユーザーストーリーの工数見積もり規模が大きいと進める間、実際は開発が進んでいるのにも関わらず、このユーザーストーリーが何週間もIn Progressのまま滞留することになります。エンジニアはタスクの消化率で進捗を測ることができるかもしれませんが、それではプロジェクトに関わるメンバーの共通認識を得ることは難しい場合があります。

そういう場合には、ユーザーストーリー自体を分解して一つのストーリーあたりのサイズやスコープを減らす方法が有効です。

ステークホルダーにとっての「価値」の単位で分解する

ユーザーストーリー分解する時も、ユーザーストーリーの形式（誰がどのような価値を享受できるのか）を意識して分割します。分割の仕方はそのサイズによって色々ありますが

例えば「求職者として、気になった求人をブックマークできる」というストーリーは、「開発者」を主語にして以下のように分割します。

• 開発者は、求職者が気になった求人をブックマークできるAPIをフロントエンドに提供できる
• 開発者は、ブックマークボタンUIを求人詳細画面に実装できる

私自身は、このようにAPI開発を切り出す方法はよくやります。

実際、大抵のアプリ開発の場合APIが先に用意されていると都合が良いためAPIの開発が依存関係として先に終わらせておきたいと考えます。その依存関係をリストの優先順位で管理することで進捗が見えやすくなります。また後続に控えるフロントエンドの実装やAPI繋ぎこみのissueとAPIの仕様記述が分離されることで、それぞれが、ドキュメントとしても見通しの良いものになります。

Github Projectsを使うと、以下のように作成されたissueがツリー構造で一覧確認できます。

実践してみて感じた効果

このやり方を実践してみて、一貫したドキュメントを書く負担が下がり、早い段階から網羅性の高いドキュメントをドラフトすることができるようになりました。また施策自体が検討段階でも、メンバーへ状況を共有することができるようになり、情報共有の頻度やクオリティも向上したと感じています。

さらに、実行計画の段階では、要件の追加や「この仕様は変えたい」といった変更が日常茶飯事です。人間が手動でドキュメントを管理していると矛盾が生じがちですが、AIにコンテキストを保持させておけば、以下のような変更も一瞬で処理できます。

• 「APIは別のリポジトリに変更するから、その前提で設計変更と依存関係の更新を行って」
• 「レスポンスに紐づく企業情報も追加して」

ドキュメント全体の一貫性を崩さずに情報を更新できるため、そのままAIに「このIssueの通りにコードを実装して」と依頼することが非常にスムーズになります。 （※UI仕様がFigmaなどの画像情報に依存するフロントエンドに比べ、バックエンド実装では特にこのやりやすさを実感できます。）

実践してみて感じた課題

AIが生成したドキュメントは、レビューが必要です。一度に多くのドキュメントを生成させてしまうと、その分レビューが大変になり、生成させたはいいがちゃんと意図が伝わっているのかの確認コストがかかってしまいます。ここは「変更前後の差分だけを再度AIにサマリさせてから目視チェックする」などの工夫を取り入れることで、認知負荷を下げながら運用しています。

おわりに

本記事では、変更されることを前提としてAIを活用し、ストレスなくドキュメントの更新を行う知見をお話しさせていただきました。