ドキュメントの重要性は誰もが理解していながら、いざ書くとなると後回しになりがちです。コードは更新され、機能はアップデートされていく一方で、ドキュメントは次第に実装とずれていきます。その結果、新しくチームに加わったメンバーはシステムの仕組みを理解するのに苦労し、ベテランの開発者でさえ、本来ドキュメント化されているべき内容をコードから読み解くために時間を費やすことになります。
こうした課題は、AI による開発支援の普及によってさらに顕著になっています。AI コーディングアシスタントを使えば機能を数分で実装できる反面、ドキュメントはますます後回しになりがちです。手動で時間をかけて書いたコードなら丁寧にドキュメント化できたかもしれませんが、AI が数秒で生成したコードはドキュメントなしでそのままリリースされることも少なくありません。その結果、コードベースの実際の挙動と、チームが理解している内容との間にギャップが生まれていきます。
CircleCI の自律型 CI/CD エージェント「Chunk」は、AI を活用したドキュメント生成機能を CI パイプラインに直接組み込むことで、この課題を解決します。個々のファイルを対象とする IDE ベースのツールとは異なり、Chunk はコードベース全体を分析し、モジュール同士の関係を理解したうえで、実装内容に基づいた包括的なドキュメントを生成できます。この記事では、Chunk を使ってドキュメントを自動的に改善する方法をご紹介します。
Chunk のセットアップ
Chunk を使い始めるには、CircleCI アカウントと、すでにパイプラインが実行されているプロジェクトが必要です。CircleCI を初めて使う場合は、スタートガイドでリポジトリの連携方法をご確認ください。
このガイドでは、ご自身のプロジェクトを使って進めることもできますし、すぐに試せるサンプルとして GitHub 上のデモプロジェクトを利用することもできます。
CircleCI 上でプロジェクトが実行されていることを確認したら、次の手順で Chunk をセットアップします。
- CircleCI の Web アプリサイドバーから Chunk を選択します。
- Set up Chunk をクリックし、表示される手順に従って GitHub へのアクセスを認可します。Chunk はリポジトリを解析するための読み取り権限と、ドキュメント更新用のプルリクエストを作成するための書き込み権限を必要とします。
- モデルプロバイダーの API キーを選択します。CircleCI が提供する組み込みキーを利用することもできますし、Anthropic や OpenAI の API キーを接続することも可能です。CircleCI のキーを使用する場合、利用可能なトークン数に上限があります。
Chunk は既存の CircleCI パイプラインに直接統合されるため、追加の設定変更は必要ありません。認証が完了すると、リポジトリのコードとビルド履歴の両方を解析し、プロジェクトの構造を把握します。詳細なセットアップ手順については、Chunk のドキュメントをご覧ください。
Chunk にドキュメント改善を依頼する
Chunk を有効化したら、サイドバーから Chunk を選択します。すると、Chunk に実行してほしい内容を入力できるプロンプト画面が表示されます。
シンプルなプロンプトを入力するか、用意されているプリセットの中から選択します。ここでは「Improve documentation（ドキュメントを改善する）」プリセットを選択します。プリセットをクリックすると、以下のプロンプトが自動で入力されます。
Add or improve documentation for key functions and components.
Submit をクリックすると、Chunk が処理を開始します。Chunk は CI/CD 環境上で動作するため、コードベース全体にアクセスして、モジュール間の関係、関数のシグネチャ、使用パターンなどを包括的に解析できます。こうした情報をもとに、実際の実装内容を反映したドキュメントを自動生成します。
結果を確認する
Chunk の分析が完了すると、生成されたドキュメントの概要が表示されます。この画面から変更内容を確認し、プルリクエストを作成するかどうかを判断できます。変更内容に満足できない場合は、プルリクエストを作成せずにプロンプトを修正することも可能です。
Chunk は以下のように変更内容を説明します。
Summary
Expanded the README with complete API documentation covering all
validators, transformers, processors, and exporters. Added detailed
function signatures, parameters, return types, and usage examples
for each module.
Changes
Enhanced project description with feature highlights
Added comprehensive API Reference section with:
- Validators: validateEmail, validatePhone, validateDate, validateCurrency
- Transformers: csvToJson, normalizeData
- Processors: processBatch, createPipeline
- Exporters: exportToJson, exportToJsonLines, parseJsonSafely
Included detailed examples and expected outputs for each function
Added development and testing sections with new commands
Replaced basic usage section with detailed API reference documentation
変更内容に問題がなければ、Open Pull Request をクリックして、リポジトリにプルリクエストを作成します。
マージ前に、生成されたドキュメントがコードの動作を正確に説明しているか必ず確認しましょう。Chunk は実装を解析してドキュメントを生成しますが、記述内容が設計の意図と一致しているかどうかは、人の目で確認することが重要です。
より具体的なプロンプトの活用
「Improve documentation（ドキュメントを改善する）」というシンプルなプロンプトは、ドキュメント全体の抜け漏れを補うのに有効です。より細かく指示したい場合は、具体的なプロンプトを試してみてください。
特定のモジュールをドキュメント化する場合：
Add JSDoc comments to all functions in src/validators
README を更新する場合：
Update the README with installation instructions and usage examples
複雑なロジックを説明する場合：
Add inline comments explaining the pipeline execution flow in
src/processors/pipeline.js
API ドキュメントを生成する場合：
Create API documentation for all exported functions with parameter
types and return values
特定の読者向けにドキュメントを作成する場合：
Add documentation to the transformers module aimed at developers
who are new to the codebase
プロンプトが具体的であればあるほど、Chunk が生成するドキュメントも的を絞ったものになります。
詳細設定
基本的な操作に慣れてきたら、Chunk のカスタマイズ設定を活用しましょう。
環境のセットアップ
依存関係やビルドプロセスが複雑なプロジェクトでは、.circleci/cci-agent-setup.yml ファイルを用意することで、Chunk に環境の準備方法を明示できます。
ドキュメント生成にテストの実行が必ずしも必要というわけではありませんが、型情報やモジュールのエクスポート、生成されたコードを理解するために、プロジェクトのビルドが必要になる場合があります。主なユースケースは以下のとおりです。
- TypeScript プロジェクト: 型定義を生成するためのビルドステップ
- 生成コード: API クライアントや GraphQL 型など、コード生成に依存するドキュメントの場合
- モノレポ: 複数パッケージを横断するための設定
- カスタムビルドツール: 標準的でないビルドプロセスを使用するプロジェクトの場合
以下は、TypeScript プロジェクト向けの設定例です。
version: 2.1
workflows:
main:
jobs:
- cci-agent-setup
jobs:
cci-agent-setup:
docker:
- image: cimg/node:20.11
steps:
- checkout
- run:
name: Install Dependencies
command: npm ci
- run:
name: Build TypeScript
command: npm run build
この設定では、環境の準備に必要な処理のみを記述してください。コードの解析方法は、プロジェクト構造をもとに Chunk が自動的に判断します。
必要に応じて、Chunk はこのファイルを自動生成しようとします。手動で作成することも可能です。Organization Settings -> Chunk Tasks から対象タスクのメニュー（…）を開き、Chunk Environment → Create File in GitHub をクリックします。詳細については、Chunk 環境のドキュメントをご覧ください。
カスタム指示
生成されるドキュメントをチームの規約に合わせるには、リポジトリのルートに claude.md または agents.md ファイルを作成し、以下のような設定を記述してください。
- ドキュメント形式（JSDoc、TSDoc、docstring など）
- コードの種類に応じた記述の詳細度
- 使用例の有無
- 文体やトーン（フォーマル、カジュアルなど）
- 多言語ドキュメントで使用する言語
Chunk はこれらのファイルを読み込み、設定された方針に従ってドキュメントを生成します。
ドキュメントの一貫性
Chunk は、既存のドキュメントのパターンを参照することで、コードベース全体のドキュメントの一貫性を保つことができます。よくドキュメント化されているモジュールがあれば、それをテンプレートとして類似モジュールのドキュメントを作成します。これにより、プロジェクト全体で文体やフォーマットの統一を保つことができます。特に、時間の経過とともに複数のチームメンバーがドキュメント作成に関わっているプロジェクトでは、この機能が大きな価値を発揮します。
AI 開発エコシステムにおける Chunk
AI コーディングアシスタントを使えば IDE でのコーディングが格段に速くなりますが、ドキュメントは後回しになりがちです。Chunk は CI/CD パイプライン上で動作するため、コードベース全体を解析でき、実装を忠実に反映したドキュメントを自動生成できます。
このアーキテクチャは、AI を活用した開発ワークフローに自然なチェックポイントをもたらします。AI アシスタントによって生成されたコードは CI/CD を通ってリリースされますが、その過程で Chunk が適切なドキュメントが付いているかを保証します。開発者が AI 生成コードのドキュメント化を忘れないよう意識し続けなくても、Chunk が自動的に対応します。
AI コーディングアシスタントを利用しているチームに向けて、CircleCI は CircleCI MCP サーバーも提供しています。Model Context Protocol（MCP）を介して AI アシスタントとパイプラインを直接連携させることで、IDE の AI ツールと CI/CD インフラをより密に統合できます。Chunk と MCP サーバーを組み合わせることで、コード品質・テスト・ドキュメントがすべて自動的に維持される、統合された AI 開発ワークフローを実現できます。
まとめ
古くなったドキュメントや不足しているドキュメントが、チームの生産性を下げる必要はありません。Chunk はコードベースを解析してドキュメントの抜け漏れを特定し、誰もが理解しやすい正確なドキュメントを自動で生成します。AI を活用した開発によってコード変更のペースが加速する中、ドキュメントを常に最新の状態に保つ自律型エージェントは、チームの生産性を維持するうえで欠かせない存在となっています。
ぜひご自身の環境で試してみてください。無料の CircleCI アカウントに登録し、Chunk を有効化することで、ドキュメントの自動改善をすぐに始められます。
