كيفية استخدام مهارات Claude Code لإنشاء الوثائق

إذا سبق لك أن ورثت وثائق غير مكتملة أو غير متناسقة أو قديمة، فأنت تعرف المشكلة: تنشئ الفرق وثائق بنوايا حسنة، ولكن بدون مراجعة دقيقة، تتلاشى الوضوح. تبقى معلمات واجهة برمجة التطبيقات (API) غير موثقة. تفتقر استجابات الأخطاء إلى التوجيه. تتعطل الأمثلة بصمت. تتغير المصطلحات عبر الملفات.

💡

هل تُبطئك الوثائق الفنية؟ ادمج Claude Code مع Apidog لتغطية توثيق كاملة ومراجعة نصية مدعومة بالذكاء الاصطناعي + التحقق المرئي من واجهة برمجة التطبيقات. جربهما مجانًا: claude.ai و apidog.com. وثّق بذكاء أكبر.

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

تمتد الوثائق الفنية لتشمل مواصفات واجهة برمجة التطبيقات، وأدلة المستخدم، وأدلة النشر، وملاحظات الإصدار. يقوم Claude Code بأتمتة مراجعة كل ذلك. وبالنسبة لتوثيق واجهة برمجة التطبيقات على وجه التحديد، ادمجه مع Apidog للتحقق المرئي وقياس الاكتمال.

فهم مهارات Claude Code للتوثيق

ما هي مهارات التوثيق؟

مهارات Claude Code هي مهام آلية مخصصة وقابلة لإعادة الاستخدام ومدعومة بالذكاء الاصطناعي توسع قدرات توثيق Claude Code. فكر فيها كمدققي توثيق أذكياء يمكنهم:

قراءة مستودع التوثيق بأكمله وفهم السياق
مقارنة المواصفات بالتطبيقات والأدلة
تحديد الأقسام المفقودة، واللغة غير الواضحة، والتناقضات
اقتراح تحسينات محددة مع مواقع الملفات وأرقام الأسطر
تطبيق الإصلاحات مباشرة على ملفاتك والتحقق من التغييرات

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

كيف تعمل المهارات

تعمل المهارات من خلال عدة آليات:

1. أوامر قابلة للاستدعاء من قبل المستخدم

# تشغيل مهارة بأمر شرطة مائلة
/review-docs --completeness
/check-consistency --terminology
/validate-api-specs
/update-broken-examples

2. الأدوات المسموح بها

تحدد المهارات الأدوات التي يمكنها استخدامها:

Bash: تشغيل أوامر التحقق
Read, Write, Edit: إدارة ملفات التوثيق
Glob, Grep: البحث عبر الوثائق
WebFetch: استرداد المراجع الخارجية
Task: إنشاء مهام فرعية للمراجعات المعقدة

3. ملفات التخطيط

تحافظ المهارات على الحالة باستخدام ملفات Markdown لتتبع تقدم المراجعة، والمشكلات المحددة، والإصلاحات المطبقة.

لماذا تتفوق المهارات في مراجعة الوثائق

مراجعة الوثائق التقليدية يدوية وغير متناسقة. تجلب المهارات الذكاء والنطاق:

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

قدرات مراجعة التوثيق الأساسية

1. تحليل الاكتمال

التعليمات: "راجع توثيق واجهة برمجة التطبيقات من حيث الاكتمال. تحقق من كل نقطة نهاية لـ: المعلمات، أمثلة الطلبات، جميع استجابات الأخطاء، وحدود المعدل."

ينشئ Claude:

مفقود من نقطة النهاية POST /users:
- [ ] أوصاف معلمات جسم الطلب
- [ ] توثيق استجابة الخطأ (400, 401, 409)
- [ ] معلومات حدود المعدل
- [ ] متطلبات الأمان/المصادقة

2. اكتشاف الاتساق

التعليمات: "راجع /docs/ لاتساق المصطلحات. ضع علامة على أي مصطلحات تظهر عدة مرات بمعاني مختلفة."

