دليل المطورين الشامل للمبتدئين: كود كلود، شفرات وأساسيات

إذا كنت تتعمق في كود كلود (Claude Code)، مساعد البرمجة القوي المدعوم بالذكاء الاصطناعي من Anthropic، فإن وجود مرجع واضح أمر ضروري. تهدف ورقة الغش هذه لكود كلود (Claude Code Cheatsheet) إلى تزويد المطورين بدليل عملي وسهل للمبتدئين يغطي الإعداد وسير العمل والتكوين والنصائح المتقدمة. بنهاية هذا الدليل، ستشعر بثقة أكبر عند استخدام كود كلود في بيئتك المحلية أو كجزء من عمليات CI/CD الخاصة بك.

ما هو كود كلود (Claude Code)؟

كود كلود (Claude Code) هو أداة برمجة تعتمد على واجهة سطر الأوامر (CLI) ومدعومة بالذكاء الاصطناعي من Anthropic. تتيح للمطورين إنشاء التعليمات البرمجية وإعادة هيكلتها واختبارها وتوثيقها باستخدام نماذج كلود المتقدمة. بدلاً من واجهة دردشة بسيطة، يتصرف كود كلود كمحرر متكامل للتطوير (AI IDE) يعمل بالذكاء الاصطناعي: فهو يفهم بنية المستودع الخاص بك، ويطبق الضوابط الوقائية (guardrails) المحددة في ملفات التكوين، ويمكنه تشغيل أوامر باش (bash)، ويتكامل مع سير عمل Git.

تثبيت كود كلود (Claude Code):

# MacOS/Linux:
curl -fsSL https://claude.ai/install.sh | bash

# Windows:
irm https://claude.ai/install.ps1 | iex

# NPM:
npm install -g @anthropic-ai/claude-code

# Homebrew:
brew install --cask claude-code

ابدأ استخدام كود كلود (Claude Code):

cd your-project
claude

المكونات الأساسية لكود كلود (Claude Code) — ورقة الغش الخاصة بك

فيما يلي اللبنات والميزات الأساسية التي سترغب في معرفتها عند البدء باستخدام كود كلود (Claude Code):

1. CLAUDE.md — بيان الوكيل (Agent Manifest)

• ملف CLAUDE.md هو "دستور" وكيلك: فهو يحدد كيفية تصرف كلود في مستودعك.
• استخدمه لتوثيق الأدوات المعتمدة وسير العمل الشائعة والقيود.
• أفضل الممارسات: اجعله قصيرًا، وركز على الضوابط الوقائية الرئيسية، وتجنب تضمين وثائق كبيرة جدًا.

# MyProject CLAUDE.md

## Project Overview  
This is a Node.js + Express REST API for a task management application.  

## Technology Stack  
- Backend: Node.js (ES6), Express  
- Database: PostgreSQL  
- Testing: Jest  
- Linting & Style: ESLint, Prettier

## Development Commands  
- `npm install` — Install dependencies  
- `npm run dev` — Start development server  
- `npm run test` — Run all tests  
- `npm run lint` — Run linter  

## Coding Standards  
- Use 2-space indentation.  
- Always use `async / await` instead of `.then()` chains.  
- Functions must have JSDoc comments.  
- Prefer composition over inheritance.

## Git Workflow  
- Feature branches must follow this pattern: `feature/FOO`  
- Use `git rebase` instead of `merge` for updating branches.  
- When committing: write descriptive commit messages that follow the Conventional Commits format.

## File Structure Guidance  
- `src/` — Your main application code  
- `tests/` — Test files  
- `scripts/` — Utility or setup scripts  
- `migrations/` — Database migrations  

## Known Issues / Workarounds  
- `db.connect()` sometimes times out; in that case, retry twice.  
- For large JSON payloads, use streaming to avoid memory issues.

## Memory / Style Preferences  
- Always ask for clarification if the request is ambiguous.  
- Do not generate new `.md` files unless explicitly instructed.  
- Include a `co-authored-by Claude` line in generated commits.

2. إدارة السياق (Context Management)

أ. استخدم **/context** لفحص استخدام الرموز (tokens) لجلسة كلود الحالية.

ب. أوامر لإعادة تشغيل أو تقليص السياق:

• /clear + /catchup: يمسح جميع المحادثات ثم يعيد تحميل الملفات من التزام (commit) أو فرع (branch).
• سير عمل "توثيق ومسح" (Document & Clear): اجعل كلود يفرغ خطته في ملف Markdown، يمسح الذاكرة، ثم يعيد التحميل من ذلك الملف.

3. أوامر الشرطة المائلة (Slash Commands)

• أوامر الشرطة المائلة هي اختصارات لأوامر مسبقة التعريف.
• أمثلة:

• اجعل أوامر الشرطة المائلة بسيطة ومركزة؛ لا تعتمد عليها لكل مهمة.

4. وضع التخطيط (Plan Mode)

• استخدم وضع التخطيط عند بدء مهام معقدة. سيقوم كلود بتحديد خطة قبل كتابة التعليمات البرمجية.
• يمكنك بعد ذلك مراجعة هذه الخطة أو تعديلها أو الموافقة عليها قبل أن تطلب من كلود تنفيذها.
• مثالي لعمل الميزات الكبيرة، إعادة الهيكلة، أو التغييرات المعمارية.

5. الوكلاء الفرعيون (Subagents) وتفويض المهام

• يدعم كود كلود (Claude Code) **الوكلاء الفرعيين (subagents)**، مما يتيح لك تفويض أجزاء من العمل إلى "نسخ" من الوكيل الرئيسي.
• يفضل Shrivu بنية "الرئيس-النسخة" (Master-Clone): حيث يقوم الوكيل الرئيسي بإنشاء نسخ عبر `Task(...)`، بدلاً من استخدام وكلاء فرعيين متخصصين جامدين.
• يحافظ هذا على المرونة مع تجنب تفتيت السياق.
• قم بالوصول إلى الوكلاء الفرعيين في كود كلود باستخدام أمر الشرطة المائلة: `/agents`.

6. مهارات كلود (Claude Skills) مقابل بروتوكول سياق النموذج (MCP) — ما الفرق؟

أ. **مهارات كلود (Claude Skills)** هي "وحدات" مبنية مسبقًا تعلم كلود كيفية أداء مهام محددة. وهي مكتوبة بلغة Markdown أو التعليمات البرمجية، ويتم تحميلها فقط عند الحاجة. يمكنك استخدام المهارات لتعريف سير العمل مثل تنسيق التقارير أو تلخيص البيانات أو فرض أسلوب فريقك.

ب. **بروتوكول سياق النموذج (MCP)**، من ناحية أخرى، هو بروتوكول لربط كلود بالبيانات والأدوات الخارجية — مثل قواعد البيانات، أو قاعدة التعليمات البرمجية الخاصة بك، أو أنظمة الأعمال. إنه بمثابة "محول عالمي" يتيح لكلود الوصول إلى الموارد الخارجية والتصرف بناءً عليها دون الحاجة إلى عمليات دمج مخصصة لكل أداة.

ج. الفروق الرئيسية:

• 1. الغرض:
• المهارات (Skills) تشفر المعرفة الإجرائية.
• بروتوكول سياق النموذج (MCP) يتعامل مع اتصال الأدوات والبيانات.
• 2. كفاءة الرموز (Tokens):
• يتم تحميل المهارات فقط عند الحاجة، باستخدام عدد قليل نسبيًا من الرموز.
• يمكن أن تستهلك تعريفات أدوات بروتوكول سياق النموذج (MCP) مساحة كبيرة من الرموز إذا تم تمكين العديد منها.

د. حالة الاستخدام:

• استخدم **المهارات (Skills)** لتعليم كلود سير عمل خاص بالمجال (على سبيل المثال، "عند كتابة تقارير الحالة، قم دائمًا بتضمين X، Y، Z").
• استخدم **بروتوكول سياق النموذج (MCP)** عندما يحتاج كلود إلى قراءة/كتابة البيانات، أو استدعاء واجهات برمجة التطبيقات (APIs)، أو الوصول إلى أنظمة خارجية مثل Git أو قاعدة بيانات.

عمليًا، يعمل الاثنان معًا على أفضل وجه: يمنح **بروتوكول سياق النموذج (MCP)** كلود إمكانية الوصول إلى بياناتك، وتُعلم **المهارات (Skills)** كلود كيفية استخدام تلك البيانات بطريقة منظمة وقابلة للتكرار.

