Skills: مهارات توليد التوثيق
آخر تحديث: 2026-08-31
الكود الجيد يجب أن يوثّق نفسه بنفسه، لكن التوثيق الجيد يوفر على القادمين الجدد الطرق الالتفافية — المهارات تضمن ألا يكون التوثيق الزاوية المنسية.
1. أنواع التوثيق والمهارات
(1) مصفوفة أنواع التوثيق
| نوع التوثيق | مصدر المدخلات | تنسيق المخرجات | أدوات المهارة |
|---|---|---|---|
| توثيق API | تعريفات المسارات/الواجهات | Markdown/HTML | Read، Grep، Write |
| README | تكوين المشروع | Markdown | Read، Glob، Write |
| سجل التغييرات | git log | Markdown | Bash، Read، Write |
| تعليقات الكود | الكود المصدري | تعليقات مضمّنة | Read، Edit |
| توثيق البنية | هيكل المشروع | Mermaid + Markdown | Glob، Read، Write |
(2) معايير جودة التوثيق
TEXT
📖 للعرض فقط
التوثيق الجيد يجب أن يكون:
├── دقيقًا: متسقًا مع سلوك الكود الفعلي
├── كاملًا: يغطي جميع الواجهات العامة
├── موجزًا: لا حشو، كل جملة تحمل معلومة
├── محدثًا: يُحدّث عندما يتغير الكود
└── متاحًا: تنسيق موحد، سهل البحث
2. توليد توثيق API
(1) استخراج واجهات API من الكود
MARKDOWN
## تدفق توليد توثيق API
1. Glob للعثور على ملفات المسارات/المتحكمات
2. Read لكل تعريف واجهة
3. استخرج: المسار، الطريقة، المعاملات، القيم المرجعة، الاستثناءات
4. نظّم المخرجات حسب الوحدة
(2) قالب التوثيق
MARKDOWN
## POST /api/users
### الوصف
إنشاء مستخدم جديد
### معاملات الطلب
| المعامل | النوع | مطلوب | الوصف |
|:----------|:-----|:---------|:------------|
| name | string | نعم | اسم المستخدم |
| email | string | نعم | عنوان البريد الإلكتروني |
### القيم المرجعة
| الحقل | النوع | الوصف |
|:------|:-----|:------------|
| id | integer | معرف المستخدم |
| name | string | اسم المستخدم |
### الاستثناءات
| رمز الحالة | الوصف |
|:------------|:------------|
| 400 | فشل التحقق من المعاملات |
| 409 | البريد الإلكتروني موجود بالفعل |
3. توليد README
(1) كشف معلومات المشروع تلقائيًا
MARKDOWN
## جمع معلومات README
1. Glob: كشف ملفات المشروع (package.json/go.mod/pyproject.toml)
2. Read: اقرأ التكوين للحصول على حزمة التقنيات والتبعيات والنصوص البرمجية
3. Grep: ابحث عن ملفات الدخول ومتغيرات البيئة وعناصر التكوين
4. Bash: git log --oneline -10 للحصول على التغييرات الأخيرة
(2) قالب README
MARKDOWN
# اسم المشروع
> وصف بجملة واحدة
## البدء السريع
### المتطلبات
- Node.js >= 18
- PostgreSQL >= 14
### التثبيت
```bash
npm install
cp .env.example .env
npm run dev
هيكل المشروع
...
دليل التطوير
...
النشر
...
---
## 4. توليد سجل التغييرات
### (1) استخراج التغييرات من Git
```bash
# الحصول على التغييرات بين الإصدارات
git log v1.1.0..v1.2.0 --oneline
git log v1.1.0..v1.2.0 --format="%s" --no-merges
(2) التصنيف والتنظيم
MARKDOWN
## v1.2.0 (2026-08-15)
### ✨ ميزات جديدة
- إضافة وظيفة تصدير المستخدمين (#42)
- دعم الوضع الداكن (#45)
### 🐛 إصلاحات
- إصلاح مشكلة انتهاء مهلة تسجيل الدخول (#38)
- إصلاح خطأ ترتيب البيانات (#41)
### 💔 تغييرات غير متوافقة
- تغير تنسيق إرجاع API /users، حقل name أُعيدت تسميته إلى username
5. ممارسة مهارة التوثيق
▶ مثال: توليد توثيق مشروع كامل
أنشأت Alice مهارة توليد توثيق مشروع بنقرة واحدة:
YAML
---
name: doc-generator
description: "توليد توثيق مشروع كامل بنقرة واحدة"
triggers:
- keyword: "gen-docs"
tools:
- Read
- Grep
- Glob
- Write
- Bash
---
قال Bob: "أكبر عدو للتوثيق هو التقادم — المهارات تستخرج المعلومات من الكود في الوقت الفعلي، مما يضمن بقاء التوثيق والكود متزامنين دائمًا."
❓ الأسئلة الشائعة
س هل التوثيق المولد تلقائيًا يحتاج مراجعة يدوية؟
ج بالتأكيد. الذكاء الاصطناعي يمكنه استخراج المعلومات الهيكلية، لكن المعنى التجاري وسيناريوهات الاستخدام تحتاج إضافة وتأكيدًا بشريًا.
س أين يجب أن يوضع التوثيق؟
ج توثيق API في
docs/api/، README في جذر المشروع، سجل التغييرات في CHANGELOG.md، توثيق البنية في docs/architecture/.س كيف أحافظ على توافق التوثيق مع الكود؟
ج أضف خطوات فحص التوثيق في CI؛ المهارات تُحدّث التوثيق ذي الصلة تلقائيًا عند تغير الكود؛ تحقق من توافق التوثيق أثناء مراجعة PR.
📖 ملخص
- خمسة أنواع توثيق: API، README، سجل التغييرات، تعليقات الكود، توثيق البنية
- توثيق API: استخراج تعريفات الواجهات من الكود، إخراج حسب القالب
- README: كشف معلومات المشروع تلقائيًا، ملء القالب القياسي
- سجل التغييرات: استخراج سجلات الالتزامات من Git، تصنيف وتنظيم
- المبدأ الأساسي: التوثيق متزامن مع الكود؛ الذكاء الاصطناعي يستخرج البنية + البشر يكملون الدلالات
📝 تمارين
- أساسي (⭐): أنشئ مهارة توليد README تكشف حزمة تقنيات المشروع تلقائيًا وتُخرج قالبًا قياسيًا.
- متوسط (⭐⭐): أنشئ مهارة توليد توثيق API تستخرج معلومات الواجهات من ملفات مسارات FastAPI/Express.
- متقدم (⭐⭐⭐): أنشئ مهارة توليد توثيق مشروع كاملة تُخرج README + توثيق API + مخطط البنية + سجل التغييرات كمجموعة كاملة.