يحدد Claude:

تم العثور على مصطلحات غير متناسقة:
- "مفتاح API" مقابل "رمز الوصول" مقابل "رمز المصادقة" (استخدم واحدًا)
- "نقطة نهاية" مقابل "مسار" مقابل "طريقة" (استخدم واحدًا)
- "كائن مستخدم" مقابل "مصدر مستخدم" (استخدم واحدًا)

3. التحقق من المراجع المتقاطعة

التعليمات: "قارن مواصفات OpenAPI في /api/openapi.yaml بالوثائق في /docs/api/. ضع علامة على أي نقاط نهاية في الكود غير موثقة أو موثقة ولكنها ليست في الكود."

يكتشف Claude:

تم العثور على تناقضات:
- POST /api/webhooks موثق ولكن ليس في openapi.yaml
- PATCH /api/users موجود في الكود ولكنه مفقود من الوثائق
- تغير مخطط الاستجابة ولكن المثال لم يتم تحديثه

4. تقييم الوضوح

التعليمات: "راجع للوضوح. ضع علامة على الأوصاف المبهمة، والمصطلحات غير المعرفة، والتعليمات الغامضة."

يحدد Claude:

مشكلات الوضوح:
- السطر 45: "اضبط التكوين على القيم المناسبة" - ما هي القيم؟
- السطر 120: "كائن المستخدم" مستخدم بدون تعريف مخطط
- السطر 200: "الحقول المطلوبة" - أي منها؟

5. التحقق من الأمثلة

التعليمات: "راجع جميع أمثلة التعليمات البرمجية. اختبرها مقابل مخطط API الحالي. ضع علامة على الأمثلة المعطلة أو القديمة."

يقوم Claude بتحديث:

أمثلة محدثة:
- مثال curl: تغير تنسيق الاستجابة، تم تحديث الحمولة
- مثال Python: يستخدم معلمة مهملة، تم الإصلاح
- مثال JavaScript: معالجة الأخطاء مفقودة، تم إضافتها

تشريح مهارة التوثيق

هيكل الدليل

تعيش مهارات التوثيق في .claude/skills/ بهذا الترتيب:

.claude/
├── skills/
│   ├── docs-completeness/
│   │   ├── SKILL.md              # بيان المهارة
│   │   ├── planning.md           # تقدم المراجعة
│   │   └── criteria.md           # قائمة التحقق من الجودة
│   ├── api-validation/
│   │   ├── SKILL.md
│   │   └── schemas/              # مخططات API
│   └── consistency-check/
│       └── SKILL.md
└── skills.md                     # فهرس جميع المهارات

بيان SKILL.md

تبدأ كل مهارة توثيق بمقدمة YAML:

---
name: docs-completeness
version: "1.0.0"
description: مراجعة الوثائق من أجل الاكتمال والوضوح
user-invocable: true
allowed-tools:
  - Read
  - Write
  - Grep
  - Glob
  - Edit
hooks:
  SessionStart:
    - matcher: command
      command: "echo '[Docs Review] بدء تدقيق الوثائق...'"
  Stop:
    - matcher: command
      command: "echo '[Docs Review] التدقيق مكتمل. راجع النتائج أعلاه.'"
---

# مهارة اكتمال الوثائق

تراجع الوثائق الفنية من أجل الاكتمال والوضوح.

## الاستخدام