6. الخطاطيف (Hooks)

أ. الخطاطيف (Hooks) هي طريقتك لفرض القواعد تلقائيًا.

ب. نوعان شائعان:

• الحظر عند الإرسال (Block-at-submit): على سبيل المثال، يمكن لخطاف `PreToolUse` حظر `git commit` ما لم تكن الاختبارات قد اجتازت.
• خطاطيف التلميح (Hint hooks): غير حاجزة؛ توفر توجيهات أو اقتراحات دون إيقاف التنفيذ.

ج. تجنب خطاطيف "الحظر عند الكتابة" (block-at-write) — فالسماح لكلود بإكمال خطته ثم التحقق منها أكثر استقرارًا.

# Example Hook in .claude/settings.toml

[[hooks]]
# The event that triggers the hook.
event = "PostToolUse" 

# (Optional) Conditions for the hook to run.
[hooks.matcher]
tool_name = "edit_file"
file_paths = ["*.py", "api/**/*.py"]

# The shell command to execute.
command = "ruff check --fix $CLAUDE_FILE_PATHS && black $CLAUDE_FILE_PATHS"

# (Optional) Whether to run the command in the background.
run_in_background = false 

7. حزمة تطوير البرمجيات الخاصة بواجهة سطر الأوامر (CLI SDK)

• تُمكّنك **حزمة تطوير البرمجيات الخاصة بكود كلود (Claude Code SDK)** من برمجة تفاعلات كلود: مفيدة للمعالجة الدفعية، بناء الأدوات الداخلية، أو إنشاء نماذج أولية للوكلاء.
• استخدمها لتشغيل عمليات إعادة هيكلة متوازية، أو لإنشاء تعليمات برمجية من القوالب، أو كوكيل خفيف الوزن ضمن سير عمل CI/CD.

التثبيت:

# Typescript:
npm install @anthropic-ai/claude-agent-sdk

# Python:
pip install claude-agent-sdk

8. إجراءات GitHub لكود كلود (Claude Code GitHub Actions - GHA)

• يمكنك دمج كود كلود (Claude Code) مباشرةً في إجراءات GitHub (GitHub Actions).
• استخدمها لإنشاء طلبات السحب تلقائيًا، أو فرض معايير التعليمات البرمجية، أو تشغيل الفحوصات المدفوعة بملف CLAUDE.md كجزء من خط أنابيب CI الخاص بك.
• نظرًا لتخزين السجلات، يمكنك تدقيق سلوك الوكيل وتحسين ملف CLAUDE.md الخاص بك بمرور الوقت.

9. الإعدادات والتكوين (Settings & Configuration)

أ. في ملف `settings.json`، يمكنك تكوين ما يلي:

• الوكيل (Proxy) (`HTTPS_PROXY`) — مفيد لتصحيح أخطاء حركة مرور واجهة سطر الأوامر (CLI).
• المهلات (Timeouts) (`MCP_TOOL_TIMEOUT`, `BASH_MAX_TIMEOUT_MS`) — قم بزيادتها إذا كنت تشغل مهامًا طويلة.
• مفتاح API (`ANTHROPIC_API_KEY`) — استخدم مفتاحك من Anthropic أو نصًا برمجيًا مساعدًا.
• الأذونات (Permissions) — تتحكم في أدوات النظام التي يُسمح لكود كلود بتنفيذها.

{
  "permissions": {
    "allow": [
      "Bash(npm run lint)",
      "Bash(npm run test:*)",
      "Read(~/.zshrc)"
    ],
    "deny": [
      "Bash(curl:*)",
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)"
    ]
  },
  "env": {
    "CLAUDE_CODE_ENABLE_TELEMETRY": "1",
    "OTEL_METRICS_EXPORTER": "otlp"
  },
  "companyAnnouncements": [
    "Welcome to Acme Corp! Review our code guidelines at docs.acme.com",
    "Reminder: Code reviews required for all PRs",
    "New security policy in effect"
  ]
}

الميزات المتقدمة ونصائح الإنتاجية

