fable-artifact

Fable Artifact

要件と根拠を、内容、構成、図、リンク、レンダリング結果をそれぞれ独立して検証できる、単独で完結した成果物にまとめます。

ミッション

Markdown として解析できる、または図が洗練されて見えるだけでは、成果物が成功したとはいえません。適切な対象者に適切な主張を伝え、情報源に忠実で、前提を明示し、ユーザーが実際に利用する媒体で正しく表示される必要があります。

有効にする場合

• RFC、アーキテクチャ提案、技術レポート、ランブック、意思決定記録、図、または充実した単独のドキュメントを作成する場合；
• 分析結果を永続的なドキュメントにまとめる場合；
• 確立された要件や根拠をもとに、図や対話型の解説成果物を作成する場合。

有効にしない場合

• 1 段落の回答で十分な場合；
• アプリケーションロジック自体の変更が必要な場合（fable-execute）；
• 主な作業が数値グラフの選定である場合（fable-dataviz）；
• 成果物に必要な事実がまだ調査・発見されていない場合。

成果物の分類

成果物	主な要件
RFC／提案	意思決定、代替案、トレードオフ、受け入れ／ロールアウト
アーキテクチャドキュメント	境界、データ／制御フロー、不変条件、デプロイ
ランブック	トリガー、前提条件、実行可能な手順、ロールバック／エスカレーション
インシデント／レポート	因果関係を捏造せず、時系列／根拠／影響を示す
意思決定記録	コンテキスト、決定、代替案、結果
図	装飾的なボックスではなく、意味のあるトポロジー／シーケンス／状態
対話型の解説	アクセシブルな操作性と、決定論的なコンテンツ／情報源

プロトコル

ステージ 1 — 対象者と目的を定める

誰が成果物を利用し、どのような意思決定や行動を支援する必要があるかを明記します。1 つの成果物に複数のセクションを含めてもかまいませんが、主なコミュニケーション上の目的は 1 つに定めます。

ステージ 2 — 主張と情報源の対応表を作成する

洗練された文章を書く前に、以下を特定します。

• 測定済み、または情報源に裏付けられた事実；
• 設計上の決定；
• 前提／推論；
• 未解決事項；
• データ／ビジュアルの情報源；
• 引用／リンクが必要な主張。

ドキュメントを充実して見せるために、例、指標、アーキテクチャコンポーネント、テスト結果、引用を捏造してはいけません。

ステージ 3 — 成果物の種類に合わせて構成を選ぶ

例：

• RFC：背景 → 目標／対象外 → 根拠 → 選択肢 → 決定 → 設計 → リスク → ロールアウト／ロールバック → 受け入れ；
• ランブック：症状／トリガー → 安全上の前提条件 → 診断 → 対応 → 検証 → ロールバック／エスカレーション；
• アーキテクチャ：範囲 → コンテキスト → コンポーネント／境界 → フロー → データ／状態 → 障害／セキュリティ → デプロイ／運用 → 決定。

ドキュメントの目的に役立たない、汎用テンプレートのセクションは避けます。

ステージ 4 — 意味に基づいて図を設計する

各ノード／エッジは、実在するコンポーネント、状態、依存関係、イベント、データフロー、または制御フローを表す必要があります。曖昧さがある場合は、方向や意味をラベルで示します。

Mermaid などのテキスト形式の図では：

• 構文を検証します；
• ラベルを安全に引用／エスケープします；
• 巨大で読みにくいグラフを避けます；
• 1 つの図が複雑になりすぎた場合は、問いに応じて図を分けます（コンテキスト、コンテナー、シーケンス、状態）。

ステージ 5 — 素早く読め、質の高い意思決定に役立つ文章を書く

階層を活用し、セクションを短く保ち、比較に役立つ場合にのみ表を使い、コールアウトは控えめにします。必要に応じて Decision、Risk、Unknown、Evidence といった語を明示します。

すべての文を箇条書きにしたり、背景の詳細の下に主要な決定を埋もれさせたりしてはいけません。

ステージ 6 — 内部の一貫性を検証する

以下を照合します。

• 用語／名前／バージョンが全体を通じて一致している；
• 図と文章の内容が一致している；
• 例が実際の API／スキーマと一致している；
• リンク／アンカーが存在する；
• 推奨事項が引用された根拠に基づいている；
• 採用された設計と矛盾するセクションがない。

ステージ 7 — 対象の媒体でレンダリングする

レンダリングが重要な場合、ソースファイルは最終成果物ではありません。必要に応じて Markdown／Mermaid／HTML／PDF／その他の対象形式をプレビュー／レンダリングし、切り抜け、図の破損、はみ出し、アセットの欠落、読みにくい文字組み、アクセシブルでない操作性がないか確認します。

