توثيقك الأول

1. يختار مجموعة التوثيق وفئات القرّاء. تُكتب الصفحات في مجموعة التوثيق الافتراضية ما لم تمرّر --set=handbook. ومن دون --audience يسألك لمن هذا التوثيق.
2. يجد وكيلك. يبحث عن أداة سطر أوامر لوكيل في PATH ويختارها. وإن كان لديك أكثر من وكيل، يسألك أيّها يكتب. ويختار --agent=codex نيابة عنك.
3. يجهّز الوكيل. يتأكد من أن مهارات LaRecipe مثبّتة في .claude/skills/ و .agents/skills/ (ومع Laravel Boost، يقدّمها Boost بدلًا منه). وفي مجموعة قاعدة البيانات، يضيف أيضًا خادم MCP المحلي larecipe إلى إعدادات ذلك الوكيل، لأن الوكيل يكتب من خلاله.
4. يعرض الأمر بالضبط ويسأل. ترى الأمر كاملًا قبل أن يعمل أي شيء.
5. يكتب الوكيل، وأنت تتابع. في Claude Code، تظهر كل خطوة في سطر قصير، مثل > Read app/Http/Controllers/OrderController.php أو > Write docs/api/orders.md، يليه ما يقوله الوكيل. أما تقدّم Codex فيمرّ كما هو. لا توجد مهلة زمنية، ويمكنك إيقافه في أي وقت بالضغط على Ctrl+C. وإن توقف الوكيل بخطأ، يعرض LaRecipe رمز الخروج. ولم يُضف شيء إلى git.
6. يسرد الصفحات ويتحقق منها. يقارن LaRecipe مجلد التوثيق قبل التشغيل وبعده (وفي مجموعة قاعدة البيانات، مجلد ترحيلات التوثيق)، ويسرد كل ملف بأنه created أو updated. ثم يشغّل php artisan larecipe:validate على المجموعة. وحين تنجح الصفحات تظهر الرسالة "The new pages pass validation. Review them, then commit them with your code." وحين لا تنجح، يفشل الأمر ويسرد الأخطاء التي عليك إصلاحها أولًا.

صفحات مجموعة المستودع ملفات جديدة في شجرة العمل لديك. أما صفحات مجموعة قاعدة البيانات فتُطبَّق على قاعدة بياناتك المحلية وتُكتب في ترحيل التوثيق الخاص بالفرع داخل database/migrations/docs/، فتصل إلى الإنتاج عبر الـ pull request مثل بقية تغييرك.

في الوضع التفاعلي، يسأل larecipe:install في آخر أسئلته "Generate starter docs from your app with your coding agent now?"، حين يجد وكيلًا مثبّتًا. أو أجب مسبقًا:

php artisan larecipe:install --onboard=api --onboard-agent=claude

كل فئة إعداد مسبق في المهارة larecipe-write-docs: مخطط للصفحات، ونبرة، وما يقرؤه من الكود، وما لا يكتبه أبدًا.

صفحات المنتج تبدأ بالمهمة، ولا تحوي أسماء أصناف ولا أوامر artisan. وصفحات API دقيقة وسهلة التصفّح، مع أمثلة طلبات واستجابات مأخوذة من Resources والاختبارات لديك. وصفحات الحزمة سهلة النسخ واللصق، وتذكر أسماء مفاتيح الإعدادات في النص. والصفحات الداخلية مباشرة ومكثّفة، مكتوبة لمطوّر Laravel في يومه الأول، مع مراجع <Model> لنموذج البيانات.

وتصلح بعض الأسماء البديلة أيضًا: users بدلًا من product، و api-consumers بدلًا من api، و package-users بدلًا من package، و team أو handbook بدلًا من internal. والأسماء التي لا يعرفها تُتجاهل.

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

• الأسرار والإعدادات. لا قيم من .env، ولا مفاتيح، ولا رموز وصول، ولا كلمات مرور، ولا سلاسل اتصال، ولا أسماء مضيفين، ولا روابط داخلية. يجوز أن يظهر مفتاح الإعدادات باسمه، لا بقيمته أبدًا. وتستخدم أمثلة API قيمة وهمية مثل YOUR_API_TOKEN.
• بيانات العملاء. لا أسماء، ولا عناوين بريد، ولا معرّفات، ولا سجلات من seeders أو fixtures تبدو حقيقية.
• التخمينات. ما لا يقوله الكود لا تقوله الصفحة. ويترك الوكيل ملاحظة في تقريره بدلًا من ذلك.

ولكل فئة على حدة، يتخطّى أيضًا المسارات الداخلية وميزات الإدارة في صفحات المنتج، ونقاط النهاية الداخلية في صفحات API، والأصناف الموسومة @internal في صفحات الحزمة.

ويجب أن تكون قيمة access.mode في مجموعة handbook الخاصة بالإعداد المسبق internal هي auth أو gate. وتشرح أساسيات الإعداد كيف تضيف مجموعة ثانية.

