よくある質問
このページで は、annai（ソースコードからユーザー向けマニュアルを自動生成するツール）についてよく寄せられる質問と回答をまとめています。
このページで疑問が解決しない場合は、トラブルシューティングページで具体的なエラーメッセージごとの対処方法を確認します。
初期設定について
annai を使い始めるには何が必要ですか？
Node.js（JavaScript の実行環境）18 以上、annai 本体、Claude CLI（Claude（AI アシスタント）のコマンドラインツール）の3つが必要です。 詳しくは初期設定をするを参照します。
annai.config.json を誤って削除してしまった場合はどうすればよいですか？
annai init を実行すると、初期設定の annai.config.json が再生成されます。
以前カスタマイズしていた内容は失われるため、再度設定を行います。
設定項目の詳細は設定をカスタマイズするを参照します。
マニュアル生成について
マニュアルの生成にはどのくらい時間がかかりますか？
プロジェクトの規模によって異なります。 ソースコードの行数が少ないほど短時間で完了します。
生成されるページの種類を選べますか？
生成されるページの種類は固定です。 イントロ、クイックスタート、はじめに（カテゴリ）、使い方（カテゴリ）、トラブルシューティング、よくある質問、更新履歴の構成で生成されます。
生成されたマニュアルを手動で編集できますか？
出力先フォルダ（初期設定では ./user-manual/docs/）内の MDX ファイルをテキストエディタで自由に編集できます。
ただし、次に一括生成を実行すると上書きされます。
手動の編集を保持したい場合は、差分更新モードを使います。
詳しくはマニュアルを差分更新するを参照します。
日本語以外のマニュアルを生成できますか？
現在は日本語のみに対応しています。
解析対象のプログラミング言語を変更できますか？
annai.config.json の sourceExtensions で、解析対象のファイル拡張子を指定できます。
初期設定では TypeScript、JavaScript、Python、Go、Swift、Kotlin、Java、Dart、Rust、Ruby、C#、C++、C、PHP のファイルが対象です。
詳しくは設定をカスタマイズするを参照します。
差分更新について
一括生成と差分更新はどう使い分ければよいですか？
初回は一括生成（annai gen）を使います。
2回目以降のソースコード変更時は、差分更新（annai gen --mode incremental）を使うと、変更に関連するページだけが再生成されるため効率的です。
詳しくはマニュアルを差分更新するを参照します。
差分更新で変更が検出されない場合はどうすればよいですか？
ソースコードの変更が Git（ソースコードの変更履歴を管理するツール）にコミット（変更の記録）されているか確認します。 差分更新は Git のコミット履歴をもとに変更を検出するため、コミットされていない変更は検出されません。
公開について
Cloudflare Pages（Web サイトのホスティングサービス）以外のサービスで公開できますか？
annai の deploy コマンドは Cloudflare Pages 専用です。
ただし、生成されたマニュアルは標準的な Docusaurus（マニュアルサイトの構築 ツール）プロジェクトのため、user-manual フォルダ内で npx docusaurus build を実行してビルドした結果を、任意のホスティングサービスにアップロードできます。
公開したマニュアルにパスワードを設定できますか？
annai 自体にはパスワード保護の機能はありません。 公開先のホスティングサービス側でアクセス制限を設定します。
品質チェックについて
品質チェックを省略できますか？
annai gen --no-quality-gate を実行すると、品質チェックを省略してマニュアルを生成できます。
詳しくはマニュアルの品質を確認するを参照します。
品質チェックの合格基準を変更できますか？
合格基準は82点（100点満点）に固定されています。 変更はできません。
更新履歴について
すべてのコミットが更新履歴に掲載されますか？
掲載されるのは feat:（新機能）、fix:（修正）、perf:（改善）で始まるコミットメッセージのみです。
refactor:、chore:、docs:、test: で始まるコミットは、ユーザーに直接関係しないため掲載されません。
詳しくは更新履歴を自動生成するを参照します。
CI/CD（継続的インテグレーション・継続的デリバリー）について
GitHub（ソースコードの共有・管理サービス）以外のサービスで自動化できますか？
annai が自動生成するワークフローファイルは GitHub Actions（GitHub が提供する自動処理の仕組み）専用です。
GitLab CI や CircleCI で使う場合は、annai gen --mode incremental と annai deploy を実行するステップを各サービスの設定ファイルに手動で記述します。
CI/CD の実行にはどのような認証情報が必要ですか？
Cloudflare の API トークン（外部サービスとデータをやり取りするための認証キー）とアカウント ID の2つが必要です。 GitHub のリポジトリにシークレット（外部に公開されない秘密の設定値）として登録します。 詳しくはCI/CD で自動生成・デプロイを設定するを参照します。
エラーについて
生成中にエラーが発生した場合、最初からやり直す必要がありますか？
やり直す必要はありません。
annai gen --mode incremental を実行すると、中断箇所から処理を再開できます。
詳しくはエラーから復旧するを参照します。
「annai.config.json のパースに失敗しました」と表示された場合はどうすればよいですか？
annai.config.json の書式に誤りがあります。
カンマの過不足、ダブルクォーテーションの閉じ忘れ、中括弧や角括弧の対応を確認します。
修正が難しい場合は、annai.config.json を削除して annai init で再生成し、改めて設定を行います。