AI models increasingly read documentation before humans do. But docs are written for humans — verbose, contextual, narrative. This creates token waste and increases hallucination risk, especially on smaller/local models.
HADS is not a new format. It's a tagging convention on top of standard Markdown:
Every document starts with an AI manifest — a short paragraph that tells the model what to read and what to skip. This is the core idea: explicit instructions in the document itself, not in the prompt.
A 7B local model with limited context window can read a HADS document and extract facts correctly because it doesn't have to reason about structure — the document tells it how.
The repo includes:
- Full specification (SPEC.md)
- Three example documents (REST API, binary file format, config system)
- Python validator (exit codes for CI/CD)
- Claude skill (SKILL.md) for AI-assisted doc generation
All MIT. Feedback welcome — especially from people running local models.
4 comments
[ 3.0 ms ] story [ 21.9 ms ] threadhttps://github.com/catcam/hads
AI models increasingly read documentation before humans do. But docs are written for humans — verbose, contextual, narrative. This creates token waste and increases hallucination risk, especially on smaller/local models.
HADS is not a new format. It's a tagging convention on top of standard Markdown:
Every document starts with an AI manifest — a short paragraph that tells the model what to read and what to skip. This is the core idea: explicit instructions in the document itself, not in the prompt.A 7B local model with limited context window can read a HADS document and extract facts correctly because it doesn't have to reason about structure — the document tells it how.
The repo includes: - Full specification (SPEC.md) - Three example documents (REST API, binary file format, config system) - Python validator (exit codes for CI/CD) - Claude skill (SKILL.md) for AI-assisted doc generation
All MIT. Feedback welcome — especially from people running local models.