living-artifacts

リビングアーティファクト

Markdown アーティファクトを作成する場合、状態を示す静的なスナップショットには、必ずそれを再生成するコマンド、クエリ、またはスクリプトを併記してください。読者が、値の出どころを推測せずに、後から同じ値を再導出できるようにします。

スナップショットに該当するもの

執筆時から閲覧時までに変化する可能性が高いものです。

• ファイルツリー、ディレクトリー一覧、プロジェクトの構成
• ポート番号、ホスト名、URL、ファイルパス
• バージョン番号、デプロイ済みのコミット、イメージタグ
• 行数、テーブルの内容、API レスポンス本文
• ユーザー、リポジトリ、テーブル、サービス、環境変数の一覧
• 「現在失敗しているテスト」など、その他のステータスのスナップショット
• 別の場所に正規の定義がある設定値
• 件数と集計値

パターン

各スナップショットの近くに、以下を記載してください。

1. まず、値を生成する正確なコマンド、クエリ、またはスクリプトを示します。
2. 次に、執筆時点の情報であり、永続的に正しいものではないことを明記したうえで、スナップショットを示します。
3. 最後に、値が変わっている可能性があり、再生成するコマンドで更新できることを短く注記します。

単一の信頼できる情報源

値の正規の定義がすでにある場合は、アーティファクト内に重複して記載せず、その定義を参照してください。

悪い例	良い例
ドキュメントにポートをハードコードする	ポートを定義している環境変数または設定を参照する
README に名前を手作業で一覧表示する	ディレクトリーまたは生成済みの一覧を示す
git SHA をハードコードする	閲覧時に SHA を解決するコマンドを示す
API フィールドの一覧をドキュメントにコピーする	実行中の API をイントロスペクトするコマンドを示す

ファイル参照はクリック可能にする

Markdown アーティファクトで具体的なファイルパスに言及する場合は、読者がそのファイルを開けるように、Markdown リンクで囲んでください。これにより、リンク切れから変更をすばやく検出できます。

以下に適用してください。

• ソースファイル
• 設定ファイル
• 同階層のドキュメント
• スクリプト
• スキルファイル
• 読者が確認すべき生成済みアーティファクト

Markdown ファイルの場所を基準に相対パスを使用してください。プレースホルダー、グロブ、コードブロック内のパス形式の CLI 引数にはリンクを設定しないでください。

事実と仮定

• 事実は現時点で検証できる情報であり、再生成する手段を併記してください。
• 仮定は現時点では検証できないため、明示してください。

観測された内容と推論された内容を読者が区別できるよう、測定された事実と解釈を分けてください。

対象読者に合わせる

セットアップ用 README はエンドユーザー向けです。コントリビューター向けドキュメントと AGENTS.md はメンテナー向けです。適切な詳細度の情報を、適切な場所に記載してください。

セルフチェック

公開する前に、具体的な値をすべて確認し、次の点を検討してください。

1. 3 か月後も正しい値ですか？
2. そうでない場合、再生成する手段が近くにありますか？
3. 読者がその手段を実行すると、同じ値が得られますか？

そうでなければ、アーティファクトは未完成です。