Free

Claude meine Rails-Site AI-native machen lassen

Sechs praktische Schritte, um dieselbe Site für Menschen und KI-Agenten bereitzustellen — inklusive Copy-Paste-Checkliste

In den letzten vier Tagen habe ich mit Claude Code smarts.md von einer Smart-Contract-Doku-Site für Menschen in eine für AI-Agenten umgebaut.

Das klingt gleich, ist es aber nicht. Eine Site für Menschen optimiert Lesbarkeit, Suche und Ladezeit. Eine Site für AI-Agenten muss andere Fragen beantworten:

  • Erreichen dich AI-Crawler überhaupt oder sperrt deine Default-robots.txt sie aus?
  • Kann eine KI das HTML-Rendering überspringen und direkt sauberen Content ziehen?
  • Kann eine KI deine Tools aufrufen, ohne vorher „die Doku zu lesen"?
  • Sagt jede Seite der KI genau, wie man auf sie verweist und wie man sie abfragt?

Das sind die sechs Dinge, die ich Claude bauen ließ. Jedes einzelne ist für sich nützlich und lässt sich unabhängig in deine Site übernehmen.

1. AI-Crawler in der robots.txt ausdrücklich willkommen heißen

Die meisten Sites erben ihre robots.txt aus einer alten Vorlage, die jeden unbekannten User-Agent implizit verbietet. Aber ab 2025 sind viele AI-Crawler neue User-Agents — GPTBot, ClaudeBot, PerplexityBot, Applebot-Extended, Google-Extended, CCBot, meta-externalagent und mehr. Wenn du sie reinlassen willst, musst du explizit Allow setzen.

Die robots.txt von smarts startet mit einer Policy-Notiz und listet dann User-agent + Allow: / für 12 Crawler — OpenAI, Anthropic, Perplexity, Google Gemini, Apple, Common Crawl, Meta, Cohere. Die Haltung ist eindeutig: Diese Site existiert, um von KIs gelesen zu werden.

2. llms.txt — ein Menü für LLMs

llms.txt ist eine Konvention, die llmstxt.org vorschlägt: Du legst ein knappes Markdown im Site-Root ab, das dem LLM sagt, was diese Site ist, wie man sie nutzt und wo die wichtigsten Einstiegspunkte liegen. Der Elevator Pitch deiner Site.