```bash
/docs-completeness                # تدقيق المستودع بالكامل
/docs-completeness --api-only    # وثائق API فقط
/docs-completeness --section api/endpoints.md  # ملف محدد

تعليمات لـ Claude

عند الاستدعاء:

اكتشاف النطاق ← تحديد الملفات المستهدفة أو المستودع بالكامل
تحليل الاكتمال ← التحقق من كل قسم مقابل قائمة التحقق
جمع المشكلات ← جمع جميع المشكلات مع المواقع
التحديد بالأولوية ← الفرز حسب التأثير (مفقود مقابل غير واضح مقابل غير متناسق)
إنشاء تقرير ← إخراج النتائج المهيكلة
اقتراحات الإصلاح ← تقديم تحسينات محددة
التحقق ← التحقق من الإصلاحات قبل تطبيقها

صياغة أول مهارة توثيق خاصة بك

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

الخطوة 1: إعداد مجلد المهارة

ابدأ الهيكل بأمر بسيط. تعيش مهارات Claude في مكان مخصص لسهولة الاكتشاف.

Bash

mkdir -p .claude/skills/api-docs-review

الخطوة 2: كتابة بيان المهارة

أنشئ .claude/skills/api-docs-review/SKILL.md:

---
name: api-docs-review
version: "1.0.0"
description: مراجعة وثائق API من أجل الاكتمال
user-invocable: true
allowed-tools:
  - Read
  - Write
  - Grep
  - Edit
---

# مهارة مراجعة وثائق API

تدقق وثائق API من أجل الاكتمال، الوضوح، والدقة.

## معايير المراجعة

يجب أن تحتوي كل نقطة نهاية على:

**معلومات أساسية**
* وصف واضح لما تفعله نقطة النهاية
* طريقة HTTP والمسار
* متطلبات المصادقة

**توثيق الطلب**
* جميع معلمات المسار مع أنواعها وأوصافها
* جميع معلمات الاستعلام مع القيم الافتراضية والقيود
* مخطط جسم الطلب (لـ POST/PUT/PATCH)
* متطلبات رأس Content-Type
* مثال على الطلب (curl أو خاص باللغة)

**توثيق الاستجابة**
* استجابة النجاح (200/201) مع المخطط والمثال
* جميع استجابات الأخطاء (400, 401, 403, 404, 409, 429, 500) مع الأمثلة
* معلومات حدود المعدل
* رؤوس الاستجابة (إذا كانت ذات صلة)

**إضافي**
* نقاط النهاية أو الأدلة ذات الصلة
* سجل الإصدارات إن أمكن
* تحذيرات الإهمال (إذا كانت مهملة)

## التعليمات

عند الاستدعاء:

1. **مسح ملفات نقطة النهاية** في /docs/api/
2. **التحقق من كل نقطة نهاية** مقابل معايير المراجعة
3. **تسجيل العناصر المفقودة** مع إشارات الملف/السطر المحددة
4. **تحديد مشكلات الوضوح** (أوصاف مبهمة، مصطلحات غير معرفة)
5. **وضع علامة على مشكلات الاتساق** (انحراف المصطلحات، اختلافات التنسيق)
6. **إنشاء قائمة تحقق** بالإصلاحات المطلوبة
7. **عرض تطبيق الإصلاحات** مع الأمثلة

تنسيق التقرير:

نقطة النهاية: POST /api/users الملف: docs/api/users.md الحالة: 65% مكتمل

مفقود:

[ ] توثيق استجابة الخطأ (400، 401، 409)
[ ] معلومات تحديد المعدل
[ ] تعريف مخطط جسم الطلب

مشكلات:

السطر 45: "كائن المستخدم" غير معرف - أضف رابطًا إلى المخطط
السطر 60: المثال قديم - تغير تنسيق الاستجابة

الإصلاحات المتاحة: نعم (اطلب تطبيقها)

الخطوة 3: تسجيل المهارة

أضف إلى .claude/skills.md:

# مهارات التوثيق المتاحة

## توثيق API

### /api-docs-review
تدقيق وثائق API من أجل الاكتمال مقابل المعايير القياسية.
- **الإصدار**: 1.0.0
- **الاستخدام**: `/api-docs-review [--file PATH] [--endpoint NAME]`
- **متى تستخدم**: قبل إصدار API، بعد تغييرات الكود
- **الوقت**: 5-10 دقائق لواجهة برمجة تطبيقات متوسطة الحجم

الخطوة 4: اختبار المهارة

# في Claude Code
/api-docs-review

سيقوم Claude الآن بتدقيق وثائق API الخاصة بك بشكل منهجي.

أنماط التوثيق المتقدمة

النمط 1: تتبع الوثائق المحددة بالإصدار

يمكن للمهارات تتبع جودة الوثائق عبر الإصدارات:

## سجل الإصدارات

### v2.0.0 [2026-01-22]
الاكتمال: 95% ✅
- جميع نقاط النهاية موثقة
- استجابات الأخطاء كاملة
- الأمثلة محدثة
- نقاط نهاية /v1 المهملة معلمة

### v1.0.0 [2025-12-01]
الاكتمال: 70%
- توثيق أخطاء مفقود
- أمثلة قديمة
- لا توجد تحذيرات إهمال

يكتشف Claude التحسينات بمرور الوقت.

النمط 2: التحقق من مواصفات API مقابل الكود

يمكن للمهارات التحقق من توافق مواصفات OpenAPI مع التنفيذ:

## التحقق من المواصفات

قارن /api/openapi.yaml بالكود:

1. **مسح التنفيذ** لجميع المسارات
2. **التحقق من مواصفات OpenAPI** لكل مسار
3. **وضع علامة على نقاط النهاية المفقودة**
4. **التحقق من تطابق المعلمات** مع التنفيذ
5. **تحديث الأمثلة** لتتطابق مع المخطط الحالي

النتيجة: المواصفات متزامنة بنسبة 100% مع الكود

الأتمتة باستخدام CI/CD

خط أنابيب التحقق من الوثائق

إعداد فحوصات آلية عند كل تحديث للوثائق:

# .github/workflows/docs-check.yml
name: فحص الوثائق

on:
  push:
    paths:
      - 'docs/**'
      - 'api/openapi.yaml'
  pull_request:
    paths:
      - 'docs/**'
      - 'api/openapi.yaml'

jobs:
  validate-docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'

      - name: تثبيت Apidog CLI
        run: npm install -g apidog-cli

      - name: التحقق من مواصفات OpenAPI
        run: |
          apidog lint api/openapi.yaml
          apidog check-completeness api/openapi.yaml --min-score 85

      - name: التحقق من الروابط المعطلة
        run: |
          npm install -g markdown-link-check
          find docs -name "*.md" -exec markdown-link-check {} \;

      - name: التحقق من صحة الأمثلة
        run: |
          # اختبار أمثلة curl تعمل
          bash scripts/test-curl-examples.sh

      - name: التعليق على طلب السحب
        if: failure()
        uses: actions/github-script@v7
        with:
          script: |
            github.rest.issues.createComment({
              issue_number: context.issue.number,
              owner: context.repo.owner,
              repo: context.repo.repo,
              body: '❌ فشل التحقق من الوثائق. راجع سجلات سير العمل.'
            })

سيناريو واقعي: اكتمال وثائق API

لنراجع مجموعة وثائق API واقعية من حيث الاكتمال ونطبق التحسينات.

السيناريو

لديك وثائق REST API عمرها 6 أشهر. إنها مكتملة جزئيًا ولكنها تفتقر إلى توثيق الأخطاء، وغير واضحة في بعض الأماكن، وتحتوي على أمثلة قديمة.

التدقيق

التعليمات لـ Claude: "راجع الوثائق في /docs/api/. لكل نقطة نهاية، تحقق من: الوصف، معلمات الطلب، مثال الاستجابة، وجميع استجابات الأخطاء. حدد أولويات الإصلاحات حسب التأثير."

نتائج التدقيق
=============

حرج (وثائق أخطاء مفقودة):
├── POST /api/users - استجابات أخطاء 400, 401, 409 مفقودة
├── POST /api/auth/login - استجابة 429 (حد المعدل) مفقودة
└── DELETE /api/resources/{id} - استجابة 403 (محظور) مفقودة

عالي (مشكلات وضوح):
├── users.md:45 - "كائن المستخدم" غير معرف
├── auth.md:60 - "اضبط مدة انتهاء الصلاحية على القيمة المناسبة" - غامض جدًا
└── resources.md:30 - وصف تنسيق مؤشر التصفح مفقود

متوسط (أمثلة قديمة):
├── products.md:120 - مثال cURL يعيد تنسيقًا قديمًا
├── orders.md:80 - مثال Python SDK يستخدم معلمة مهملة
└── webhooks.md:60 - مثال Node.js يفتقر إلى معالجة الأخطاء

اتساق:
├── "مفتاح API" مقابل "رمز الوصول" - 5 حالات غير متناسقة
├── تنسيق جسم الطلب - 3 أنماط مختلفة عبر نقاط النهاية
└── مخطط استجابة الخطأ - تباينان بدلاً من واحد

إصلاحات ذات أولوية: 15 إجمالاً
الجهد المقدر: 2-3 ساعات يدوية، 15 دقيقة مع Claude Code

التحسينات

تطبيق الإصلاحات بشكل منهجي:

قبل - POST /api/users (غير مكتمل):

## إنشاء مستخدم

POST /api/users

ينشئ مستخدمًا جديدًا.

**المعلمات:**
- name: اسم المستخدم
- email: بريد المستخدم الإلكتروني

**الاستجابة:**
```json
{
  "id": "usr_123",
  "name": "أليس",
  "email": "alice@example.com"
}


