github.com/catcam/hads
AIモデルは、ユーザーが読む前にあなたのドキュメントを読みます。しかし、ドキュメントは人間向けに書かれています。
この不一致には実際のコストがあります：トークンの無駄、幻覚、長いドキュメントで諦めてしまうローカルモデル。
JSONから Ableton Live のプロジェクトファイルを生成するツールを作成しながら、数週間この問題をデバッグしました。技術的なドキュメントをモデルに入力するたび、同じことが起こりました — 文脈ウィンドウの半分が物語的な文章に占有され、モデルが事実を誤って抽出したり、重要なバグ修正を完全に見逃したりします。
解決策は、より良いプロンプトではありませんでした。より構造化されたドキュメントでした。
Introducing HADS
HADS（Human-AI Document Standard）は、Markdown のタグ付け規約です。新しい形式でも新しいツールでもありません。人間とAIモデルの双方が、読んでいるコンテンツの種類を知らせる、4つのタグだけです。
[SPEC] 権威ある事実。端的。AIは常に読む。
[NOTE] 人間の文脈、歴史、例。AIはスキップしてよい。
[BUG] 検証済みの失敗と修正。常に読む。
[?] 未検証 / 推定。信頼度は低い。
すべての HADS ドキュメントは、AI マニフェストで始まります — モデルに何を読んで何をスキップするかを明示的に指示する短い段落です。
markdown## AI読解指示
[SPEC] および [BUG] ブロックを、権威ある事実として読む。
[NOTE] は追加の文脈が必要な場合のみ読む。
[?] ブロックは未検証です — 信頼度を低く扱う。
それで以上です。文書はモデルにどう読ませるかを教えます。
小型モデルでの有効性
4k のコンテキストウィンドウを持つ 7B ローカルモデルは、文書構造を信頼性高く推論することはできません。しかし、文書の先頭にある明示的な指示には従えます。
マニフェストは構造的推論の必要性を完全になくします。モデルは何が重要かを自分で決める必要はなく、文書がそれを教えてくれます。
HADSドキュメントの実例
実際の例 — 認証に関するドキュメント：
markdown## 認証
[SPEC]
- 方法: Bearerトークン
- ヘッダー:
Authorization: Bearer <token> - トークン有効期間: 3600 秒
- リフレッシュ:
POST /auth/refresh
[NOTE]
トークンは元々セッションベースでした（以前のバージョン）。レガシーなドキュメントで cookie 認証が言及されているのを見たら無視してください — その切り替えは2022年に起きました。
[BUG] パスワード変更後にトークンが静かに拒否される
症状: 401 with body {"error": "invalid_token"} — 期限切れトークンと同じ。
原因: パスワード変更時に全トークンが無効化され、別のエラーコードがない。
修正: いかなる 401 でも再認証。401 が常に期限切れを意味するとは限らない。
AI がこれを読むと、method、header、expiry、refresh endpoint — すべてを 1 つの [SPEC] ブロックに抽出します。人間は [NOTE] を読んで履歴を理解します。両方とも [BUG] を読みます。
重複はありません。1つの文書。2人の読者。
BUG ブロックは最も重要な革新です
技術文書で最も価値のある内容は、既知の故障モードです。誰かが壁にぶつかり、それをデバッグして書き留めました。通常の文書では、これが変更履歴や 2019 年の Stack Overflow の回答に埋もれてしまいます。
HADS は [BUG] ブロックを第一級の扱いにします。HADS ドキュメントを読むすべての AI は、コードを生成する前にすべての [BUG] ブロックを読了します。これだけで幻覚の一部の発生を排除します。
リポジトリには何が入っています
SPEC.md — 完全な正式仕様
examples/ — 3つの完全な例文書（REST API、バイナリファイル形式、設定システム）
validator/validate.py — CI/CD の終了コードを備えた Python バリデータ
claude-skill/SKILL.md — Claude が自動的に HADS ドキュメントを生成するためのスキルファイル
すべて MIT。HADS ドキュメントを読むのに依存関係はゼロ。
GitHub
github.com/catcam/hads
フィードバック歓迎 — 特にローカルモデルを実行している方から。マニフェスト方式は、あなたの文脈管理に本当に役立つのでしょうか？