ステージ 8 — 事実性と使いやすさをレビューする

次の点を確認します。

• 読者は主要な判断やアクションをすぐに見つけられますか？
• どの記述が事実で、どれが提案や推論ですか？
• 根拠のない主張はありませんか？
• 図によって、実際には存在しない関係が示唆されませんか？
• 将来の読者は、チャットの文脈がなくても成果物を実行・保守できますか？

判断ルール

• もっともらしい内容で空白を埋めるよりも、「不明／未確認」と明記することを優先します。
• 図は問いに答えるものにします。1つの図にトポロジー、シーケンス、デプロイ、所有者が読みやすさを損なうほど混在する場合は、分割します。
• 追跡可能性が重要な外部情報や最新情報の主張には、リンクや引用を使用します。出典を捏造しないでください。
• 生成されたグラフや表のデータの出所は、DataViz／調査パケットから引き継がれます。
• 設計の変更に応じて成果物も変わる場合は、完了前にすべての図、例、判断に関する参照を整合させます。
• インタラクティブな成果物には、用途に応じたキーボード操作、アクセシビリティ、フォールバックの動作が必要です。目新しいビジュアルは、コミュニケーションの代わりにはなりません。
• 意思決定に重大な影響を与えない限り、エグゼクティブ向け／意思決定用の成果物に実装の詳細を含めないでください。
• リポジトリ／指定された成果物の保存先を使用し、ルートや一時パスを散らかさないでください。

不変条件

• すべての事実に関する主張は、出典に裏付けられているか、推論／提案であることが明確に示されています。
• 架空のデータ、引用、テスト結果、アーキテクチャコンポーネント、事例研究はありません。
• 図、文章、例が同じ設計を説明しています。
• レンダリングが納品に含まれる場合は、対象環境でのレンダリングを確認します。
• 隠れた会話の文脈がなくても、成果物単独で理解できます。
• 読者が主要な判断やアクションを特定できます。

失敗の分類

内容の捏造

不足している事実を、もっともらしい詳細で埋めてしまうことです。削除するか、調査するか、不明であると明記します。

図の意味のずれ

図が現在の設計と一致しなくなったり、誤ったフローを示唆したりすることです。再生成し、整合させます。

テンプレートの肥大化

汎用的なセクションが、ドキュメント本来の役割を見えにくくすることです。意思決定に役立たないセクションを削除します。

ソースとレンダリングの不一致

Markdown／HTML のコードは正しく見えても、対象のレンダラーでアセットや図が切れたり、壊れたりすることです。レンダリング結果を確認します。

内部矛盾

セクション間でバージョン、名称、判断が異なることです。基準となる主張の一覧を1つ作成し、整合させます。

読者とのミスマッチ

技術的には完全でも、想定読者に対して詳細度が低すぎる、または高すぎることです。読者の判断やアクションを軸に再構成します。

リンク／ソースの陳腐化

重要な根拠が無効または欠落したパスを指していることです。修正するか、適切であれば関連コンテンツをローカルに保持します。

アンチパターン

• 提案を説得力のあるものに見せるための架空の指標；
• エッジの意味が明確でない、装飾的なボックスだらけの Mermaid 図；
• 目的にかかわらず使われる汎用的な「概要／アーキテクチャ／結論」テンプレート；
• 生の調査メモを統合せずにそのまま転記すること；
• コールアウトブロックをあらゆる場所で使うこと；
• 対象の表示環境でプレビューせずに、レンダリング済み／アクセシブルであると主張すること；
• アーキテクチャの説明文を更新しても、図が古いままであること；
• 文を裏付けていない引用；
• 主な判断の前に、実装の詳細を長々と並べること。

成果物パケット

Audience / job:
Artifact type + destination:
Claim/source map:
Decisions vs assumptions vs unknowns:
Structure rationale:
Diagram(s) + question answered:
Data/source provenance:
Internal consistency checks:
Rendered validation:
Accessibility/usability check:
Known limitations:

完了条件

成果物は、次の条件を満たしたときに完成です。

• 内容が根拠に基づき、読者と目的に合致している；
• 構成が意図された判断やアクションを支えている；
• 図、例、データに意味上の一貫性がある；
• 不明点が捏造されず、明示されている；
• 対象のレンダリング、リンク、アセットが検証されている；
• 事前の文脈がない読者でも成果物を理解し、活用できる。

段階的なリソース

• 詳細ガイド：references/source-grounded-artifact-design.md
• 既存のガイド：references/artifact-composition-guide.md
• 例：examples/system-architecture-diagram.md