جعل Claude يُحوّل موقع Rails إلى موقع مُهيأ لذكاء اصطناعي

خلال الأيام الأربعة الماضية، حوّلتُ أنا و Claude Code موقع smarts.md من موقع توثيق للعقود الذكية مبني للبشر إلى موقع مبني لوكلاء الذكاء الاصطناعي.

يبدوان كالشيء ذاته. ليسا كذلك. موقع مخصص للبشر يُحسَّن من أجل قابلية القراءة، والبحث، وسرعة التحميل. موقع مخصص لوكلاء الذكاء الاصطناعي عليه أن يجيب على أسئلة مختلفة:

• هل يستطيع زواحف الذكاء الاصطناعي (crawlers) الوصول إليك أصلاً، أم أن robots.txt الافتراضي يُقفل الباب في وجهها؟
• هل يستطيع الذكاء الاصطناعي تجاوز تصيير HTML والحصول على محتوى نظيف مباشرة؟
• هل يستطيع الذكاء الاصطناعي استدعاء أدواتك دون الحاجة إلى "قراءة التوثيق" أولاً؟
• هل كل صفحة تخبر الذكاء الاصطناعي بالضبط كيف يُشير إليها وكيف يستعلم منها؟

فيما يلي ستة أشياء طلبتُ من Claude بناءها. كل منها مفيد بمفرده، ويمكنك نقل كل واحد منها إلى موقعك الخاص باستقلالية.

1. رحّب صراحةً بزواحف الذكاء الاصطناعي في robots.txt

تَرِث معظم المواقع ملف robots.txt من قالب قديم يمنع ضمنياً أي User-Agent لا يعرفه. لكن بعد 2025 أصبحت كثير من زواحف الذكاء الاصطناعي User-Agents جديدة — GPTBot و ClaudeBot و PerplexityBot و Applebot-Extended و Google-Extended و CCBot و meta-externalagent وغيرها. إن أردت أن تدخل، عليك أن تسمح لها صراحةً.

يبدأ robots.txt في smarts بملاحظة سياسية، ثم يسرد User-agent + Allow: / لـ 12 زاحفاً تغطي OpenAI و Anthropic و Perplexity و Google Gemini و Apple و Common Crawl و Meta و Cohere. الموقف صريح: هذا الموقع موجود ليُقرأ من قِبل الذكاء الاصطناعي.

2. llms.txt — قائمة للنماذج اللغوية الكبيرة

llms.txt عُرف يقترحه llmstxt.org: تضع ملف Markdown مختصر في جذر الموقع يخبر النموذج اللغوي ما هو هذا الموقع، وكيف يُستخدم، وأين نقاط الدخول الأساسية. إنه المقدمة الخاطفة لموقعك.

ملف llms.txt في smarts نحو 60 سطراً ويحتوي:

• جملة تموضع (Live docs for every verified smart contract)
• كيف يُستخدم من وكيل ذكاء اصطناعي (نقطة نهاية MCP، أمر إعداد من سطر واحد)
• أنماط URL (/{chain}/{address} مقابل slug قصير)
• قائمة أدوات MCP مع أوصاف من جملة
• قائمة عقود منتقاة (تمنح النموذج "إجابات افتراضية")
• النطاق والحدود (أي السلاسل غير مدعومة، سياسة التخزين المؤقت)

الفكرة الجوهرية: تدفع النماذج اللغوية بالتوكن لقراءة توثيقك، ولذلك لن تزحف الموقع بكامله. أعطِها فهرساً مُقطَّراً ويرتفع معدل الإصابة بشكل ملحوظ.

3. .well-known/mcp.json — رِهان مُبكّر

لم يُعيِّر بروتوكول MCP بعد عُرفاً لاكتشاف تلقائي على شاكلة /.well-known/openid-configuration. لا يوجد اليوم أي عميل عام يزحف إلى مسار well-known ثابت.

لكن نشر هذا الـ manifest يكلّف 30 سطراً:

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

حين يظهر عُرف اكتشاف، لن أُعدّل سطراً واحداً. وبالإضافة إلى ذلك فهو توثيق ذاتي للمطورين — من يريد أن يرى شكل MCP الخاص بي، يكفيه curl smarts.md/.well-known/mcp.json.