سير عمل الإعداد الأولي في المهارة واحد لكل الوكلاء. يقرأ الوكيل أولًا AGENTS.md و README.md و composer.json والتوثيق الموجود لديك، ويحتفظ بصفحة المقدمة التي كتبها المثبّت، فيحسّنها ولا يستبدلها. ويخطّط لكل صفحة قبل كتابتها، مع الكود الذي ستقرؤه كل واحدة. ويجمع الصفحات الجديدة حسب الفئة في التنقل، ولا يكتب إلا داخل مجلد التوثيق، ويشغّل التحقق، وينهي عمله بقائمة بالصفحات التي كتبها وبكل ما استبعده.

يكتشف LaRecipe الوكيل بأداة سطر الأوامر الخاصة به في PATH (claude و codex و cursor-agent و gemini و copilot)، أو بملفاته داخل المشروع (.claude و CLAUDE.md و .codex و .cursor و .gemini و GEMINI.md و .github/copilot-instructions.md و .github/skills). ولا يختار الإعداد الأولي إلا وكيلًا أداته مثبّتة، لأنه يجب أن يشغّلها.

ما تقرؤه هو ما يعمل: الأمر المعروض على الشاشة والعملية التي يبدؤها LaRecipe مبنيّان من الوسائط نفسها. لمجموعة مستودع في docs/:

claude -p "Use the larecipe-write-docs skill to run onboarding for audiences: product, api (set: docs)" --allowedTools "Read,Grep,Glob,Edit(docs/**),Write(docs/**),Bash(php artisan larecipe:*)" --output-format stream-json --verbose

codex exec --sandbox workspace-write 'Use the $larecipe-write-docs skill to run onboarding for audiences: product, api (set: docs)'

يمكن لـ Claude Code أن يقرأ مشروعك كله، لكنه لا يكتب إلا داخل docs/، ولا يشغّل إلا أوامر php artisan larecipe:*. وفي مجموعة قاعدة البيانات، تكون الأدوات المسموح بها Read,Grep,Glob,mcp__larecipe,Bash(php artisan larecipe:*): فلا يكتب الوكيل إلا عبر أدوات التأليف في خادم MCP الخاص بـ LaRecipe، وهي تسجّل كل تغيير في ترحيل توثيق.

لا تستطيع بيئة العزل في Codex أن تحصر الكتابة في مجلد واحد، فينبّه LaRecipe إلى ذلك تحت الأمر: راجع الـ diff قبل أن تضيف التغييرات إلى git. ولكي يكتب Codex في مجموعة قاعدة بيانات، يحتاج أيضًا إلى خادم MCP larecipe في .codex/config.toml، داخل مشروع يثق به Codex.

أما Cursor و Gemini CLI و GitHub Copilot، فافتح الوكيل في مشروعك وأرسل إليه الموجّه الذي يطبعه LaRecipe:

Use the larecipe-write-docs skill to run onboarding for audiences: product, api (set: docs)

لا يبدأ LaRecipe وكيلًا أبدًا من دون موافقتك:

• في الوضع التفاعلي، يسأل "Run it now?". وإن أجبت بالرفض، يطبع الأمر لتشغّله لاحقًا.
• يشغّله --yes من دون سؤال، للسكربتات.
• يكتفي --print بطباعة الأمر.
• من دون طرفية ومن دون --yes، يطبع الأمر ويتوقف. ويشمل ذلك larecipe:install --no-interaction --onboard=api: ينهي المثبّت عمله، وتشغّل أنت php artisan larecipe:onboard --audience=api --yes حين تكون مستعدًا.
• يطبع larecipe:install --dry-run --onboard=api الأمر ولا يشغّل شيئًا.

وحين تسمّي بالخيار --agent وكيلًا ليست أداته في PATH، يطبع LaRecipe الأمر ويطلب منك تشغيله حيث يكون الوكيل مثبّتًا.

حين لا تكون أي أداة وكيل مثبّتة، يحتفظ توثيقك بصفحة المقدمة التي كتبها المثبّت، ويطبع LaRecipe الأمر الذي تشغّله حين يصبح لديك وكيل:

php artisan larecipe:onboard --audience=api --set=docs

يعيش سير العمل في المهارة larecipe-write-docs لا في الأمر، فيستطيع أي وكيل يقرأ المهارات أن يشغّله من محادثة: أرسل إليه الموجّه المعروض أعلاه. ويمكنك أيضًا أن تكتب الصفحات الأولى بنفسك، فصفحتا Markdown والمكوّنات تغطّيان كل ما يمكن أن تحويه الصفحة.

مقروءة مباشرة من سجلّ الأوامر في هذا التطبيق:

php artisan larecipe:onboard [--audience [AUDIENCE]] [--set [SET]] [--agent [AGENT]] [--print] [--yes]