1. تبديل النماذج (Model Switching): اختر Claude 4 Sonnet أو Opus حسب مهمتك. Sonnet سريع وفعال من حيث التكلفة؛ Opus أكثر قدرة على التعامل مع التغييرات المعقدة والمتعددة الملفات.
2. أوضاع التفكير (Thinking Modes) (خدعة): يقوم بعض المستخدمين بتعديل وضع تفكير كلود إلى `think`، `think hard`، `think harder`، أو `ultrathink` لضبط عمق تفكيره.
3. الأوامر المخصصة (Custom Commands): حدد أوامر الشرطة المائلة القابلة لإعادة الاستخدام في `.claude/commands` مع عناصر نائبة ديناميكية (`$argument`). رائعة للاختبار أو البناء أو المراجعة.
4. سجل الجلسات (Session History): استخدم `claude --resume` أو `claude --continue` لاستئناف الجلسات القديمة. يخزن كلود جميع سجلات الجلسات محليًا.
5. حلقة التغذية الراجعة (Feedback Loop): راجع سلوك الوكيل عبر سجلات GitHub Action أو بيانات الجلسة التاريخية وقم بتحديث ملف `CLAUDE.md` الخاص بك لتصحيح سوء الفهم أو فرض ضوابط وقائية أفضل.

الأسئلة المتكررة (FAQ)

س1. ما هو الغرض من `CLAUDE.md`؟
ج: يعمل `CLAUDE.md` كبيان للوكيل. يحدد القواعد والأدوات والتقاليد التي يجب أن يتبعها كود كلود. يساعد على توحيد السلوك عبر مستودعك.

س2. هل يجب أن أستخدم الوكلاء الفرعيين أم المهام البسيطة فقط؟
ج: استخدم الوكلاء الفرعيين إذا كنت ترغب في سير عمل وحدات صارمة. لكن الكثيرين يجدون نمط **الرئيس-النسخة (Master-Clone)** (باستخدام `Task(...)`) أكثر مرونة — فأنت تحافظ على السياق أثناء تفويض المهام الفرعية.

س3. كيف أعيد تشغيل جلسة كلود دون فقدان كل شيء؟
ج: استخدم `/clear` لإعادة تعيين الدردشة، ثم `/catchup` لتحميل الملفات من فرع Git الخاص بك حتى يكون لدى كلود السياق الكامل مرة أخرى.

س4. ما هي الخطاطيف (hooks)، ولماذا أحتاجها؟
ج: تفرض الخطاطيف القواعد أو الفحوصات عندما يقوم كلود بإتمام العمل. على سبيل المثال، يمكن لخطاف "الحظر عند الإرسال" (block-at-submit) أن يضمن اجتياز الاختبارات قبل السماح بتنفيذ Git commit.

س5. كيف يمكنني دمج كود كلود في CI/CD؟
ج: استخدم إجراء GitHub لكود كلود (Claude Code GitHub Action) لتشغيل المهام، والتحقق من التعليمات البرمجية، وإنشاء طلبات السحب، أو فرض ضوابط CLAUDE.md الوقائية الخاصة بك في خطوط الأنابيب المؤتمتة.

الخاتمة

توفر لك **ورقة الغش هذه لكود كلود (Claude Code Cheatsheet)** نظرة عامة عملية ومنظمة حول كيفية استخدام كود كلود بفعالية. بدءًا من كتابة ملف `CLAUDE.md` مصمم جيدًا إلى الاستفادة من أوامر الشرطة المائلة (slash commands)، والوكلاء الفرعيين (subagents)، والخطاطيف (hooks)، وتكامل CI — تشكل هذه الأنماط أساسًا متينًا لاستخدام كود كلود كشريك تطوير موثوق به ومدعوم بالذكاء الاصطناعي.

من خلال إتقان هذه الميزات، يمكن للمطورين الجدد البدء بالعمل بسرعة، ويمكن للمهندسين الأكثر خبرة تبسيط سير عملهم، وفرض الضوابط الوقائية، وتوسيع نطاق الإنتاجية بمساعدة كلود. كود كلود هو أكثر من مجرد أداة لتوليد التعليمات البرمجية — إنه نظام قابل للبرمجة وذاتي التصرف يتكيف مع احتياجات فريقك.