Markdown für KI pflegen
KI senkte die Kosten für das Schreiben von Dokumentation und erhöhte die Kosten für deren Verifikation. Die Arbeit hat sich verlagert — und der verifizierende Teil ist die Aufgabe von niemand anderem.
Markdown in KI-Workflows
Ein einziges Format für drei der sechs Kontextarten: Wissen, Anweisungen und Speicher.
Eine reine Textdatei ohne mechanischen Unterbau. Entscheidend ist, wie und wann sie genutzt wird: als Wissen, als Anweisungen, als Speicher — und ob der Agent bei jedem Schritt dafür bezahlt oder nur beim Abruf.
docs/handbook/onboarding.md
Retrieved on demandFront matter header
---
type: Handbook
stale_after: 2026-07-01
owner: "@people-ops"
---Document body
# Employee onboarding
Handbook for first-week setup. Dynamic context: the agent pays token costs only when a question reaches for it.
1. Collect laptop from IT on day one
2. Complete security training module
3. Meet your onboarding buddy
Retrieved on demand. Stale pages answer just as fluently as fresh ones.
KnowledgeRetrieved on demand
Pay only when fetched
InstructionsUser or model invoked
Progressive disclosure
MemoryAlways loaded
Paid on every turn
Volumen überholt die Prüfung
Bei einem einzelnen Dokument nimmt der Pflegeaufwand ab, während die Drift zunimmt — an dieser Schnittstelle hat sich die Arbeit verlagert.
Zwei unterschiedliche Dinge werden schwieriger: Bei einem einzelnen Dokument sinkt der Pflegeaufwand, während inhaltliche Drift steigt. Über einen Korpus hinweg wächst die Pflegefläche schneller als die Dateianzahl.
Wohin der Aufwand fließt
Was eine Maschine prüfen kann, wobei KI beschleunigt und was nur ein Mensch entscheiden kann.
Drei Grenzen: Was eine Maschine automatisiert, was KI beschleunigt und was nur ein Mensch entscheiden kann.
Was die Maschine verifiziert
Syntaktische und strukturelle Prüfungen, die deterministisch in Millisekunden ohne LLM laufen.
Machine checkResolves cleanly
✓Syntax: valid YAML frontmatter delimiter (---) & structure
✓Resource: present and well-formed URI (https://intranet.example.com/people-ops/handbook#onboarding)
✓Staleness: 2026-07-01T00:00:00Z parses with valid ISO timestamp
Machine checking proves the file is mechanically sound. It cannot determine if the policy is still active.
Was KI beschleunigt
Gegenprüfung von Texten gegen Handbücher, um Widersprüche für menschliche Reviews zu markieren.
Machine check✓ Resolved cleanly
AI recommendation⚠ Discrepancy flagged (needs check)
Observation
Compared onboarding.md against linked People Ops handbook. Section 4 of the handbook updated equipment lead times from 5 working days to 7 working days.
Proposal
Recommend updating line 15 and notifying the hiring manager.
The recommendation is rapid and insightful, but remains an unverified claim itself.
Was menschlich bleibt
Gilt die Richtlinie noch? Ist die Zuständigkeit korrekt? Grundwahrheiten, die kein Modell kennen kann.
Machine check✓ Resolved cleanly
AI recommendation⚠ Discrepancy flagged
Human judgmentOpen · Unresolved
?Does the buddy coffee on day one still match team practice?
?Does People Ops still close provisional accounts on Friday 5pm?
?Is the stated owner (@people-ops) still the accountable team?
Ground truth that no machine or language model can know. You are the one accountable when it is wrong.
Google OKF
Vollständiges OKF v0.2 Frontmatter-Schema für Provenienz, Vertrauensstufen und Lebenszyklus.
Ein standardisiertes Frontmatter-Schema zur Governance von KI-Wissensbasen. Provenienz, Vertrauensstufen und Lebenszyklus-Felder stehen direkt im Markdown neben dem Inhalt.
| 1 | --- | |
| 2 | # --- Provenance (§5.1) --- | |
| 3 | title: <Concept name> | # REQUIRED — Human-readable concept title |
| 4 | version: 0.2.0 | # SemVer concept version |
| 5 | description: <Summary> | # Summary statement for agent indexing |
| 6 | tags: [onboarding, ops] | # Categorical indexing keys |
| 7 | sources: | # Optional — materials this concept derives from |
| 8 | - id: <citation-key> | # Stable citation key for claim attribution |
| 9 | resource: <URI> | # REQUIRED within entry — URI or path |
| 10 | # --- Trust (§5.2, §5.3) --- | |
| 11 | generated: | # Content production record |
| 12 | by: <Actor> | # REQUIRED within generated — agent or human |
| 13 | at: <ISO 8601> | # Timestamp of generation |
| 14 | verified: | # Content verification event log |
| 15 | - by: <Actor> | # REQUIRED — reviewer who sets trust tier |
| 16 | at: <ISO 8601> | # Timestamp of verification |
| 17 | # --- Lifecycle (§5.4) --- | |
| 18 | stale_after: <ISO 8601> | # Temporal expiration date |
| 19 | owner: "@people-ops" | # Accountable team or user |
| 20 | --- |
OKF
Official Open Knowledge Format Specification (v0.2)
Open specification by Google Cloud Platform for agent-maintained knowledge repositories.
Die KI steuern
markdown-harness steuert den maschinellen Teil
Ein Dokument kann angeben, wie viel man ihm glauben darf. Kein blindes Vertrauen — ein verlässliches Fundament und ein klares Signal, wann ein Mensch eingreifen muss.
Läuft auf einem 100% deterministischen Kern
Ein Mechanismus, drei Auslöser, ein deterministischer Kern.
3 Entry Triggers
1. Agent read
Pre-read hook intercepts document read before injection.
2. Git commit
Pre-commit husky gate blocks invalid frontmatter.
3. Manual / CI run
CLI command `mh check` verifies entire corpus.
the same core, every time
Retrieve configurationconfig.yaml ↗
↓
Deterministic validationpure function
3 Corresponding Outcomes
Steer or block
Injects freshness warning or denies stale knowledge.
Prevent drift
Rejects commits lacking mandatory metadata fields.
Report corpus health
Outputs JSON violation summary for build pipelines.
Live-Demo
Die Prüfung live ausgeführt.
File under test
docs/handbook/onboarding.md
Asked of the agent
“What are the first-week onboarding steps for a new hire?”
Comparative contrast in terminal
Unhooked panel answers confidently from stale documentation. Hooked panels either warn the agent with steering instructions or deny access entirely.
Feature-Roadmap
Drei veröffentlicht, drei geplant.
v0.0.4 Shipped✓ Available now
- ✓Frontmatter linting — field constraints declared per path
- ✓Staleness checking — stale_after against a stated instant
- ✓Markdown harness skill — skill to install and configure harness
Planned RoadmapIn progress
- ○Drift detection — semantic checks against git commit diffs
- ○Corpus validation — cross-file reference integrity
- ○GitHub Action — automated verification in CI pipelines
Der verifizierende Teil liegt bei Ihnen
Zurück zum Venn-Diagramm: Der menschliche Bereich hervorgehoben, der Rest gedimmt.
Die Arbeit hat sich verlagert. Sie liegt bei Ihnen.
the AI region is my hypothesis — still unsettled
markdown-harness · github.com/hancrafted/markdown-harness