ドキュメントと実装の乖離を発見し修正計画を立てた話（開発日記 No.092）
関連リンク
はじめに
昨日はプロジェクト全体の整理を進め、不要なファイルや機能を削除したり、ドキュメント整備に関するIssueを更新したりしました。今日はその流れを受けて、さらにドキュメント整備を具体的に進め、合わせてプロジェクトの品質保証体制についても考え始めることにしました。
背景と目的
開発を進める中で、コードだけでなく、それを説明するドキュメントの重要性を改めて感じています。特に、将来的に他の担当者に引き継ぐ可能性を考えると、ドキュメントが最新かつ正確であることは必須です。また、プロジェクトの品質を担保するためには、どのようなテストを行い、どのように品質を保証していくのかという体制も明確にする必要があります。
そこで今日の目的は、まずドキュメントの現状を把握し、実装との乖離をなくすこと。そして、テストと品質保証についての方針を検討することに置きました。特にドキュメントについては、「ドキュメントを唯一の正とする」という強い方針を立て、実装側をドキュメントに合わせることで、常に最新の仕様がドキュメントに反映される仕組みを目指すことにしました。
検討内容
まずは、プロジェクトのdocsディレクトリにある既存のドキュメント類（architecture.md, features.md, installation.md, specification.md, supported_llm_providers.mdなど）を確認するところから始めました。それぞれのドキュメントが何について書かれているのか、現状の実装と比べて古くなっていないかなどをざっと見ていきました。
その過程で、「ドキュメントを唯一の正とする」という方針をより明確にしました。これは、もしドキュメントと実装に違いがあった場合、ドキュメントに書かれている内容を正しい仕様とみなし、実装の方を修正するという考え方です。これにより、ドキュメントが常に最新の仕様を反映する状態を保ちやすくなります。ドキュメントに書かれていない機能や挙動は「仕様逸脱」として扱い、必要に応じて修正や仕様変更の検討を行うことにしました。
この方針のもと、各ドキュメントと実際の実装コードを照合し、具体的な差異を洗い出す作業を進めました。
実装内容
今回は主にドキュメントと実装の差異を分析し、今後の修正計画を立てる作業が中心でした。具体的なコード修正や機能追加は行っていません。
行った作業としては、以下の通りです。
-
docsディレクトリ内の各ドキュメントの内容を確認。 - ドキュメントに記載されている仕様（CLI引数、環境変数、デフォルト設定、機能など）をリストアップ。
- 実際の実装コードを確認し、ドキュメントのリストと比較照合。
- 見つかった差異をリスト化し、内容を整理。
- ドキュメントを正とした場合の修正提案を作成し、優先度を付けました。
この分析の結果、いくつかの重要な乖離が見つかりました。
技術的なポイント
ドキュメントと実装を照合した結果、以下のような技術的な差異が明らかになりました。
1. CLI引数の不一致
ドキュメントに記載されている引数名と、実際の実装で使われている引数名が異なっていたり、ドキュメントにある引数が実装されていなかったり、逆にドキュメントにない引数が実装されていたりしました。
| ドキュメント仕様 | 実装状況 | 差異内容 |
|---|---|---|
--input |
input_file |
引数名が異なる |
--template |
実装なし | 実装されていない |
--prompt |
実装なし | 実装されていない |
--llm-provider |
実装済み | 一致 |
--model |
実装なし | 実装されていない |
| 記載なし | --platform |
ドキュメントに記載なし |
| 記載なし | --use-llm |
ドキュメントに記載なし |
| 記載なし | --generate-summary |
ドキュメントに記載なし |
| 記載なし | --summary-length |
ドキュメントに記載なし |
2. APIキー環境変数の不一致
使用するLLMプロバイダーのAPIキーを指定するための環境変数名が、ドキュメントと実装で異なっていました。
| ドキュメント仕様 | 実装状況 | 差異内容 |
|---|---|---|
GOOGLE_API_KEY |
GEMINI_API_KEY |
環境変数名が異なる |
OPENROUTER_API_KEY |
OPENROUTER_API_KEY |
一致 |
3. デフォルト設定の不一致
LLMのデフォルトモデル名が、ドキュメントと実装で異なっていました。
| ドキュメント仕様 | 実装状況 | 差異内容 |
|---|---|---|
デフォルトモデル: gemini-2.0-flash-001
|
gemini-pro |
モデル名が異なる |
| OpenRouterデフォルトモデル: 記載なし | anthropic/claude-3-opus-20240229 |
ドキュメントに記載なし |
4. 機能の不一致
ドキュメントに記載されている機能（テンプレートファイル指定、プロンプトファイル指定）が実装されていなかったり、逆にドキュメントにない機能（プラットフォーム指定、要約生成）が実装されていたりしました。
| ドキュメント仕様 | 実装状況 | 差異内容 |
|---|---|---|
| テンプレートファイル指定 | 実装なし | 実装されていない |
| プロンプトファイル指定 | 実装なし | 実装されていない |
| 記載なし | プラットフォーム指定機能 | ドキュメントに記載なし |
| 記載なし | 要約生成機能 | ドキュメントに記載なし |
5. 依存関係の不一致
使用しているライブラリの依存関係がドキュメントに記載されていませんでした。
| ドキュメント仕様 | 実装状況 | 差異内容 |
|---|---|---|
| 記載なし | google-generativeai>=0.3.0 |
ドキュメントに記載なし |
これらの差異に基づき、ドキュメントを正とした場合の修正提案と優先度をリストアップしました。CLI引数名や環境変数名、デフォルトモデルといった基本的な部分の不一致は高優先度として、早めに修正することにしました。
所感
ドキュメントと実装の間にこれほど多くの乖離があるとは正直驚きでした。開発を進める中で仕様変更や機能追加が頻繁に行われると、どうしてもドキュメントの更新が追いつかなくなりがちです。今回は「ドキュメントを唯一の正とする」という方針を立てたことで、実装側の修正が必要な課題が明確になりました。
この方針は、一見すると実装をドキュメントに合わせる手間が増えるように思えますが、長期的に見ればドキュメントの信頼性が高まり、プロジェクト全体の理解や引き継ぎが格段に楽になるはずです。また、ドキュメントに書かれていない機能が見つかったことで、それが意図した仕様なのか、それとも不要な機能なのかを改めて検討する良い機会にもなりました。
洗い出した差異リストを見ると、やるべきことがたくさんあるなと感じますが、一つずつ着実に修正していきたいと思います。特に高優先度の項目は、ユーザーがドキュメントを見てCLIを使おうとしたときに、そのままでは動かない可能性がある部分なので、早急に対応したいです。
今後の課題
今回洗い出したドキュメントと実装の差異を解消することが喫緊の課題です。高優先度から順に、実装コードを修正していく必要があります。
また、今回はドキュメント整備に焦点を当てましたが、当初の計画にあったテスト体制・品質保証プロセスについても、引き続き検討を進める必要があります。どのようなテスト（単体テスト、結合テストなど）を導入するのか、品質基準をどう定めるのかなどを具体的に詰めていく予定です。
さらに、プロジェクト全体の整理もまだ完了していません。副作用に注意しながら、不要な部分をさらに削減していく作業も並行して進めていきます。
まとめ
本日は、プロジェクトのドキュメントと実装コードの間に存在する乖離を詳細に分析しました。CLI引数、環境変数、デフォルト設定、機能、依存関係など、様々な不一致が見つかりましたが、「ドキュメントを唯一の正とする」という方針のもと、これらの差異を解消するための具体的な修正計画と優先度を立てることができました。
今回の作業を通じて、ドキュメントを最新の状態に保つことの重要性と難しさを改めて認識しました。今後、洗い出した課題に一つずつ取り組み、ドキュメントの信頼性を高め、プロジェクトの品質向上を目指していきます。
Discussion