**بعد - POST /api/users (مكتمل):**
```markdown
## إنشاء مستخدم

`POST /api/users`

ينشئ حساب مستخدم جديد بالتفاصيل المقدمة. يجب أن يكون البريد الإلكتروني فريدًا.

### المصادقة

يتطلب مفتاح API في رأس `Authorization`: `Bearer YOUR_API_KEY`

### معلمات الطلب

| المعلمة | النوع | مطلوب | الوصف |
|-----------|------|----------|-------------|
| `name` | string | نعم | الاسم الكامل (2-100 حرف) |
| `email` | string | نعم | بريد إلكتروني صالح (يجب أن يكون فريدًا) |
| `role` | string | لا | الدور: `admin`، `developer`، `viewer`. الافتراضي: `viewer` |

### مثال على الطلب

```bash
curl -X POST https://api.example.com/v1/users \
  -H "Authorization: Bearer sk_live_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "أليس سميث",
    "email": "alice@example.com",
    "role": "developer"
  }'

الاستجابة (201 تم الإنشاء)

{
  "id": "usr_abc123",
  "name": "أليس سميث",
  "email": "alice@example.com",
  "role": "developer",
  "created_at": "2026-01-22T10:30:00Z"
}

استجابات الأخطاء

400 طلب سيئ - إدخال غير صالح