Die llms.txt von smarts hat rund 60 Zeilen und enthält:

  • Positionierung in einem Satz (Live docs for every verified smart contract)
  • Wie man aus einem AI-Agenten darauf zugreift (MCP-Endpoint, Einzeiler-Setup)
  • URL-Muster (/{chain}/{address} vs. kurzer Slug)
  • MCP-Tools mit Ein-Satz-Beschreibung
  • Kuratierte Contract-Liste („Standardantworten" für das LLM)
  • Scope und Grenzen (welche Chains nicht unterstützt sind, Cache-Policy)

Die zentrale Einsicht: LLMs bezahlen deine Doku in Tokens, also crawlen sie nicht die ganze Site. Gib ihnen einen destillierten Index, und die Trefferquote steigt spürbar.

3. .well-known/mcp.json — früh setzen

Das MCP-Protokoll hat noch keine Discovery-Konvention wie /.well-known/openid-configuration. Heute crawlt kein öffentlicher Client einen festen well-known-Pfad.

Das Manifest zu veröffentlichen kostet trotzdem nur 30 Zeilen:

def well_known_mcp
  response.set_header("Cache-Control", "public, max-age=3600")
  response.set_header("Access-Control-Allow-Origin", "*")
  render json: {
    name: "smarts",
    version: "0.1.0",
    description: "...",
    protocol_version: "2024-11-05",
    transports: [{ type: "sse", endpoint: "https://smarts.md/mcp/sse" }],
    capabilities: { tools: true, resources: false, prompts: false },
    tools: MCP_TOOLS.map { |t| { name: t[:name], description: t[:blurb] } }
  }
end

Sobald eine Discovery-Konvention steht, muss ich keine Zeile ändern. Gleichzeitig ist das Selbstdokumentation für Entwickler — wer neugierig auf mein MCP ist, macht einfach curl smarts.md/.well-known/mcp.json.

Der Trick: Das tools-Array wird aus der Konstante MCP_TOOLS abgeleitet — Single Source of Truth. Ein vorhandener struktureller Test erzwingt, dass jede app/tools/*_tool.rb in dieser Konstante auftaucht. Dadurch erbt das Manifest kostenlos die Garantie, „neue Tools nicht zu vergessen".

4. Eine .md-Variante: WebFetch-freundliche Destillation für jede Seite

Mein Favorit. Das WebFetch-Tool von Claude Code muss beliebiges HTML selbst säubern und Inhalte extrahieren — Token-teuer und instabil. Was, wenn du .md direkt ausspielst?

Rails' respond_to unterstützt das nativ:

# config/routes.rb
get ":slug(.:format)", to: "contracts#show",
    constraints: { slug: ContractSlugs::ROUTE_PATTERN, format: /html|md/ }

https://smarts.md/usdc-eth liefert HTML; https://smarts.md/usdc-eth.md liefert 40 Zeilen Markdown — Adresse, Chain, Klassifizierung, MCP-Endpoint, Anfrage via AI-Agent, Quelllinks.

# USD Coin on Ethereum

- **Address:** `0xa0b8...`
- **Chain:** Ethereum
- **Classification:** ERC-20 Token

## Query via AI agent

- **MCP endpoint:** `https://smarts.md/mcp/sse`
- **Reference:** `usdc-eth`
- **Sample prompt:** "Tell me the current state of usdc-eth"

Ein Fetch, alle strukturierten Inhalte, die ein AI-Agent will, kein DOM-Parser nötig. Claude hat das zügig erledigt — ein Controller, zwei .md.erb-Templates, (.:format) in den Routes, fertig.

5. Eine MCP-Karte auf jeder Seite: Nutzer ihre KI hierher lenken lassen

Das ist die umgekehrte Entdeckung: Ein Teil meiner Besucher nutzt bereits Claude Code / Cursor / Windsurf. Sie landen auf einer Contract-Seite, und der nächste Impuls ist meist „lass meine KI mal draufschauen".

Also rendert jede Contract-Seite eine Karte mit:

  • Reference: der kuratierte Slug (z. B. usdc-eth) oder chain/address, mit Copy-Button
  • Sample prompt: „Tell me the current state of usdc-eth", mit Copy-Button
  • Noch keine KI angebunden?: Verweis auf mcp.smarts.md (Einzeiler-Setup)

Ein Klick Reibung zwischen „ich schaue mir diesen Contract an" und „ich frage meine KI dazu". Die Karte nutzt eine DaisyUI-Card und einen generischen Stimulus-Controller copy — 50 Zeilen erb. Ein Regressionstest fixiert die data-copy-text-value-Attribute, damit ein späteres Refactor nicht still den falschen String in Nutzer-Clipboards pastet.

6. Klassisches SEO, aber schema.org richtig gemacht

OpenGraph, Twitter Card, JSON-LD — die klassische Such- und Social-Card-Schicht. Lohnt sich, weil AI-Crawler hier auch lesen.

Die spannende Entscheidung ist, wie JSON-LD einen Smart Contract beschreiben soll. Claude hat sich für eine WebPage entschieden, die eine SoftwareApplication umschließt:

{
  "@type": "WebPage",
  "about": {
    "@type": "SoftwareApplication",
    "name": "USD Coin",
    "applicationCategory": "SmartContract",
    "operatingSystem": "Ethereum",
    "identifier": "0xa0b8..."
  }
}

operatingSystem bekommt den Chain-Namen, identifier die Adresse, additionalType die Klassifizierung (z. B. „Uniswap V3 Pool"). schema.org hat keinen eigenen SmartContract-Typ, aber SoftwareApplication plus diese Felder reichen aus, damit ein LLM versteht: „Das ist ein Contract auf Ethereum mit einer bestimmten Adresse."

Das OG-Bild ist ein 1200×630-summary_large_image; Twitter Card, Breadcrumbs, softwareVersion und license runden das Ganze ab.

Wie viel Arbeit ist das alles

Die sechs Punkte oben verteilen sich auf sieben PRs in vier Tagen:

PR Dateien Größe
feat/ai-crawler-discovery 2 ~126 loc
feat/well-known-mcp-manifest 4 ~129 loc
feat/markdown-contract-pages 6 ~298 loc
feat/contract-mcp-card 3 ~126 loc
feat/seo-meta-tags 8 ~292 loc
feat/seo-enrichments 8 ~189 loc
feat/og-card — —

Jeder ist ein eigenständiger PR mit eigenen Tests und Commit-Message. Diese feine Schnittkadenz ist das Wertvollste an der Zusammenarbeit mit Claude — jeder PR ist klein genug, den Diff auf einen Blick zu prüfen, aber gestapelt ergibt sich eine vollständige AI-Oberfläche der Site.

Copy-Paste-Checkliste

Wenn du eine Content-Site hast und sie AI-freundlich machen willst, geh in dieser Reihenfolge vor:

  1. Die wichtigsten AI-Crawler in robots.txt explizit erlauben
  2. Eine /llms.txt schreiben (ein destilliertes Menü)
  3. Kerninhalts-Seiten eine .md-Variante geben
  4. Wenn du einen MCP-Server betreibst, /.well-known/mcp.json veröffentlichen
  5. Eine „Frag deine KI zu dieser Seite"-Karte auf Content-Seiten setzen
  6. JSON-LD / OpenGraph mit den zum Content passenden schema.org-Typen befüllen

Die ersten fünf wird dir kaum ein SEO-Engineer erzählen — sie stehen nicht im klassischen Playbook. Aber aus vier Tagen Daten bei mir: Die AI-Traffic-Kurve und die Menschen-Traffic-Kurve sind zwei komplett unabhängige Reihen. Man muss beide bedienen.