#headless-mode (1)

wikigenはGo製CLIで、Claude Codeを呼び出してコードベースから仕様wikiを自動生成する。embeddings/Docker/Ollama不要。Astro+Svelte+Firebaseの中規模プロダクトで検証した結果、想像を超えるクオリティだった。

本質は「Claude Codeをワーカーとして外部から叩くパターン」

これが一番の学び。wikigenはClaude Codeスキルのようなものではなく、外部プログラムがclaude CLIを子プロセスとして並列に起動する設計。スキルとは別物。

観点	スキル	wikigen方式
実行場所	現在の会話内（同一context）	外部プロセスが独立context起動
並列	不可	-pp Nで並列worker
Context消費	現在のcontextを食う	各subprocess独立
運用	人が対話	GH Actionsで無人実行可能

いわゆる Claude Code headless mode / Claude Code as SDK のパターン。claude -p <prompt> で対話UIを起動せずプロンプト投入だけできるので、それを外部オーケストレーターから叩くと「バッチ処理」「CI統合」「Slack Bot裏側」等に応用できる。会話UIとしてのClaude Codeと、プログラムから叩くワーカーとしてのClaude Codeは別の顔、という発想転換が大事。

実行のコツ

• -localフラグは不要: 位置引数に直接ローカルパスを渡せばclone不要 → ./wikigen /path/to/repo
• privateリポでもローカルクローンさえあれば動く
• 認証はclaude CLIの対話ログイン状態を子プロセス継承で引き継ぐ。CLAUDE_CODE_OAUTH_TOKENを明示設定しなくても動作した（READMEに記載なし）
• 単一ページだけ生成したい場合は-retryを悪用: 1ページだけ空ファイル（<200B）を置いてretry実行 → そのページだけ生成される

クオリティ検証結果

24ページ構成のwikiを2分24秒で設計。1ページ本生成は約3分で16,301文字。スポットチェックで確認した範囲では:

• ソース引用が行番号まで全て正確（ハルシネーションなし）
• sequenceDiagramとflowchartのmermaid図を自動生成
• コメントと実装の乖離のような人間のレビュアーでも見落としがちな細部まで指摘
• 「設計上の特徴」セクションを自力で作成する抽象化力

記事が触れていない注意点

• 「追加課金なし」はClaude Pro/Max契約者のOAuthトークン方式のみ。ANTHROPIC_API_KEY利用時は従量課金
• --bareモードではOAuthトークン無効
• OAuthトークンは1年有効
• 便利な未記載フラグ: -dry-run, -model(haiku/sonnet/opus), -json

向き/不向き

向き: コード主体のリポの叩き台仕様wiki、新人オンボーディング初稿、設計ドキュメントの老朽化対策（GH Actionsで定期再生成）

不向き: Markdownコンテンツ主体のドキュメントリポ、ビジネス要件・設計意図の「Why」の記述（wikigenはコード根拠に限定される）