المفتاح: مصفوفة tools مشتقة من ثابت MCP_TOOLS، مصدر وحيد للحقيقة. اختبار هيكلي قائم يُلزم أن يظهر كل app/tools/*_tool.rb في ذلك الثابت، وبذلك يرث الـ manifest ضمان "عدم نسيان أدوات جديدة" مجاناً.

4. نسخة .md: تقطير ملائم لـ WebFetch لكل صفحة

هذه المفضلة عندي. يُضطر WebFetch في Claude Code إلى تنظيف HTML اعتباطي واستخراج المحتوى منه — وهذا مكلف بالتوكن وغير موثوق. ماذا لو أعطيته .md مباشرة؟

يدعم respond_to في Rails هذا بشكل أصلي:

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

يُعيد https://smarts.md/usdc-eth ملف HTML؛ ويُعيد https://smarts.md/usdc-eth.md أربعين سطراً من Markdown — العنوان، السلسلة، التصنيف، نقطة نهاية MCP، كيفية الاستعلام عبر وكيل ذكاء اصطناعي، روابط المصدر.

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

جلب واحد، وكل المحتوى المهيكل الذي يحتاجه وكيل الذكاء الاصطناعي موجود، دون حاجة إلى محلل DOM. أنجز Claude هذا بسرعة — controller واحد، قالبان .md.erb، إضافة (.:format) في routes، انتهى.

5. بطاقة MCP على كل صفحة: دع المستخدمين يُوجّهون ذكاءهم الاصطناعي هنا

هذه اكتشاف في الاتجاه المعاكس: جزء من زوار موقعي يستخدمون أصلاً Claude Code أو Cursor أو Windsurf. يصلون إلى صفحة عقد، والخطوة التالية عادةً "دع ذكائي الاصطناعي يُلقي نظرة على هذا".

لذلك تَعرض كل صفحة عقد بطاقة بما يلي:

• Reference: الـ slug المنتقى (مثل usdc-eth) أو chain/address، مع زر نسخ
• Sample prompt: "Tell me the current state of usdc-eth"، مع زر نسخ
• لم يُربط الذكاء الاصطناعي بعد؟: مؤشر إلى mcp.smarts.md (إعداد من سطر واحد)

نقرة واحدة من الاحتكاك بين "أنا أنظر إلى هذا العقد" و "أنا أسأل ذكائي الاصطناعي". تستخدم البطاقة card من DaisyUI و Stimulus controller copy عاماً — 50 سطر erb. يُثبّت اختبار انحدار سمات data-copy-text-value حتى لا يُلصق refactor مستقبلي نصاً خاطئاً في حافظة المستخدمين صمتاً.

6. SEO تقليدي، لكن مع استخدام schema.org بشكل صحيح

OpenGraph و Twitter Card و JSON-LD — طبقة البحث والبطاقات الاجتماعية التقليدية. تستحق العمل، لأن زواحف الذكاء الاصطناعي تقرأها هي الأخرى.

الاختيار المثير للاهتمام هو كيف ينبغي لـ JSON-LD أن يصف عقداً ذكياً. اختار Claude هيكلاً يضع SoftwareApplication داخل WebPage:

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

يحصل operatingSystem على اسم السلسلة، و identifier على العنوان، و additionalType على التصنيف (مثل "Uniswap V3 Pool"). لا يوجد في schema.org نوع مُخصّص SmartContract، ولكن SoftwareApplication مع هذه الحقول كافٍ ليفهم النموذج اللغوي أن "هذا عقد يعمل على Ethereum بعنوان محدد".

صورة OG هي summary_large_image بأبعاد 1200×630؛ وتُكمِل الحزمةَ Twitter Card وفتات الخبز و softwareVersion و license.

كم يكلف كل هذا من عمل

خرجت البنود الستة أعلاه من سبعة PR خلال أربعة أيام:

PR	ملفات	الحجم
feat/ai-crawler-discovery	2	~126 سطر
feat/well-known-mcp-manifest	4	~129 سطر
feat/markdown-contract-pages	6	~298 سطر
feat/contract-mcp-card	3	~126 سطر
feat/seo-meta-tags	8	~292 سطر
feat/seo-enrichments	8	~189 سطر
feat/og-card	—	—

كل واحد منها PR مستقل باختباراته ورسالة commit الخاصة به. هذا الإيقاع في التقطيع الدقيق هو أثمن ما في العمل مع Claude — كل PR صغير بما يكفي لمراجعة diff بنظرة واحدة، لكن عند جمعها نما في الموقع سطح كامل للذكاء الاصطناعي.

قائمة جاهزة للنسخ

إن كان لديك موقع محوره المحتوى وتريده ملائماً للذكاء الاصطناعي، نفّذ ما يلي بالترتيب:

1. اسمح صراحةً لأهم زواحف الذكاء الاصطناعي في robots.txt
2. اكتب /llms.txt (قائمة مُقطَّرة)
3. أضِف نسخة .md لصفحات المحتوى الأساسية
4. إن كنت تُشغِّل خادم MCP، انشر /.well-known/mcp.json
5. ضع بطاقة "اسأل ذكاءك الاصطناعي عن هذه الصفحة" في صفحات المحتوى
6. املأ JSON-LD / OpenGraph بأنواع schema.org الموافقة لنوع محتواك

لن يخبرك أغلب مهندسي SEO بالخمسة الأولى — فهي ليست ضمن playbook تقليدي. لكن من بيانات أربعة أيام على جانبي، منحنى حركة الذكاء الاصطناعي ومنحنى حركة البشر سلسلتان مستقلتان تماماً. عليك أن تخدم الاثنتين.