{
  "error": "validation_error",
  "message": "تنسيق البريد الإلكتروني غير صالح",
  "field": "email",
  "request_id": "req_xyz789"
}

401 غير مصرح به - مفتاح API مفقود/غير صالح

{
  "error": "unauthorized",
  "message": "مفتاح API غير صالح",
  "request_id": "req_xyz789"
}

409 تعارض - البريد الإلكتروني موجود بالفعل

{
  "error": "conflict",
  "message": "مستخدم بهذا البريد الإلكتروني موجود بالفعل",
  "request_id": "req_xyz789"
}

429 عدد كبير جدًا من الطلبات - تم تجاوز حد المعدل

{
  "error": "rate_limited",
  "message": "عدد كبير جدًا من الطلبات. حاول مرة أخرى في 60 ثانية.",
  "retry_after": 60,
  "request_id": "req_xyz789"
}

تحديد المعدل

100 طلب في الدقيقة لكل مفتاح API. انظر تحديد المعدل.


**التحسينات المطبقة:**
- تمت إضافة متطلبات المصادقة
- تم توثيق جميع المعلمات مع القيود
- استجابات نجاح كاملة + جميع استجابات الأخطاء
- مثال cURL جاهز للإنتاج
- معلومات تحديد المعدل
- تنسيق متناسق

