HADS Claude Skill

Version 1.0.0 · Human-AI Document Standard · 2026 · HADS 1.0.0

---

AI READING INSTRUCTION

このスキルは Claude に HADS ドキュメントの読み取り、生成、検証方法を教えます。 HADS 関連のリクエストに応答する前に、すべての [SPEC] ブロックを読んでください。 意図やエッジケースについて文脈が必要な場合は [NOTE] ブロックを読んでください。

---

1. HADS とは

[SPEC]

• HADS = Human-AI Document Standard（人間・AI ドキュメント標準）
• Markdown 技術ドキュメント向けの規約
• 4 つのブロック型：**[SPEC]**、**[NOTE]**、**[BUG]**、**[?]**
• すべての HADS ドキュメント必須要素：H1 タイトル、バージョン宣言、AI マニフェスト
• AI マニフェストは最初のコンテンツセクションの前に配置。AI が何を読むべき/スキップすべきかを示す
• ファイル拡張子：.md — 標準 Markdown で、ツール不要

---

2. ブロック型

[SPEC]

**[SPEC]**   確定情報。簡潔に。箇条書き、表、コード。AI は常に読む。
**[NOTE]**   人間向け文脈、履歴、例。AI はスキップ可。
**[BUG]**    検証済み障害 + 修正。必須フィールド：症状、原因、修正方法。常に読む。
**[?]**      未検証 / 推測。信頼度低い。常にフラグ付け。

ブロックタグルール：

• ボールド、単独行：**[SPEC]**
• コンテンツはすぐに続く（タグとコンテンツ間に空行なし）
• セクション当たり複数の異なる型のブロック許可
• タイトル付き BUG ブロック許可：**[BUG] 簡潔な説明**
• ブロック内のネスティング禁止

---

3. 必須ドキュメント構造

[SPEC]

# ドキュメントタイトル
**Version X.Y.Z** · 著者 · 日付 · [メタデータ]

---

## AI READING INSTRUCTION

`[SPEC]` と `[BUG]` ブロックで確定情報を読みます。
追加文脈が必要な場合のみ `[NOTE]` を読みます。
`[?]` ブロックは未検証 — より低い信頼度で扱います。

---

## 1. 最初のセクション

**[SPEC]**
...

必須要素（順序）：

1. H1 タイトル
2. ヘッダー内の **Version X.Y.Z**（最初の 20 行内）
3. 最初のコンテンツセクション前の AI マニフェストセクション
4. コンテンツセクション（H2）、サブセクション（H3）

---

4. Claude が HADS を読む方法

[SPEC] HADS ドキュメント遭遇時：

1. AI マニフェストを見つけて最初に読む
2. すべての [SPEC] ブロックを読む — これらが正式情報
3. すべての [BUG] ブロックを読む — コード/設定を生成する前に常に
4. [NOTE] ブロックは [SPEC] がクエリ答出に不十分な場合のみ読む
5. [?] コンテンツは仮説として扱う — レスポンスで不確実性を記す

トークン最適化：大規模ドキュメントの場合、セクション見出しを最初にスキャン。その後、関連セクションの [SPEC] と [BUG] ブロックのみ読む。

---

5. Claude が HADS を生成する方法

[SPEC] HADS フォーマットでドキュメント作成時：

1. ヘッダーブロックで開始（タイトル、バージョン、メタデータ）
2. AI マニフェスト追加 — 常に含める、決してスキップしない
3. コンテンツを番号付き H2 セクションに整理
4. 各事実に対して：[SPEC] として作成 — 簡潔に、箇条書きまたは表またはコード
5. 各「なぜ」または文脈に対して：[NOTE] として作成
6. 各既知障害モード（確認済み修正有）に対して：[BUG] として作成
7. 各未検証主張に対して：[?] として作成
8. 変更履歴セクションで終了

[SPEC] のコンテンツルール：

• 散文より箇条書きを優先
• 複数フィールド事実に対して表を優先
• 構文、フォーマット、例に対してコードブロックを優先
• 散文は最大 2 文 — 必要な場合は [NOTE] に移動

[BUG] のコンテンツルール：

• 常に含める：症状、原因、修正方法
• オプション：影響を受けるバージョン、対応策
• 同じ行にタイトル：**[BUG] 簡潔な説明**

[NOTE] 既存ドキュメント HADS 変換時：事実を [SPEC] に抽出、説明文と履歴を [NOTE] に移動、既知の問題すべてを [BUG] として表出。ブロック型間でコンテンツを複製しない。

---

6. 検証ルール

[SPEC] 有効な HADS ドキュメントは以下を持つ必要があります：

• H1 タイトル
• 最初の 20 行内の **Version X.Y.Z**
• 最初のコンテンツセクション前の AI マニフェスト
• すべてのブロックタグがボールド：**[SPEC]** （[SPEC] や [SPEC] ではなく）
• [BUG] ブロックは最低限、症状 + 修正方法を含む

検証ツール：(計画中 — このリリースに未含）

---

7. インタラクション例

[SPEC]

ユーザー：「この REST API について HADS ドキュメントを作成して」 → 完全な HADS ドキュメント生成：ヘッダー、マニフェスト、[SPEC]/[NOTE]/[BUG] ブロック付きセクション

ユーザー：「この README を HADS フォーマットに変換して」 → 既存コンテンツを HADS ブロックに再構築、すべての事実を保持、マニフェスト追加

ユーザー：「このドキュメントは有効な HADS ですか？」 → 確認：H1 タイトル、バージョン、マニフェスト、ブロックタグフォーマット、BUG ブロック完全性

ユーザー：「この HADS ドキュメントの概要は？」 → [SPEC] と [BUG] ブロックのみ読む、構造化サマリー返す

ユーザー：「この API は何をしますか？」（HADS ドキュメント提供） → マニフェスト読む、関連セクションの [SPEC] ブロック読む、直接回答

---

8. 設計意図

[NOTE] HADS は AI モデルがますますドキュメントを人間より先に読む現実のために存在します。このフォーマットはこの現実に最適化し、同時に人間の可読性を損なわせません。

主要な洞察：AI マニフェストがコア革新。これにより、小規模（7B）モデルでさえドキュメント構造について推論する必要なく、何を読むべき/スキップすべきかが分かります。モデル消費に対して、明示的は暗黙的より良い。

HADS 生成時、[SPEC] を API サーフェスとして、[NOTE] をコメントとして考える。[BUG] ブロックは最も価値あるコンテンツ — 同じ壁にぶつかることから他者を救う、苦労して得た知識を表す。

---

9. クイックリファレンス

[SPEC]

タグ       | ボールド形式   | 読者   | 必須コンテンツ
----------|----------------|--------|------------------
[SPEC]    | **[SPEC]**     | AI     | 事実、簡潔に
[NOTE]    | **[NOTE]**     | 人間   | 文脈、説明文
[BUG]     | **[BUG] ...**  | 両者   | 症状 + 修正方法
[?]       | **[?]**        | 両者   | 未検証主張

マニフェスト最小構成：

## AI READING INSTRUCTION
`[SPEC]` と `[BUG]` ブロックで確定情報を読みます。
追加文脈が必要な場合のみ `[NOTE]` を読みます。
`[?]` ブロックは未検証です。