文書構造を維持する
ページを追加してもカテゴリ構成を崩さないために。配置確認だけで足りる場面、構造を見直す場面、人とAIエージェントが一つの編集方針を共有する方法。
文書群は、それぞれはもっともな一ページの追加を重ねるうちに少しずつ崩れていきます。このガイドは、zudo-docサイトに内容を追加するときにカテゴリとページ間の関係を保つための手順を、人とAIエージェントで共有できる形で示します。対象はzudo-doc自身ではなく、zudo-docをインストールして使うプロジェクトです。
手順には二つの段階があります。通常の追加では、短い配置確認をして配置理由を一行で記すだけです。構造レビューは、現在のカテゴリが読者の必要に合わなくなっている根拠があるときにだけ始めます。構造をそのまま維持することも、レビューの正式な成功結果です。何もしなかったという失敗ではありません。
三つの層と管理者
| 層 | 置き場所 | 変更する人 |
|---|---|---|
| 共通ガイド | このページ(zudo-docのドキュメントとして提供) | zudo-docの開発者 |
| プロジェクトの編集方針 | プロジェクト内の一ファイル。新規scaffoldでは AUTHORING.md、既存プロジェクトでは指定した既存ファイル | プロジェクトの管理者 |
| 指示ファイルとスキル | README.md、CLAUDE.md、AGENTS.md、任意のスキル | プロジェクト。いずれも編集方針を参照する |
カテゴリについての正本はプロジェクトの編集方針だけです。README.md、CLAUDE.md、AGENTS.md、各スキルはそこを指すだけにします。カテゴリの詳しい規則を複数のファイルにコピーしないでください。コピーは食い違い、古いコピーを読んだエージェントは誤った境界を自信を持って適用します。
配置確認が必要な変更
誤字、表現、書式だけの修正は通常の執筆ルールで進めます。配置確認も構造レビューも不要です。
ページを追加するとき、ページに新しい読者タスクや論点を加えるとき、ページの役割を変えるときは、次の四問に答えます。
誰が何をできるようにする内容か。 「サイト管理者がロケールを追加できる」のように読者とタスクを書きます。
同じ役割の既存ページはあるか。 まずタイトル、description、カテゴリの一覧を検索します。
なぜこのカテゴリか。競合する行き先はあるか。 判断の根拠になる編集方針上の境界を挙げます。
今回の追加でカテゴリの意味が変わるか。 たとえばリファレンスのカテゴリにチュートリアルが集まり始める場合です。
答えが明確なら、内容を配置して理由を一行で報告します。例:「サイト管理者向けのタスクガイドとして guides/ に配置。ロケール設定を扱う既存ページはない」。ほとんどの追加はこれで完了です。
構造レビューを始める条件
四問の結果、次のいずれかの根拠が出たときにだけ構造レビューを始めます。
カテゴリとの衝突 — 編集方針に書かれた境界では、内容が二つのカテゴリに同程度に当てはまる、またはどこにも当てはまらない。
内容の重複 — 同じ読者タスクを扱う既存ページがある。
独立したまとまりの出現 — カテゴリの定義が想定していない別の読者タスクを扱うページが複数できた。
探しにくさ — 読者が目的の内容を見つけられない、または違うページにたどり着くという具体的な報告や観察がある。
読む範囲は段階的に広げます。まずカテゴリ地図(サイドバーのツリーまたはディレクトリ一覧)と編集方針を確認し、次に関連するページ、競合するページ、例外として記録されたページの本文を読みます。毎回すべての本文を読む必要も、長い監査報告を書く必要もありません。一部しか調べていない場合はその範囲を明記し、部分的な調査を全体監査として報告しないでください。
案を比較する
まず具体的な読者上の問題を一、二文で書きます。そのうえで、問題を解消できる案を比較します。
| 案 | 向いている場面 |
|---|---|
| 既存ページへの追記 | 新しい内容がそのページと同じ読者タスクを扱う |
| 構造を維持したままの改善 | タイトルの明確化、カテゴリindexの導入文、編集方針への境界の注記で問題が解消する |
| 局所的な再編 | 別の読者タスクに独自の置き場所が必要なため、ページを分割・統合する、または一つのカテゴリを改称・分割・統合する |
| 関連リンク、索引、別の入口 | 横断的な内容。主所属を一つにし、読者が探す他の場所からリンクする |
読者上の問題を実際に解消できる案に絞り、そのあとで各案の変更量を比較します。「変更するファイルが少ない」は同点のときの決め手であって、必要な再編を避ける理由にはなりません。逆に、構造を保つ案で問題が解消するなら再編はしません。
ページ数、カテゴリの均等さ、根拠を示せない総合点で決めないでください。プロジェクトの編集方針が採用していないなら、Diátaxisの四分類や主題別分類を当てはめないでください。そのプロジェクトが定義したカテゴリを使います。
管理者に質問するのは、重要な編集目的が競合し、編集方針からは解消できないときだけです。たとえば公開済みURLの維持と、ページを正しいカテゴリへ移すことが両立しない場合です。具体的な選択肢とそれぞれの影響を示してください。通常の配置や、編集方針がすでに許している変更では確認を求めません。
カテゴリの意味を記録する
編集方針には、後の執筆者が同じ判断をするために必要なことだけを記録します。
各カテゴリに含む内容、含まない内容、隣接カテゴリとの違い
重要な例外。たとえばURLを保つために古いカテゴリに残しているページ
実際に行った再編の理由
それぞれの記述の出所を明記します。decision(決定)はプロジェクトの管理者が決めたこと、fact(事実)は既存の文書や設定に書かれていること、hypothesis(仮説)は執筆者やAIエージェントが推測し、まだ誰も確認していないことです。編集方針の未記入欄は推測で埋めず未確定として扱い、確認されていない仮説を恒久的な規則にしないでください。
通常の配置は記録しません。新しい根拠がないまま同じカテゴリを再編し直さないでください。同じ入力を再評価したら同じ結論になるべきです。
zudo-docで確認する制約
ファイルシステムによるナビゲーションが基本です。 ディレクトリがカテゴリになり、その
index.mdxがランディングページになります。望む階層がディレクトリと異なるときは、通常はファイルの移動が第一選択です(ナビゲーションの構成方法)。論理的な分類変更とファイルの移動は別物です。 ファイルを移動するとURLが変わります。両者を分けて判断してください。
維持すべきURL があるページは、editorialツリーまたはumbrellaツリーで親を付け替えられます。これらが変えるのは対になったヘッダーとサイドバーだけです。パンくずリスト、前後ページのリンク、検索、サイトマップ、
<CategoryNav>はURLのツリーに従い続けるため、サイドバーを変えただけではそれらは一致しません。categoryMatchはトップレベルのディレクトリ一つ で、リンク付きの親行は実在するカテゴリノードのままにします。ヘッダーナビゲーションとサイドバーを参照してください。note-trayは平らなまま保ちます。 note-trayは日誌や講座のような連なりです。項目が多いことはトピックツリーへ変換する理由になりません。連なりでは提供できないトピック別のアクセスを読者が必要とするときだけ変換します。
ロケールのルートは設定から読みます。
zfb.config.tsのdocsDirと各locales.<code>.dirを読みます。docs-v1/のようなバージョンのスナップショットはロケールではないので、現在の内容と一緒に再編しないでください(国際化、バージョニング)。ジェネレーターが所有する内容 には
generated: trueが付いているか、ドキュメントソースのようなジェネレーターが書き出しています。生成されたファイルではなく、その元データや設定を再編します。defaultLocaleOnlyPrefixesには、意図的にロケールのミラーを持たないパスを列挙します(デフォルトロケール専用プレフィックス)。draftとunlistedのページも重複を探すときは対象に含めます。draftはビルドから除外され、unlistedはビルドされますがナビゲーションには表示されません(フロントマター)。
例
各例は入力、判断の理由、短い結論を示します。結論は判断の仕方の例であり、唯一の正しいツリーではありません。
| 入力 | 理由 | 結論 |
|---|---|---|
すでに三つのデプロイ先ページがある deploy/ カテゴリに、四つ目のデプロイ先ページを追加 | 同じ読者タスク(ホストへのデプロイ)で、編集方針の境界がすでに含んでいる | 構造を維持し、一行の理由を添えてページを追加 |
エンドユーザー向けの手順として定義された guides/ に、サイトのAPI向けプラグイン作成のページが五つ増えた | 別の読者(プラグイン作者)と別のタスク。プラグインのページが見つからないという報告がある | 構造レビュー。新しい plugins/ カテゴリ、入れ子の guides/plugins/ カテゴリ、索引ページを比較し、読者上の問題で絞ってから変更量で選ぶ |
reference/ も十二ページになったが、すべて同じ種類のAPIリファレンス項目 | 件数は上と同じだが内容は同質で、読者上の問題もない | 構造を維持。件数だけでは分割の理由にならない |
guides/ があるのに「検索の設定方法」を書いてほしいという依頼 | 既存ページと同じ読者タスク | 既存ページを更新し、新規ページは作らない |
| セットアップとAPIの利用の両方に関わる認証のページ | 横断的な内容 | 主所属を一つ(たとえば guides/)にし、APIのページから関連リンクを張る。本文は複製しない |
notes/ のnote-trayが日付付きで120項目になった | note-trayは順に読むためのもので、トピック別に探せないという報告もない | note-trayを維持。トピック別のアクセスが実際に必要になったら、タグやトピック索引ページを検討する |
| ページを別カテゴリへ移すべきだが、そのURLは外部サイトからリンクされている | 正しいカテゴリと公開URLの対立 | ファイルはそのままにし、必要ならeditorialツリーで親を付け替え、例外を編集方針に記録する。生成ファイル、ロケールのミラー、バージョンのスナップショットを個別に動かさない |
| ページタイトルの誤字修正 | 表現のみ | 配置確認もレビューも不要 |
| 一週間後に、新しいページも報告もないまま同じレビューの依頼 | 新しい根拠がない | 前回の判断を維持し、変化がないことを伝える |
新規プロジェクトへの導入
create-zudo-docで作成したプロジェクトのルートには次のファイルがあります。
| ファイル | 役割 |
|---|---|
AUTHORING.md | 編集方針のひな形。記入していく。未記入の欄は未確定 |
README.md | 人向けの短い「Adding or reorganizing docs」節 |
CLAUDE.md | Claude Code向けの「Documentation structure」節 |
AGENTS.md | Codexなど AGENTS.md を読むエージェント向けの同じ参照 |
三つの入口はどれも同じ AUTHORING.md を指し、四問と最小手順もそこに書かれているので、基本の手順はオフラインでも、任意機能をすべて無効にしても使えます。claudeSkillsWriting 機能を有効にすると、zudo-doc-writing スキルが詳しいナビゲーション規則を加え、同じ編集方針を読みます。skillSymlinker 機能を有効にすると、生成されるドキュメントスキルのupdateモードも書き込む前に編集方針を読みます(ドキュメントスキルシンボリックリンカー)。Codexリソース機能やClaudeリソース機能が有効な場合、AGENTS.md と CLAUDE.md の内容はリソースページとしてサイトにも掲載されます。
AUTHORING.md のプレースホルダーは、読者、扱う範囲、入口、カテゴリの境界が決まった時点で置き換えてください。
既存プロジェクトへの導入
移行用のコマンドは不要です。次の手順で進めます。
確認する —
README.md、CLAUDE.md、AGENTS.md、入れ子の指示ファイル、ドキュメント内の執筆方針を確認します。正本を一つ決める — 既存のものを再利用します。
CONTRIBUTING.mdの節、AUTHORING.md、公開ドキュメント内のページのいずれでも構いません。AUTHORING.mdを新設したり既存ファイルの名前を変えたりする必要はありません。足りない参照節だけを追加する — まず各ファイルで方針のパスを検索します。すでに方針を指していればそのままにします。Codexなど
AGENTS.mdを読むエージェントを使っていてAGENTS.mdがまだない場合は、参照節だけを含むAGENTS.mdを作成します。指示ファイルを丸ごと上書きしないでください。使っているスキルをつなぐ — 手書きの執筆スキルやコピーした
zudo-doc-writingスキルも、同じ方針のパスを指すようにします。結果を確認する — すべての参照先が実在すること、正本が一つだけであること、二つのファイルが互いを方針として指していないこと、古いパスが残っていないことを確認します。
正本の置き場所
公開コンテンツの外(
AUTHORING.mdやCONTRIBUTING.md)。サイトの読者には見えません。エージェントはリポジトリから直接読みます。公開コンテンツの中。たとえば
src/。貢献者はサイト上で読めます。content/ docs/ contributing/ authoring. mdx CLAUDE.mdとAGENTS.mdではサイトのURLだけでなくソースファイルのパスを参照し、エージェントがネットワークなしでローカルのソースへ到達できるようにします。
参照節の例
CLAUDE.md と AGENTS.md には次のような節を追加し、パスを自分の正本に置き換えます。
## Documentation structure
Before adding a page, changing what a page is for, or changing a category, read
`AUTHORING.md` (the project's editorial policy). Check for an existing page with
the same role, the right category, and whether the change alters what a category
means. Typo, wording, and formatting fixes skip this structure check.README.md には次のような節を追加します。
## Adding or reorganizing docs
Read `AUTHORING.md` before adding pages or changing categories. It describes who
the docs are for, what each category contains, and the steps for placing a new page.最新の状態に保つ
次の操作はそれぞれ別のもので、一つを行っても他は行われません。
@takazudo/zudo-docパッケージの更新 はフレームワークだけを更新します。AUTHORING.md、README.md、CLAUDE.md、AGENTS.md、コピー済みのスキルには触れません。新しいscaffoldの生成 はその時点のテンプレートを一度書き出すだけです。後のテンプレートの変更は既存プロジェクトには届きません。
配布スキルの更新 は、新しいスキルを手で
.claude/skills/にコピーすること、または生成されるドキュメントスキルならsetup:doc-skillを再実行することです。編集方針の更新 は、プロジェクトの管理者が正本のファイルを編集することです。
カテゴリや方針ファイルを移動したときは、同じ変更の中で README.md、CLAUDE.md、AGENTS.md、各スキルのパスを更新してください。このページの助言を適用する前に、使っているzudo-docのバージョンを確認してください。note-trayやeditorialツリーなどの機能は、それぞれのページに書かれたバージョンを必要とします。
関連項目
ドキュメントの書き方 — ページごとの執筆ルール
ナビゲーションの構成方法 — 最初のツリーの設計
Editorialナビゲーション — URLを動かさずに親を付け替える
Claudeスキル — 任意の
zudo-doc-writingスキル