## 概要

zudo-docはプロジェクトのClaude Codeリソース — CLAUDE.mdファイル、カスタムコマンド、スキル、エージェント — からドキュメントページを自動的に生成できます。有効にすると、これらは**Claude**ヘッダーナビゲーションセクションに表示されます。

## Claude Resourcesの有効化

`zfb.config.ts`で`claudeResources`を設定します：

```ts title="zfb.config.ts"
export default defineConfig(
  zudoDoc({
    claudeResources: {
      claudeDir: ".claude",
    },
  }),
);
```

無効にするには`false`に設定します：

```ts
claudeResources: false,
```

## 生成されるもの

インテグレーションは`.claude/`ディレクトリをスキャンし、以下のMDXドキュメントページを生成します：

| リソース | ソース | 出力 |
|----------|--------|--------|
| CLAUDE.mdファイル | プロジェクトルートとサブディレクトリ | `claude-md/` |
| コマンド | `.claude/commands/*.md` | `claude-commands/` |
| スキル | `.claude/skills/*/SKILL.md` | `claude-skills/` |
| エージェント | `.claude/agents/*.md` | `claude-agents/` |

各リソースタイプには、すべてのアイテムのリストを含むインデックスページと個別の詳細ページが用意されます。

## 仕組み

インテグレーションはzfbプラグイン（`@takazudo/zudo-doc/plugins/claude-resources`）として、ビルド時に動作します。このプラグインは`claudeResources`が設定されていれば`zudoDoc()`が自動的に組み込みます。`preBuild`フックで以下を行います：

1. 設定された`.claude/`ディレクトリをスキャン
2. CLAUDE.mdファイル、コマンド、スキル（リファレンス付き）、エージェントを検出
3. `src/content/docs/claude-*/`ディレクトリにMDXファイルを生成
4. これらのファイルはzfbのコンテンツコレクションによって取得され、ドキュメントページとしてレンダリング

生成されたページは**Claude**ヘッダーナビゲーションタブに表示されます。`headerNav`で`categoryMatch: "claude"`を設定して構成します。

[Dynamic content unavailable in text export]

生成されたファイルは`src/content/docs/`に書き込まれ、ビルドごとに再作成されます。手動で編集しないでください — 変更は上書きされます。



## ロケールごとの挙動

概要ページとカテゴリインデックスは、設定済みの各ロケールに生成されます。タイトル、説明、ラベルには`resource.*`のUI文字列が使われます。個別リソース本文の正本となるソースダンプはデフォルトのコンテンツディレクトリに置かれます。本文の言語は元のソースファイルに従うため、必ずしも英語ではありません。ロケール付きルートでは未翻訳バナーを出さず、ローカライズされたナビゲーションとクロームの中にその本文を表示します。言語切り替えには設定済みの全ロケールへのリンクが残ります。

パッケージが同梱する`resource.*`文字列は英語と日本語です。他の対応ロケールコードは、通常どおり要求ロケール → 設定済みデフォルト → 英語 → リテラルの順でフォールバックします。ラベルは`ZudoDocConfig.translations`で上書きできます。保存方針の理由、`llms.txt`と検索の挙動、`defaultLocaleOnlyPrefixes`によるオプトアウトは[国際化](https://zudo-doc.takazudomodular.com/ja/docs/guides/i18n#%E7%94%9F%E6%88%90%E3%83%9A%E3%83%BC%E3%82%B8%E3%81%A8%E3%83%87%E3%83%95%E3%82%A9%E3%83%AB%E3%83%88%E3%83%AD%E3%82%B1%E3%83%BC%E3%83%AB%E3%81%AE%E6%9C%AC%E6%96%87)を参照してください。

このオプトアウトを使う場合は、セクション全体をまとめて制限してください。`/docs/claude-md/`、`/docs/claude-skills/`、`/docs/claude-agents/`、`/docs/claude-commands/`に加えて、概要プレフィックス`/docs/claude/`も列挙する必要があります。概要プレフィックスがないと、ロケール所有の概要インデックスは設定済みの全ロケールに生成されます。そのロケール側に手書きの`claude/index.mdx`（frontmatterに`generated: true`がないもの）が既にある場合、ビルドは`resource-docs: refusing to overwrite authored locale index`で失敗します。詳しくは[リソースセクションには概要プレフィックスも含まれる](https://zudo-doc.takazudomodular.com/ja/docs/guides/i18n#%E3%83%87%E3%83%95%E3%82%A9%E3%83%AB%E3%83%88%E3%83%AD%E3%82%B1%E3%83%BC%E3%83%AB%E5%B0%82%E7%94%A8%E3%83%97%E3%83%AC%E3%83%95%E3%82%A3%E3%83%83%E3%82%AF%E3%82%B9-%E3%83%AA%E3%82%BD%E3%83%BC%E3%82%B9%E3%82%BB%E3%82%AF%E3%82%B7%E3%83%A7%E3%83%B3%E3%81%AB%E3%81%AF%E6%A6%82%E8%A6%81%E3%83%97%E3%83%AC%E3%83%95%E3%82%A3%E3%83%83%E3%82%AF%E3%82%B9%E3%82%82%E5%90%AB%E3%81%BE%E3%82%8C%E3%82%8B)を参照してください。

## 設定オプション

| オプション | 型 | 説明 |
|--------|------|-------------|
| `claudeDir` | string | `.claude/`ディレクトリへのパス（プロジェクトルートからの相対パス） |
| `projectRoot` | string | CLAUDE.mdファイルパスの解決に使用するオプションのプロジェクトルートオーバーライド |
| `scanRoot` | string | CLAUDE.mdの探索に使用する省略可能なリポジトリ全体のルート。デフォルトは`projectRoot` |

`projectRoot`オプションは、`.claude/`ディレクトリがプロジェクトルートにないモノレポ設定で便利です。

[Dynamic content unavailable in text export]

`references/`サブディレクトリを持つスキルは、そのリファレンスドキュメントが個別のリンクされたページとして含まれるため、バンドルされたナレッジベースを簡単に閲覧できます。



## ミラー内のリポジトリ相対リンク

ミラーされたリソース本文では、リポジトリ内の相対パスを指すMarkdownリンクと画像をインラインコードに変換します。リンク先をドキュメントのURLとして扱うと壊れるためです。リンクのラベルまたは画像の代替テキストを表示します。Claude側の`CLAUDE.md`・コマンド・エージェント、Codex側の`AGENTS.md`、および両方のスキル本文とサブページに適用されます。

スキルのメイン本文にある`references/`・`scripts/`・`assets/`へのリンクは、対応するサブページが実際に生成される場合に限り、そのページへのリンクとして維持されます。存在しない対象や生成対象外のファイル（`.sh`スクリプトなど）はインラインコードになります。サブページ本文のリポジトリ相対リンクもインラインコードになります。生成ページへのリンクを維持する例外は、スキルのメイン本文に適用されます。

外部URL、ルート相対URL、ページ内フラグメントは維持されます。インラインコードやコードフェンス内のリンク例は変換しません。通常の手書きMDXでは、引き続き[ドキュメント間リンク](https://zudo-doc.takazudomodular.com/ja/docs/getting-started/writing-docs)の規則に従ってください。