トラブルシューティング
このページでは、annai（ソースコードからユーザー向けマニュアルを自動生成するツール）の利用中に発生しやすい問題と、その解決方法をまとめています。
問題が発生した場合は、まずこのページで該当する症状を探します。該当する項目が見つからない場合は、ページ末尾の「上記で解決しない場合」を参照します。
「Claude CLI（コマンドラインツール）が見つかりません」と表示される
症状
annai gen を実行すると、「Claude CLI が見つかりません」というメッセージが表示され、マニュアル生成が開始されません。
原因
annai がマニュアル生成に使用する Claude CLI がインストールされていないか、認証が完了していません。
解決手順
- Claude CLI をダウンロードしてインストールします
- ターミナル（コマンドを入力する画面）で
claude login（認証コマンド）を実行します - 画面の案内に従って認証を完了します
annai genを再度実行します
「認証が切れています」と表示される
症状
マニュアル生成の途中で「認証が切れています」というメッセージが表示され、処理が中断されます。
原因
Claude CLI の認証トークン（認証済みであることを証明する情報）の有効期限が切れています。
解決手順
- ターミナルで
claude loginを実行します - 画面の案内に従って再認証を完了します
annai gen --mode incrementalを実行します
差分更新モードで再開するため、中断前に生成済みのページは再利用されます。 最初からやり直す必要はありません。
「レートリミットに達しました」と表示される
症状
マニュアル生成の途中で「レートリミットに達しました」というメッセージが表示され、処理が中断されます。
原因
一定時間内のリクエスト回数の上限に達しています。 annai は自動で最大3回までリトライしますが、それでも解消しない場合にこのメッセージが表示されます。
解決手順
- 数分間待ちます
annai gen --mode incrementalを実行します
差分更新モードで再開するため、中断箇所から処理が再開されます。
「ソースパスが見つかりません」と表示される
症状
annai gen を実行すると、「ソースパスが見つかりません」というメッセージが表示されます。
原因
annai.config.json の sourcePath に指定されたフォルダが存在しません。
解決手順
- annai.config.json をテキストエディタで開きます
sourcePathの値を確認します- 指定されたフォルダが実際に存在するか確認します
- 存在しない場合は、ソースコードがあるフォルダのパスに修正します
- ファイルを保存して
annai genを再度実行します
設定の詳細は設定をカスタマイズするを参照します。
「cloudflare.projectName が設定されていません」と表示される
症状
annai deploy を実行すると、「cloudflare.projectName が設定されていません」というメッセージが表示されます。
原因
annai.config.json の cloudflare.projectName が空のままです。
解決手順
- annai.config.json をテキストエディタで開きます
cloudflareセクションのprojectNameにプロジェクト名を入力します- ファイルを保存します
annai deployを再度実行します
設定例は以下の通りです。
{
"cloudflare": {
"projectName": "my-app-manual"
}
}
「./user-manual/ が存在しません」と表示される
症状
annai deploy を実行すると、「./user-manual/ が存在しません」というメッセージが表示されます。
原因
マニュアルがまだ生成されていません。
annai deploy は生成済みのマニュアルを公開するコマンドのため、事前にマニュアルの生成が必要です。
解決手順
annai genを実行してマニュアルを生成します- 生成が完了したら
annai deployを再度実行します
詳しくはマニュアルを一括生成するを参照します。
マニュアルのビルドに失敗する
症状
annai deploy の実行中に「Docusaurus（マニュアルサイトの構築ツール）のビルドに失敗しました」というメッセージが表示されます。
原因
生成されたマニュアルファイルの内容に問題があるか、Docusaurus の依存パッケージが破損しています。
解決手順
user-manualフォルダに移動しますnode_modulesフォルダを削除しますnpm installを実行して依存パッケージを再インストールしますnpx docusaurus buildを実行してエラーの詳細を確認します- エラー内容に応じて、該当する MDX ファイルを修正します
- プロジェクトのルートフォルダに戻り、
annai deployを再度実行します
Cloudflare Pages（Web サイトのホスティングサービス）へのデプロイに失敗する
症状
annai deploy の実行中に「Cloudflare Pages へのデプロイに失敗しました」というメッセージが表示されます。
原因
Cloudflare の認証が切れているか、プロジェクト名が annai.config.json の設定値と一致しません。
解決手順
npx wrangler loginを実行して Cloudflare の認証を行います- annai.config.json の
cloudflare.projectNameが Cloudflare 側のプロジェクト名と一致しているか確認します - Cloudflare のダッシュボード（管理画面）で該当のプロジェクトが存在するか確認します
annai deployを再度実行します
詳しくはマニュアルを公開するを参照します。
品質スコアが低いページがある
症状
マニュア ル生成後の品質レポートで、一部のページに「警告」が表示されます。
原因
生成されたページが品質基準（82点）を満たしていません。 annai は自動で最大2回まで再生成を試みますが、それでも基準に達しない場合に警告が表示されます。
解決手順
- 品質レポートで減点された観点を確認します
- 該当するページをテキストエディタで開きます
- 減点の観点に応じて内容を修正します
- 修正が完了したら保存します
各観点の修正方法はマニュアルの品質を確認するを参照します。
差分更新で「変更ファイルがありません」と表示される
症状
ソースコードを変更したのに、annai gen --mode incremental を実行すると「変更ファイルがありません。更新は不要です」と 表示されます。
原因
変更がまだ Git（ソースコードの変更履歴を管理するツール）にコミット（変更の記録）されていません。 差分更新は、Git のコミット履歴をもとに変更ファイルを検出します。
解決手順
git addで変更ファイルをステージング（記録の準備）しますgit commitで変更をコミットしますannai gen --mode incrementalを再度実行します
更新履歴が空になる
症状
生成されたマニュアルの更新履歴ページに「更新履歴はまだありません。」とだけ表示されます。
原因
更新履歴の対象となるコミットが存在しません。
annai は feat:、fix:、perf: で始まるコミットメッセージのみを更新履歴に含めます。
解決手順
- Git のコミット履歴を確認します
- コミットメッセージの先頭に
feat:、fix:、perf:のいずれかが付いているか確認します - 対象のコミットがない場合は、次の変更時にこれらの形式でコミットメッセージを記述します
詳しくは更新履歴を自動生成するを参照します。
上記で解決しない場合
以下の方法を試します。
annai gen --verboseを実行して、処理の詳細をターミナルに出力します。出力内容をもとに、問題箇所を特定しますannai gen --dry-runでファイル書き出しなしの事前確認を行い、どの段階で問題が発生するか切り分けます- annai.config.json を削除し、
annai initで設定ファイルを再生成してからやり直します