كثيرًا ما تصل الواجهة البرمجية إلى أول مطوّر خارجي بلا مواصفة مكتوبة، ويتوقف بناء موقع Docusaurus عند خطأ واحد في docusaurus.config.js، ويدخل النص المنسوخ من مستند Word إلى المستودع بعناوين وقوائم مكسورة. لهذه المواقف الثلاثة في الحزمة ثلاثة وكلاء فرعيين (subagents) يعملون في Claude Code، لكل منهم ملف Markdown مستقل يحدد متى يُستدعى، وبأي خطوات يعمل، وماذا يسلّم.
الصيغة خاصة بـ Claude Code؛ لا يقرؤها claude.ai مباشرة، ولم أجهّز نسخة لـ Codex. لكن نص كل ملف تعليمات إنجليزية يمكنك لصقها في تعليمات مشروع (Project) على claude.ai.
الوكلاء الثلاثة كما تصفهم ملفاتهم
- api-documenter: يكتب مواصفة OpenAPI 3.0 لنقاط الواجهة، مع أمثلة طلب واستجابة تذكر كل حقل ونوعه وقواعد التحقق منه. ويضيف دليلًا لطرق المصادقة، ومرجعًا لرموز الأخطاء مع طريقة حل كل منها، وأمثلة curl، ومجموعة Postman أو Insomnia، وأمثلة استخدام SDK بأكثر من لغة، وخطة لإصدارات الواجهة مع أدلة الانتقال بينها.
- docusaurus-expert: يفحص أولًا بنية المجلدات، ثم يراجع docusaurus.config.js وsidebars.js، والاعتماديات وأوامر البناء في package.json، والقوالب والإضافات المستخدمة. ويسلّم إصلاحات بمسارات ملفات محددة، وخطوات لتتبّع أخطاء البناء، وإرشادات لمحتوى MDX وتخصيص المظهر والنشر.
- markdown-syntax-formatter: يحوّل التنسيق المرئي إلى صياغة Markdown وفق CommonMark وGitHub Flavored Markdown، فالأسطر المكتوبة بحروف كبيرة والرموز النقطية وعلامات التأكيد تصير عناوين وقوائم وتأكيدًا صحيحًا. ويرتّب مستويات العناوين دون قفز، ويضيف اسم اللغة إلى كتل الكود حين يتضح.
مثال: واجهة Express بلا مواصفة
لنفترض أن مسارات خادم Express في src/routes بلا أي مواصفة. تكتب: «Use the api-documenter agent to write an OpenAPI 3.0 spec for the routes in src/routes». ينص ملفه على أن يسلّم مواصفة تغطي كل نقطة مع أمثلة الطلب والاستجابة، ومرجعًا للأخطاء وأمثلة curl. وتنص تعليماته على التحقق من التوثيق باستدعاءات فعلية للواجهة، فوجّهه إلى خادم التطوير لا إلى بيئة الإنتاج.
وفي وصف كل من api-documenter وdocusaurus-expert عبارة «Use PROACTIVELY»، فقد يستدعيهما Claude دون أن تسمّيهما حين تعمل على توثيق API أو موقع Docusaurus. أما markdown-syntax-formatter فالأوضح أن تسمّيه في طلبك.
التشغيل في Claude Code
- فك ضغط الملف في مجلد لن تنقله لاحقًا.
- للتجربة في جلسة واحدة شغّل
claude --plugin-dir "PATH/TO/EXTRACTED/plugin"بعد وضع مسار فك الضغط الفعلي. - اكتب /agents داخل الجلسة وتأكد من ظهور الوكلاء الثلاثة.
- لتبقى متاحة دائمًا، انسخ الملفات الثلاثة من plugin/agents إلى .claude/agents داخل مشروعك، أو إلى ~/.claude/agents لتظهر في كل مشروعاتك، ثم افتح جلسة جديدة.
ما يلزمك وما لا تتوقعه
- يلزمك Claude Code مثبتًا ومسجّل الدخول، وتكلفة تشغيل النموذج على حسابك. ووكيل Docusaurus مكتوب لمواقع الإصدارين الثاني والثالث.
- لا تحدد الملفات قائمة أدوات، فيرث كل وكيل أدوات جلستك كلها، ومنها تعديل الملفات وتشغيل الأوامر. راجع ما يقترحه قبل قبوله.
- الحزمة نصوص تعليمات فقط، بلا سكربتات؛ فالمواصفة وأمثلة SDK يكتبها النموذج، وتحتاج مراجعة على واجهتك الفعلية.
- يذكر ملف docusaurus-expert مجلدًا باسم docs_to_claude مرجعًا للمسارات، وهو مجلد لا يلزم أن يوجد في مشروعك؛ فاذكر في طلبك مسار مجلد التوثيق عندك.
- التعليمات بالإنجليزية، فإن أردت التوثيق بالعربية فاطلب ذلك صراحة.
- وصفتُ الوكلاء هنا من نصوص ملفاتهم.
أرفقتُ مع الملفات الأصلية دليلًا عربيًا للتشغيل وفهرسًا بمسار كل وكيل.
الترخيص: MIT. الملفات الثلاثة من مجتمع BuildWithClaude وحقوق نشرها لـ davepoon، ونصوصها كما وردت دون تعديل.
