## 概要

zudo-docは、プロジェクト内のCodexリソースからドキュメントページを自動生成できます。対象となるのは、`AGENTS.md`ファイル、設定プロファイル、カスタムエージェント、フック、ルール、スキルです。有効にすると、生成されたページはヘッダーナビゲーションの**Codex**セクションに表示されます。

## Codexリソースの有効化

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

```ts title="zfb.config.ts"
export default defineConfig(
  zudoDoc({
    codexResources: {
      codexDir: ".codex",
    },
  }),
);
```

インテグレーションを無効にするには`false`を設定します：

```ts
codexResources: false,
```

## 生成されるもの

インテグレーションは以下のドキュメントセクションを生成します：

| 生成先ディレクトリ | 内容 | ソース |
|---------------------|------|--------|
| `codex/`（位置904） | カテゴリカードを備えた概要ページ | — |
| `codex-agents-md/`（位置905） | すべての`AGENTS.md`と`AGENTS.override.md` | `scanRoot`から探索 |
| `codex-config/`（位置906） | `config.toml`、`*.config.toml`プロファイル、`config.toml.example` | `.codex/` |
| `codex-agents/`（位置907） | カスタムサブエージェント | `.codex/agents/*.toml` |
| `codex-hooks/`（位置908） | ライフサイクルフックとフックスクリプト | `.codex/hooks.json`と`.codex/hooks/` |
| `codex-rules/`（位置909） | コマンド承認ルール | `.codex/rules/*.rules` |
| `codex-skills/`（位置910） | スキルパッケージ | `.codex/skills/`と、プロジェクトルートおよびスキャンルートの`.agents/skills/` |

リソースごとにインデックスページが作られ、検出された各リソースは個別の詳細ページとして表示されます。

## 仕組み

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

1. `projectRoot`、`scanRoot`、設定された`.codex/`ディレクトリを解決
2. `scanRoot`を探索して`AGENTS.md`と`AGENTS.override.md`を検出
3. 設定された各リソースの場所から、設定、エージェント、フック、ルール、スキルを検出
4. 7つの`codex*`ディレクトリにインデックスページと詳細ページのMDXを生成
5. 生成したページをzfbのコンテンツコレクションから利用できる状態にする

生成されたページは、ヘッダーナビゲーションの**Codex**タブに表示されます。すべてのCodex生成セクションでタブをアクティブにするには、`categoryMatch: "codex"`を設定します。

ヘッダーアイテムには`versioned: false`を設定してください。生成されたCodexコンテンツは`/v/{version}`配下には書き込まれないため、バージョン対応のリンクにすると、過去バージョンの表示中に存在しないルートを指してしまいます。

## ロケールごとの挙動

概要ページとカテゴリインデックスは、設定済みの各ロケールに生成されます。タイトル、説明、ラベルには`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)を参照してください。

## 設定オプション

| オプション | 型 | 説明 |
|------------|----|------|
| `codexDir` | string | `.codex/`ディレクトリへのパス。`projectRoot`を基準に解決 |
| `projectRoot` | string | 省略可能なプロジェクトルートの上書き。`codexDir`と生成先の`docsDir`はこのルートを基準に解決 |
| `scanRoot` | string | 省略可能なリポジトリ全体の探索ルート。デフォルトは`projectRoot`で、`AGENTS.md` / `AGENTS.override.md`の探索と、リポジトリレベルの`.agents/skills/`ルートの両方に適用 |

[Dynamic content unavailable in text export]

スキルは`<codexDir>/skills/`、`<projectRoot>/.agents/skills/`、`<scanRoot>/.agents/skills/`の優先順で検出されます。同じ実体パスを指すルートは重複排除されます。異なるディレクトリに同名のスキルがある場合は、先に検出したルートが優先され、プラグインが警告を記録します。Codex自体は、異なるスコープに同名のスキルがある構成も許容します。



[Dynamic content unavailable in text export]

Claude CodeとCodexで同じスキルを一元管理するには、ソースを1か所に置き、そのスキルディレクトリを`.claude/skills/`と`.codex/skills/`の両方からシンボリックリンクします。



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

ミラーされたリソース本文では、リポジトリ内の相対パスを指す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)の規則に従ってください。