دمج Claude مع Apidog لتوثيق API فائق الجودة

💡 نصيحة احترافية: استفد من Claude للمراجعات الثاقبة للوثائق السردية، بينما يضمن Apidog أن مواصفات API الخاصة بك قوية جدًا ويملأ الفجوات تلقائيًا بأمثلة عملية.

التعليمات المقترحة لـ Claude:"افحص /docs/api/ بحثًا عن الوضوح والمشاركة الشاملة. بعد ذلك، تحقق من اكتمال ملف /api/openapi.yaml باستخدام Apidog. سلط الضوء على أي تناقضات أو عناصر مفقودة، حتى أتمكن من معالجتها مباشرة في Apidog قبل المتابعة."

Bash

# الخطوة 1: المراجعة الأولية للنثر عبر Claude
> /docs-completeness  # يُخرج اقتراحات للغة وبنية أوضح

# الخطوة 2: التحقق من مواصفات API في Apidog
apidog check-completeness api/openapi.yaml  # يضع علامات على مشكلات مثل المخططات غير المكتملة أو الاستجابات المفقودة

# الخطوة 3: إنشاء المحتوى تلقائيًا باستخدام AI من Apidog
# (عبر واجهة مستخدم Apidog: الإعدادات ← AI ← إنشاء الأوصاف والأمثلة والملخصات تلقائيًا)

# الخطوة 4: التحقق النهائي من التوافق مع Claude
> /consistency-check  # يضمن توافق الوثائق والمواصفات بشكل مثالي

يؤدي هذا إلى إنشاء سير عمل حيث يتعامل Apidog مع التحقق المنظم من المواصفات ويتعامل Claude Code مع جودة النثر.

أفضل الممارسات لمراجعة الوثائق

اعرف جمهورك

صمم عمق الوثائق ليناسب القراء:

الجمهور	النمط	مثال
المطورون	أمثلة تعليمات برمجية بلغات متعددة	cURL، بايثون، جافاسكريبت
DevOps	خطوات النشر، التكوين	أمثلة Kubernetes YAML
فرق المنتجات	سير عمل عالي المستوى، مخططات	تدفقات الميزات مع لقطات الشاشة
الدعم	استكشاف الأخطاء وإصلاحها، المشكلات الشائعة	"الخطأ 429 يعني..."

امنح الوضوح الأولوية

اكتب بصيغة المبني للمعلوم، وهيكل المحتوى لتسهيل المسح السريع:

❌ قبل: "يتم إرسال الطلب عبر POST. ستحتوي الاستجابة على المستخدم."
✅ بعد: "أرسل طلب POST لإنشاء مستخدم. تعيد API المستخدم الجديد."

دائمًا قم بتضمين الأمثلة

المفاهيم المجردة تحتاج إلى ربط. كل نقطة نهاية API تحتاج إلى:

# ✅ جاهز للنسخ واللصق
curl -X GET https://api.example.com/v1/users/usr_123 \
  -H "Authorization: Bearer YOUR_API_KEY"

المزالق الشائعة

المأزق	الحل
كثرة المصطلحات التخصصية	عرّف المصطلحات عند أول استخدام
أمثلة قديمة	اختبار في CI/CD
توثيق الأخطاء المفقود	وثّق جميع رموز الأخطاء
تنسيق غير متناسق	استخدم القوالب
روابط معطلة	التحقق في CI/CD

الخاتمة

تحول مهارات Claude Code مراجعة الوثائق الفنية من عملية يدوية مملة إلى سير عمل ذكي ومؤتمت. أنت تصف ما يحتاج إلى مراجعة، ويقوم Claude بتدقيق مستودع التوثيق بأكمله، وتحديد الفجوات والتناقضات، وتطبيق الإصلاحات مع الحفاظ على معايير الجودة.

بالاشتراك مع Apidog للتحقق من مواصفات API، ستحقق تغطية توثيق شاملة.

button