mcpField
H
hads

hads

github.com/wshobsonドキュメント41.9k6.7k 回インストール2 週間前に更新
リポジトリ

hads について

HADS 形式の Markdown 技術文書を読み、生成し、確認するための Claude スキルです。4種類のブロックと必須構成を定めており、このリリースにバリデーターは含まれていません。

主な機能

  1. 014種類の HADS ブロックの定義
  2. 02必須文書構成の指定
  3. 03ブロック単位の読み方の案内
  4. 04HADS 文書の生成方法
  5. 05書式検証ルールの提示

活用シーン

  1. 01既存文書を HADS 形式へ変換
  2. 02標準に沿った技術文書の作成
  3. 03構成とブロックタグの確認
  4. 04HADS 文書から事実を要約

インストール

コマンドをコピーしてターミナルで実行します。

$npx skills add https://github.com/wshobson/agents --skill hads

インストール後、Claude Code で/hadsを入力して読み込まれたか確認します。

詳細

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. WHAT IS HADS

[SPEC]

  • HADS = Human-AI Document Standard
  • Markdown 技術ドキュメントのための規約
  • 4 つのブロック種別: **[SPEC]**、**[NOTE]**、**[BUG]**、**[?]**
  • すべての HADS ドキュメントに必須: H1 タイトル、バージョン宣言、AI マニフェスト
  • AI マニフェストは最初のコンテンツセクションの前に配置し、AI に何を読むべきか、何をスキップすべきかを伝える
  • ファイル拡張子: .md — 標準の Markdown、ツールは不要

2. BLOCK TYPES

[SPEC]

**[SPEC]**   Authoritative fact. Terse. Bullet lists, tables, code. AI reads always.
**[NOTE]**   Human context, history, examples. AI may skip.
**[BUG]**    Verified failure + fix. Required fields: symptom, cause, fix. Always read.
**[?]**      Unverified / inferred. Lower confidence. Always flagged.

ブロックタグのルール:

  • 太字で、単独行に配置: **[SPEC]**
  • コンテンツは直後に続く（タグとコンテンツの間に空行を入れない）
  • 1 つのセクションに異なる種別の複数ブロックを配置可能
  • タイトル付き BUG ブロックも可能: **[BUG] Short description**
  • ブロックの中にブロックをネストしない

3. REQUIRED DOCUMENT STRUCTURE

[SPEC]

# Document Title
**Version X.Y.Z** · Author · Date · [metadata]

---

## AI READING INSTRUCTION

Read `[SPEC]` and `[BUG]` blocks for authoritative facts.
Read `[NOTE]` only if additional context is needed.
`[?]` blocks are unverified — treat with lower confidence.

---

## 1. First Section

**[SPEC]**
...

順番に必要な要素:

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

4. HOW CLAUDE READS HADS

[SPEC] HADS ドキュメントに遭遇したとき:

  1. まず AI マニフェストを見つけて読む
  2. すべての [SPEC] ブロックを読む — これらがグラウンドトゥルースです
  3. すべての [BUG] ブロックを読む — コードや設定を生成する前に必ず読んでください
  4. [SPEC] がクエリに答えるのに不十分な場合にのみ [NOTE] ブロックを読む
  5. [?] の内容は仮説として扱う — 応答に不確実性を明記する

トークン最適化: 大きなドキュメントでは、まずセクション見出しをスキャンし、その後関連するセクションの [SPEC] と [BUG] ブロックのみを読んでください。

5. HOW CLAUDE GENERATES HADS

[SPEC] HADS 形式でドキュメントを書くよう求められたとき:

  1. ヘッダーブロック（タイトル、バージョン、メタデータ）から始める
  2. AI マニフェストを追加する — 常に含め、決して省略しない
  3. コンテンツを番号付きの H2 セクションに整理する
  4. 各事実について: [SPEC] として書く — 簡潔に、箇条書きか表かコードで
  5. 各「なぜ」やコンテキストについて: [NOTE] として書く
  6. 確認済みの修正がある既知の障害モードについて: [BUG] として書く
  7. 検証されていない主張について: [?] として書く
  8. 変更履歴セクションで終える

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

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

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

  • 常に含める: 症状、原因、修正
  • 任意: 影響を受けるバージョン、回避策
  • タイトルは同じ行に: **[BUG] Short description**

[NOTE] 既存のドキュメントを HADS に変換する場合: 事実を [SPEC] に抽出し、ナラティブと履歴を [NOTE] に移し、すべての既知の問題を [BUG] として表面化させてください。ブロック種別間でコンテンツを重複させないでください。

6. VALIDATION RULES

[SPEC] 有効な HADS ドキュメントは以下を備えている必要があります:

  • H1 タイトル
  • 最初の 20 行内の **Version X.Y.Z**
  • 最初のコンテンツセクションの前の AI マニフェスト
  • すべてのブロックタグが太字: **[SPEC]** であり、[SPEC] や [SPEC] ではない
  • [BUG] ブロックには少なくとも症状 + 修正が含まれる

バリデーター: (planned — not yet included in this release)

7. EXAMPLE INTERACTIONS

[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]

Tag       | Bold format    | Reader  | Required content
----------|----------------|---------|------------------
[SPEC]    | **[SPEC]**     | AI      | Facts, terse
[NOTE]    | **[NOTE]**     | Human   | Context, narrative
[BUG]     | **[BUG] ...**  | Both    | Symptom + fix
[?]       | **[?]**        | Both    | Unverified claims

マニフェストの最小構成:

## AI READING INSTRUCTION
Read `[SPEC]` and `[BUG]` blocks for authoritative facts.
Read `[NOTE]` only if additional context is needed.
`[?]` blocks are unverified.

コメント

Markdown 対応