Diátaxis ドキュメンテーション ガバナンス

このスキルは、ドキュメンテーションのための Diátaxis フレームワークを実装します。Diátaxis は、ユーザーのニーズに基づいて 4 つの異なるドキュメントタイプを識別します：チュートリアル、ハウツーガイド、リファレンス、説明。それぞれが異なる目的を果たし、異なる書き方が必要です。

動作モード

このスキルは、以下のいずれかのモードで動作します：

• classify（分類）: コンテンツがどの象限に属するかを識別する
• audit（監査）: ドキュメンテーションセットをギャップ、バランスの問題、違反について分析する
• generate（生成）: 指定された象限に新しいドキュメンテーションを作成する
• restructure（再構成）: 既存の混合モードのコンテンツを分割または再編成する

動作モードはユーザーのリクエストから推測するか、明示的に指定する必要があります。動作モードを確実に推測できない場合は、進める前にユーザーに確認を求めてください。

象限の純粋性を維持できない場合、説明を伴う拒否は有効で成功した結果です。

生成モードのポリシー

生成モードでは、コンテンツを生成する前に、以下のいずれかが真である必要があります：

• ユーザーがターゲット象限を明示的に述べている（「X のためのハウツーを書いてください」）、または
• エージェントがリクエストを分類し、確信度とエビデンス付きで推論を提示し、ユーザーの確認を受ける

Diátaxis コンパス

コンテンツを正確に 1 つの象限に分類するには、この意思決定ツリーを使用します：

コンテンツが...	...かつユーザーの...	...であれば、属する象限は...
アクション（実行）を通知する	習得（学習）をサポート	チュートリアル
アクション（実行）を通知する	応用（仕事）をサポート	ハウツーガイド
コグニション（知識）を通知する	応用（仕事）をサポート	リファレンス
コグニション（知識）を通知する	習得（学習）をサポート	説明

問うべき 2 つの質問：

1. これはアクション（実行）それともコグニション（知識）を通知しますか？
2. これは習得（学習・研究）それとも応用（仕事）をサポートしていますか？

象限の概要

チュートリアル（学習志向）

学習者を実践的な経験へと導くレッスンです。インストラクターは学習者の成功に責任を持ちます。説明ではなく、実行に焦点を当てます。早期かつ頻繁に成果を提供します。説明を最小限に抑えます。選択肢や代替案はありません。

• 形式: 具体的なステップを含む順序立てたレッスン
• 言語: 「〜します」「まず X を実行してください」「〜に気づくでしょう」
• ではないもの: 概念の教示、代替案の提供、理由の説明

ハウツーガイド（目標志向）

すでに能力がある読者を実際の問題を解決するために導く指示です。読者が何を達成したいかを知っていることを前提としています。研究ではなく、仕事に焦点を当てています。

• 形式: 特定の目標に対応するステップの一連
• 言語: 「X を達成するには、Y を実行してください」「もし〜したければ」条件付き命令法
• ではないもの: 初心者への教育、概念の説明、機械的仕組みの記述

リファレンス（情報志向）

機械的仕組みの技術的説明です。厳密で、中立的で、正確です。構造は説明対象の物事を反映しています。ユーザーはそれを参照し、読むのではありません。

• 形式: 構造化された説明、表、仕様
• 言語: 「X は〜です」「オプションは〜です」事実的な述べ方
• ではないもの: 指示、理由の説明、物語的な叙述、意見

説明（理解志向）

文脈、背景、「なぜ」に答える論述的な扱いです。つながりを作り、意見を認め、主題を循環的に扱います。

• 形式: トピックについての散文討論
• 言語: 「X の理由は〜です」「これは〜だからです」「〜を考慮してください」
• ではないもの: ステップバイステップの手順、技術仕様、タスク教育

コア ワークフロー

分類の場合

1. コンテンツを注意深く読み込む
2. コンパスを適用：アクション/コグニション × 習得/応用
3. 単一の象限を特定する
4. 確信度とエビデンス付きで報告する

生成の場合

1. ターゲット象限を確認する（明示的に述べられている、または確認を伴い推測される）
2. 象限の制約を厳密に適用する
3. 象限の混合を拒否；必要に応じて分割を推奨する
4. 象限の特性に照らして出力を検証する

監査の場合

1. すべてのドキュメンテーションをインベントリする
2. 各ドキュメントを分類する
3. ギャップを特定する（欠けている象限）
4. 違反にフラグを立てる（混合モード、不適切な象限）
5. バランスの問題を報告する（例：「リファレンス重視、チュートリアル不足」）

再構成の場合

1. 既存のコンテンツを分類する
2. 象限違反を特定する
3. 分割を提案する（象限ごとに 1 つのドキュメント）
4. 変更前にユーザーに確認するための計画を提示する

出力要件

分類または違反にフラグを立てる場合、常に以下を提供してください：

• 象限: 識別されたタイプ（チュートリアル、ハウツー、リファレンス、説明）
• 確信度: 高 | 中 | 低
• エビデンス: 特定のフレーズ、構造パターン、または信号

例：

ハウツーに分類されます（確信度：高）。 エビデンス：命令動詞（「設定する」「セットアップする」）、目標志向の見出し、概念的な枠組けの欠如、読者の能力を前提としている。

違反検出

これらのアンチパターンにフラグを立てます：

• 説明付きチュートリアル: 長い「なぜ」セクション、概念的な脱線
• 教える型のハウツー: 初心者向けの枠組み、「学びましょう」という言語
• 物語的なリファレンス: 一人称の声、手続き的な指示
• 手順を含む説明: 番号付きステップ、命令法の命令
• 混合モード文書: 単一の文書内の複数の象限シグナル

詳細な検出パターンと修復については、references/anti-patterns.md を参照してください。

対象外

このスキルは以下を行いません：

• ドキュメンテーション戦略または情報アーキテクチャを発明する
• 製品アーキテクチャまたは機能スコープを決定する
• 複数の Diátaxis 象限を単一のドキュメントにマージする
• リポジトリ固有のドキュメンテーション規則またはスタイルガイドをオーバーライドする
• 明示的な象限分類なしでコンテンツを生成する

追加リソース

• 詳細な象限の特性: references/quadrants.md
• 分類の意思決定ツリー: references/compass.md
• アンチパターンと修正: references/anti-patterns.md

クレジット

Diátaxis は Daniele Procida による作品です。このスキルは、AI エージェントが使用するために Diátaxis フレームワークをエンコードしています。権威あるソースと完全なドキュメンテーションについては、diataxis.fr を参照してください。

CC-BY-SA 4.0 の下でライセンスされています。引用メタデータは Diátaxis GitHub リポジトリで入手可能です。