Claude'a Rails Siteni AI-Native Hale Getirtmek

Son dört günde Claude Code'la birlikte smarts.md'yi insanlar için yapılmış bir akıllı kontrat dokümantasyon sitesinden AI ajanları için yapılmış bir siteye dönüştürdük.

Aynı şey gibi duruyorlar. Değiller. İnsanlar için bir site; okunabilirlik, aranabilirlik ve yükleme süresi için optimize edilir. AI ajanları için bir sitenin cevaplaması gereken sorular farklıdır:

• AI crawler'ları sana ulaşabiliyor mu, yoksa varsayılan robots.txt kapıyı kilitlemiş mi?
• Bir AI, HTML render etmeden doğrudan temiz içerik alabiliyor mu?
• Bir AI, önce "dokümanları okumadan" senin tool'larını çağırabiliyor mu?
• Her sayfa AI'a tam olarak nasıl referans verileceğini ve nasıl sorgulanacağını söylüyor mu?

Claude'a yaptırdığım altı şey aşağıda. Her biri tek başına faydalı ve kendi sitene ayrı ayrı taşıyabilirsin.

1. robots.txt'te AI crawler'ları açıkça davet et

Çoğu site robots.txt'ini eski bir şablondan miras alır ve tanımadığı User-Agent'ları üstü kapalı şekilde engeller. Ama 2025 sonrasında birçok AI crawler'ı yeni User-Agent — GPTBot, ClaudeBot, PerplexityBot, Applebot-Extended, Google-Extended, CCBot, meta-externalagent ve fazlası. İçeri almak istiyorsan açıkça Allow etmelisin.

smarts'ın robots.txt'i bir politika notuyla açılıyor, sonra OpenAI, Anthropic, Perplexity, Google Gemini, Apple, Common Crawl, Meta ve Cohere'yi kapsayan 12 crawler için User-agent + Allow: / listeliyor. Tavır net: bu site AI tarafından okunmak için var.

2. llms.txt — LLM'ler için menü

llms.txt, llmstxt.org'un önerdiği bir kongre: site köküne kısa bir Markdown koyarsın ve LLM'e bu site nedir, nasıl kullanılır, ana giriş noktaları nerede anlatırsın. Sitenin elevator pitch'i gibi.

smarts'ın llms.txt'i yaklaşık 60 satır:

• Tek cümle konumlandırma (Live docs for every verified smart contract)
• AI ajanından nasıl kullanılacağı (MCP endpoint, tek satırlık kurulum komutu)
• URL desenleri (/{chain}/{address} vs kısa slug)
• Tek cümle açıklamalı MCP tool listesi
• Seçilmiş kontrat listesi (LLM'e "varsayılan cevaplar" vermek için)
• Kapsam ve sınırlar (hangi chain'ler desteklenmiyor, cache politikası)

Püf nokta: LLM'ler dokümanını token ile okuyor, o yüzden tüm siteyi crawl etmezler. Damıtılmış bir dizin ver, isabet oranı belirgin şekilde artar.

3. .well-known/mcp.json — erken bahis

MCP protokolü henüz /.well-known/openid-configuration gibi bir discovery kongresini standartlaştırmadı. Bugün sabit bir well-known yolunu crawl eden genel bir client yok.

Ama manifest'i yayımlamak 30 satır:

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

Bir discovery kongresi netleştiği anda tek satır değiştirmeme gerek yok. Aynı zamanda developer'lar için self-documentation — MCP'mi merak eden curl smarts.md/.well-known/mcp.json yeter.

Kilit nokta: tools dizisi MCP_TOOLS sabitinden türetiliyor, tek hakikat kaynağı. Mevcut bir yapısal test her app/tools/*_tool.rb'nin o sabit içinde görünmesini zorluyor, dolayısıyla manifest "yeni tool'u unutma" garantisini bedavaya miras alıyor.

4. .md varyantı: her sayfa için WebFetch-dostu damıtma

Bu benim favorim. Claude Code'un WebFetch tool'u gelişigüzel HTML'i kendisi temizleyip içerik çıkarmak zorunda — token açısından pahalı ve güvenilmez. Peki doğrudan .md versen?

Rails'in respond_to'su bunu natif destekliyor:

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

https://smarts.md/usdc-eth HTML döner; https://smarts.md/usdc-eth.md 40 satırlık Markdown döner — adres, chain, sınıflandırma, MCP endpoint, AI ajanından nasıl sorgulanacağı, kaynak linkler.

# 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"

Tek fetch, AI ajanının istediği tüm yapısal içerik orada, DOM parser'a gerek yok. Claude bunu hızlı halletti — bir controller, iki .md.erb şablonu, routes'a (.:format), bitti.

5. Her sayfada bir MCP kartı: kullanıcıların AI'larını buraya yönlendirmesine izin ver

Bu tam tersi yönde bir discovery: ziyaretçilerimin bir kısmı zaten Claude Code / Cursor / Windsurf kullanıyor. Bir kontrat sayfasına geliyorlar, bir sonraki adım çoğunlukla "bırak AI'm buna bir baksın" oluyor.

O yüzden her kontrat sayfasında şu kartı render ediyorum:

• Reference: seçilmiş slug (örn. usdc-eth) veya chain/address, yanında Kopyala butonu
• Sample prompt: "Tell me the current state of usdc-eth", yanında Kopyala butonu
• Henüz AI bağlı değil mi?: mcp.smarts.md'ye işaret (tek satırlık kurulum)

"Bu kontrata bakıyorum" ile "AI'ma soruyorum" arasında tek tıklık sürtünme. Kart bir DaisyUI card'ı ve genel bir Stimulus copy controller kullanıyor — 50 satır erb. Bir regresyon testi data-copy-text-value özelliklerini sabitliyor, böylece gelecekte bir refactor kullanıcıların panosuna sessizce yanlış string yapıştıramaz.

6. Klasik SEO, ama schema.org'u doğru kullanarak

OpenGraph, Twitter Card, JSON-LD — geleneksel arama ve sosyal kart katmanı. Yapmaya değer, çünkü AI crawler'ları da burayı okuyor.

İlginç seçim, JSON-LD'nin bir akıllı kontratı nasıl tanımlaması gerektiği. Claude WebPage'in bir SoftwareApplication'ı sardığı yapıyı seçti:

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

operatingSystem'e chain adı, identifier'e adres, additionalType'a sınıflandırma (örn. "Uniswap V3 Pool"). schema.org'da adanmış SmartContract tipi yok, ama SoftwareApplication + bu alanlar LLM'in "Ethereum'da çalışan, belirli adresi olan bir kontrat" olduğunu anlaması için yeterli.

OG görseli 1200×630 summary_large_image; Twitter Card, breadcrumb, softwareVersion, license alanları da tamamlandı.

Tüm bunlar ne kadar iş

Yukarıdaki altı madde, dört gündeki yedi PR'dan çıktı:

PR	Dosya	Boyut
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	—	—

Her biri kendi testleri ve commit mesajlarıyla bağımsız bir PR. Bu kadar ince doğrama ritmi Claude'la çalışmanın en değerli yanı — her PR bir bakışta diff'i gözden geçirecek kadar küçük, ama üst üste konduğunda site tam bir AI yüzeyi çıkardı.

Kopyala-yapıştır kontrol listesi

İçerik odaklı bir siten varsa ve AI-dostu yapmak istiyorsan, bu sırayla ilerle:

1. robots.txt'te ana AI crawler'larına açıkça Allow ver
2. /llms.txt yaz (damıtılmış bir menü)
3. Ana içerik sayfalarına bir .md varyantı ekle
4. MCP sunucusu işletiyorsan /.well-known/mcp.json yayımla
5. İçerik sayfalarına "AI'na bu sayfa hakkında sor" kartı koy
6. JSON-LD / OpenGraph'ı içerik türünle uyuşan schema.org tipleriyle doldur

İlk beşini çoğu SEO mühendisi söylemeyecek — geleneksel SEO playbook'unda yoklar. Ama benim dört günlük verilerime göre AI trafik eğrisi ile insan trafik eğrisi tamamen bağımsız iki seri. İkisine de hizmet etmek lazım.