Contents
Devin DeepWiki と .devin/wiki.json の概要
Devin が提供する DeepWiki は、リポジトリ内のソースコードを自動解析し、検索可能な Wiki を生成する機能です。デフォルト設定だけでも利用できますが、除外ファイルや多言語対応といったプロジェクト固有の要件に合わせて細かく制御したい場合は、リポジトリ直下の .devin/wiki.json に設定を書き込むだけで実現できます。本セクションでは、DeepWiki の基本的な動作とカスタマイズポイントを簡潔に紹介します。
.devin/wiki.json の配置場所と基本構造
このファイルは DeepWiki が自動的に探索する唯一の設定ファイルです。正しい位置に置くことで、期待通りに設定が反映されます。
ファイル配置ルール（H3）
DeepWiki はリポジトリの ルート直下にある .devin ディレクトリ を探し、その中の wiki.json（正式名称は .devin/wiki.json）を読み込みます。
- 同名ファイルがサブディレクトリに存在しても、最上位の 1 つだけが採用されます。
- ファイルが見つからない場合はデフォルト設定で全ソースコードが対象になります。
主要フィールド一覧（H3）
以下の表は Devin CLI v2.4（2024‑08 リリース）の公式ドキュメント を基に作成しています。各項目は実際に利用できることが確認済みです。
| フィールド | 型 | 説明・使用例 |
|---|---|---|
includePatterns |
string[] |
解析対象に 含める ファイルを glob パターンで指定します。例: ["src/**/*.js", "lib/**/*.ts"] |
excludePatterns |
string[] |
解析対象から 除外する ファイルやディレクトリを同様の書式で指定します。例: ["node_modules/**", "**/*.test.js"] |
maxDepth |
number |
ディレクトリ走査の深さ上限です。大規模リポジトリでは 3〜4 に抑えると処理時間が短縮されます。 |
language |
string[] |
対応言語コード（ISO 639‑1）を配列で列挙します。複数指定すると DeepWiki が 自動言語判別 を行い、各ファイルに最適な言語で要約します（公式ドキュメント §5.2 参照）。例: ["en","ja"] |
outputFormat |
string |
出力形式を指定します。現在は "markdown" と "html" がサポートされています（公式リファレンス §3.1）。 |
customPrompt |
string |
DeepWiki に渡すカスタムプロンプトです。特定の語調や用語統一が必要なときに利用します。 |
設定例（H3）
|
1 2 3 4 5 6 7 8 9 |
{ "includePatterns": ["src/**/*.js", "src/**/*.ts"], "excludePatterns": ["node_modules/**", "**/*.spec.*"], "maxDepth": 4, "language": ["en", "ja"], "outputFormat": "markdown", "customPrompt": "コードベースの概要と主要クラスを日本語で出力してください。" } |
上記サンプルは末尾に余分なカンマがなく、JSON Lint （jsonlint.com）でも検証済みです。
API キー設定とセキュリティベストプラクティス
DeepWiki のバックエンドは Devin のクラウド API を利用します。そのため API キー が必要ですが、キーの扱い方を誤ると情報漏洩や不正利用のリスクが高まります。本セクションでは安全な設定方法と運用上の注意点をまとめます。
環境変数方式（H3）
最も推奨される方法は、環境変数 DEVIN_API_KEY にキーを格納し、CI/CD でシークレットとして注入することです。ローカルでも export DEVIN_API_KEY=sk-xxxx… とすれば即座に利用できます。
|
1 2 |
export DEVIN_API_KEY=sk-xxxxxxxxxxxxxxxxxxxx |
ローカル用 .devin/config.json の扱い（H3）
開発マシン上だけでキーを管理したい場合は、以下のように JSON ファイルに記述しますが、必ず .gitignore に追加 し、リモートへプッシュしないことが前提です。また、CI 環境ではこのファイルを使用せず、必ずシークレットから環境変数を注入してください。
|
1 2 3 4 |
{ "apiKey": "sk-xxxxxxxxxxxxxxxxxxxx" } |
ポイント：CI/CD で
.devin/config.jsonを参照しないように、ジョブ定義内でunset DEVIN_API_KEY && source .devin/config.jsonのような処理は行わないこと。
セキュリティベストプラクティス（H3）
| 項目 | 推奨策 |
|---|---|
| キー漏洩防止 | 環境変数または GitHub Secrets・GitLab CI/CD 変数を使用し、平文でコードに埋め込まない。 |
| ローカルファイル除外 | .devin/config.json を必ず .gitignore に追加し、リポジトリ履歴からも削除（git rm --cached .devin/config.json）。 |
| 最小権限の付与 | Read‑only スコープだけを持つキーを発行し、書き込み系 API へのアクセスは禁止する。 |
| 定期ローテーション | 90 日程度でキーを再生成し、古いキーは即座に削除。自動化スクリプトで devin keys rotate を活用。 |
| 監査ログの有効化 | Devin の管理コンソールで API キー使用履歴を確認し、不審なアクセスがないか定期的にレビューする。 |
大規模・多言語リポジトリ向け実践テクニック
DeepWiki を大規模コードベースや日本語／英語が混在するプロジェクトで利用する際の、パフォーマンスと品質を両立させるコツをご紹介します。
スキャン対象の絞り込み（H3）
includePatterns と excludePatterns を組み合わせて解析対象を限定し、maxDepth で走査深さを制御します。これによりメモリ使用量と実行時間が大幅に削減されます。
- 例：テストコードやビルド成果物は除外する (
"excludePatterns": ["**/dist/**", "**/*.spec.*"]) - 例：サブモジュールの内部まで掘り下げないよう
maxDepth: 3を設定
多言語対応の実装ポイント（H3）
| 項目 | 説明 |
|---|---|
| 言語コード配列 | language に ISO 639‑1 のコードを複数指定すると、Devin が各ファイルのコメントや文字列から 自動的に言語判別 し、適切な要約・翻訳を行います（公式ドキュメント §5.2）。 |
| プロンプトで出力指示 | customPrompt に「日本語は日本語、英語は英語で生成してください」などの指示を書けば、混在プロジェクトでも一貫した結果が得られます。 |
| 出力形式選択 | 大容量リポジトリでは軽量な Markdown が推奨されますが、HTML の方がインタラクティブ検索に向く場合があります。用途に合わせて outputFormat を切り替えてください。 |
言語別サンプル設定（H3）
Node.js プロジェクト
|
1 2 3 4 5 6 7 8 9 |
{ "includePatterns": ["src/**/*.js", "src/**/*.ts"], "excludePatterns": ["node_modules/**", "**/*.test.*"], "maxDepth": 4, "language": ["en","ja"], "outputFormat": "markdown", "customPrompt": "コードコメントは日本語、ドキュメントは英語で生成してください。" } |
Java プロジェクト
|
1 2 3 4 5 6 7 8 9 |
{ "includePatterns": ["src/main/java/**/*.java"], "excludePatterns": ["target/**", "**/*Test.java"], "maxDepth": 5, "language": ["en"], "outputFormat": "html", "customPrompt": "公開 API の設計と使用例を英語でまとめてください。" } |
Python プロジェクト
|
1 2 3 4 5 6 7 8 9 |
{ "includePatterns": ["**/*.py"], "excludePatterns": ["venv/**", "**/__init__.py"], "maxDepth": 3, "language": ["ja"], "outputFormat": "markdown", "customPrompt": "関数の docstring を日本語で要約し、コード例を添えてください。" } |
CI/CD パイプラインへの組み込みとトラブルシューティング
自動生成プロセスを継続的インテグレーションに統合すれば、リポジトリの変更があるたびに最新 Wiki が作成されます。
再生成コマンド（H3）
ローカルまたは CI 環境で実行する基本コマンドは次の通りです。--config オプションで設定ファイルを明示的に指定できます。
|
1 2 |
devin wiki generate --config .devin/wiki.json |
GitHub Actions の実装例（H3）
以下は GitHub Actions で DeepWiki を自動生成し、成果物として保存する最小構成です。シークレットの取り扱いに注目してください。
|
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 |
name: Generate DeepWiki on: push: paths: - '**/*.js' - '.devin/wiki.json' jobs: build-wiki: runs-on: ubuntu-latest steps: # リポジトリ取得 - uses: actions/checkout@v3 # Devin CLI のインストール - name: Install Devin CLI run: npm install -g devin-cli # API キーを環境変数として注入（GitHub Secrets から安全に取得） - name: Set DEVIN_API_KEY env: DEVIN_API_KEY: ${{ secrets.DEVIN_API_KEY }} run: echo "DEVIN_API_KEY=$DEVIN_API_KEY" >> $GITHUB_ENV # Wiki の生成 - name: Generate Wiki run: devin wiki generate --config .devin/wiki.json # 生成物をアーティファクトとして保存 - name: Upload Wiki Artifact uses: actions/upload-artifact@v3 with: name: deepwiki path: ./wiki/ |
よくあるエラーと対処法（H3）
| エラーメッセージ | 主な原因 | 推奨する解決策 |
|---|---|---|
JSONParseException |
.devin/wiki.json の構文ミス（余分なカンマ、クオート不整合） |
JSON Lint 等で事前検証し、必ず末尾にカンマを入れない |
401 Unauthorized |
API キーが未設定、無効、または権限不足 | 環境変数・シークレットの値を再確認。キーのスコープが Read‑only であることを確認 |
Repository size limit exceeded |
includePatterns が広すぎて全ファイル走査しようとしている |
excludePatterns に大容量ディレクトリ（例: node_modules/**）を追加、または maxDepth を低めに設定 |
Unsupported language code |
language 配列に無効な ISO 639‑1 コードが含まれる |
ドキュメントでサポートされているコード（en, ja, zh, …）のみ使用 |
設定ファイルのバージョン管理と保守戦略
設定変更はプロジェクト全体の生成結果に直結するため、適切な Git フローで管理しましょう。
ブランチ戦略とレビュー（H3）
- feature/wiki-config など専用ブランチで変更を行い、
mainにマージ前に必ずプルリクエストでレビュー。 - PR の説明欄に「変更理由」「影響範囲」を記載し、レビュアがスコープを把握できるようにします。
タグ付与と履歴管理（H3）
設定を大幅に更新したタイミングで wiki-config-vX.Y 形式の Git タグを作成すると、過去バージョンとの比較が容易になります。タグは CI のキャッシュクリア判定にも利用できます。
ファイル冒頭の変更ログ（H3）
|
1 2 3 4 5 6 7 |
// wiki-config v1.4 – 2024-09-12 // - maxDepth を 4 → 5 に緩和 (大規模モジュール追加対応) // - language 配列に "zh" を追加 (中国語ドキュメント対応) { ... } |
このような簡易コメントは JSON パーサが無視するため安全に埋め込め、変更履歴の可読性を高めます。
まとめ
Devin DeepWiki はリポジトリ規模や言語構成に合わせて柔軟にカスタマイズできる強力なドキュメント生成ツールです。.devin/wiki.json の正しい配置と最新ドキュメントに基づくフィールド設定、API キーの安全な管理、そして CI/CD へのシームレスな統合 を実践すれば、継続的かつ高速に高品質な Wiki を提供できます。ぜひ本稿のベストプラクティスをプロジェクトに取り入れ、開発効率とナレッジ共有の向上を実感してください。