الوحدة 16 — مشروع: صندوق أدوات Claude Code الكامل لفريق Kiosque

تُغلق هذه الوحدة الدورة بجمع القطع المرئيّة في الوحدات 3 و6 و7 و9 و10 و11 و12 و14 حول مشروع واحد: صندوق أدوات Kiosque. خمسة مطوّرين يشتركون في تطبيق FastAPI/React (Kiosque، قارئ RSS مؤسّسيّ). الهدف: تهيئة المستودع بحيث يستعمل كلّ حاسوب، وكلّ cron، وكلّ PR، Claude Code بالطريقة نفسها، بالضوابط نفسها والكلفة المتوقّعة نفسها. في النهاية، متعاون جديد يستنسخ Kiosque ويكتب /nouveau-endpoint فيحصل على عمل جيّد دون أن يتحدّث مع زملائه.

الشجرة النهائيّة لمستودع Kiosque

kiosque/
├── .claude/
│   ├── settings.json                 # allow/deny وplugins المُفعَّلة
│   ├── settings.local.json           # (.gitignore) تفضيلات شخصيّة
│   ├── agents/{revieweur,testeur}.md
│   ├── commands/                     # /commit /revue /nouveau-endpoint
│   │                                 # /tests-cibles /doc-api /notes-de-version
│   ├── claude-security-guidance.md   # قواعد داخليّة
│   └── security-patterns.yaml        # أنماط مشروع محظورة
├── .github/workflows/claude.yml      # anthropics/claude-code-action@v1
├── .mcp.json                         # خوادم MCP باسم github وpostgres
├── backend/                          # FastAPI + SQLAlchemy + Alembic
├── frontend/                         # Vite + React + TanStack Query
├── plugins/kiosque-tools/            # plugin محلّيّ، تحت الإدارة الإصداريّة
├── CLAUDE.md                         # اتّفاقيّات، < 200 سطرًا
├── Makefile                          # أهداف test وlint وrun وmigrate
└── README.md

خمسة ثوابت: settings.json تحت الإدارة الإصداريّة صالح للجميع؛ وsettings.local.json شخصيّ، متجاهَل من git؛ وskills المشروع تحت .claude/commands/، وتلك القابلة لإعادة الاستعمال تحت plugins/kiosque-tools/؛ وسب-agentان لا عشرة (دور واضح، prompt قصير)؛ وMakefile هو العقد بين البشر وClaude — كلّ skill تستدعيه بدل ابتكار أمر خاصّ.

الخطوة 1 — إرساء ثوابت الفريق

في shell مستنسَخ لتوّه: git checkout -b claude-boite-a-outils ثمّ mkdir -p .claude/{agents,commands} plugins/kiosque-tools/{commands,skills}. التحقّق: ls .claude/ يعرض agents commands.

اكتب بعدها .claude/settings.json — هذا الملفّ هو الحاكم:

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "allow": [
      "Bash(make test)",
      "Bash(make lint)",
      "Bash(make run)",
      "Bash(make migrate)",
      "Bash(ruff *)",
      "Bash(pytest *)",
      "Bash(npm test)",
      "Bash(npm run build)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Bash(curl *)",
      "Bash(wget *)"
    ]
  },
  "enabledPlugins": {
    "security-guidance@claude-plugins-official": true,
    "kiosque-tools@local": true
  }
}

التحقّق: أطلق claude في المجلّد، واكتب /status وأكِّد أنّ سطر Setting sources يذكر Project؛ اكتب /permissions لرؤية القوائم المدموجة.

الخطوة 2 — كتابة CLAUDE.md

افتح CLAUDE.md في الجذر. محتوى تحت 200 سطرًا، بخمسة أقسام: البنية (backend مع FastAPI، وfrontend مع React، وmigrations Alembic في backend/migrations/)؛ هدف الاختبارات (make test يشغّل pytest ثمّ npm test؛ PR بلا اختبارات خضراء يرفضها الـworkflow)؛ الأسلوب (ruff للـbackend، وprettier للـfrontend، ولا print يُسلَّم)؛ Migrations (لا تعديل لـmigration مطبَّق؛ دائمًا revision جديدة)؛ أين تجد ماذا (docstrings في backend/app/routes/*.py، وأنماط في frontend/src/styles/).

التحقّق: يجب أن يشير /context إلى أنّ CLAUDE.md المشروع يزن نحو 1800 رمز — إن زاد، قلّص.

الخطوة 3 — Skills المشروع الستّ

كلّ skill تعيش تحت .claude/commands/<nom>.md مع frontmatter أدنى (description، وربّما allowed-tools):

• /commit: رسالة conventional من git diff --staged، تقترح commit، ولا تدفع. allowed-tools: [Bash(git *)].
• /revue: يستدعي revieweur على الـdiff مقابل origin/main، ويعرض المكتشفات.
• /nouveau-endpoint: وسيطان (method وpath)، يُولّد مسار FastAPI، ومخطّط Pydantic، وmigration Alembic إن مُسّ نموذج، واختبار pytest، وstub React. كلّ خطوة تستدعي make test قبل المتابعة.
• /tests-cibles: يحسب القائمة الدنيا من الـdiff، ويُشغّل pytest -k "<expr>" ثمّ npm test -- --changed.
• /doc-api: يُعيد توليد doc OpenAPI ويُحدِّث docs/api.md.
• /notes-de-version: يستأنف سكربت Python من الوحدة 14، ويُستدعى أيضًا من cron.

التحقّق: / بلا شيء يعرض الأوامر الستّة؛ و/nouveau-endpoint POST /articles/{id}/lu يُنتج route + test + migration متّسقة في دور واحد، وينتهي الدور بـmake test أخضر.

الخطوة 4 — السب-agentان

ملفّان قصيران، دوران.

.claude/agents/revieweur.md — frontmatter skills: [Read, Grep, Bash]، وmodel: claude-sonnet-5. النصّ: «تُراجع diff FastAPI + React. أشِر إلى الانحدارات، ونسيان الاختبارات، وتسرّب الأسرار، والـmigrations الخطرة. استخدم git diff origin/main...HEAD. لا تكتب في الملفّات. اختم بحكم حاجب | يجب تصحيحه | مقبول.»

.claude/agents/testeur.md — frontmatter skills: [Bash, Read]، وmodel: claude-sonnet-5. النصّ: «تُطلق make test (أو انتقاء pytest -k) وترفع الإخفاقات بالملفّ والسطر. لا تعديل للشيفرة. ملخّص من سطرَين لكلّ إخفاق.»

التحقّق: /agents يعرض السب-agentَين. /revue يجب أن يستدعي revieweur (يظهر في الأثر).

الخطوة 5 — Hooks

ثلاثة hooks في .claude/settings.json، تحت مفتاح hooks، جميعها بـ"type": "command": PostToolUse ruff بمطابق matcher: "Edit|Write" وأمر command: "make lint 2>/dev/null || true" (linter بعد كلّ كتابة، الخرج مُتَجاهَل عند الفشل، الـlint إرشاديّ)؛ وPreToolUse حماية migrations/.env بنفس المطابق، وأمر command: ".claude/hooks/protege-sensible.sh" — سكربت قصير يرفض (رمز 2) أيّ كتابة على backend/migrations/*.py مُودَع أصلًا أو على .env*؛ وStop make test بلا matcher، وأمر command: "make test"، فتعمل المجموعة عند كلّ نهاية دور ويُعاد حقن نتيجة الفشل في المحادثة.

التحقّق: اطلب من Claude الكتابة في .env؛ يجب أن يجيب الـhook مرفوض: ملفّ حسّاس محميّ. عدّل مسارًا واترك الدور ينتهي: يظهر make test في الأثر.

الخطوة 6 — خوادم MCP

.mcp.json في الجذر، تحت الإدارة الإصداريّة، يُصرِّح بخادمَي stdio: github (عبر @modelcontextprotocol/server-github) لفتح PR وسرد issues والتعليق؛ وpostgres (عبر @modelcontextprotocol/server-postgres، رابط بمستخدم للقراءة فقط) لفحص المخطّط. تبقى التعريفات مؤجَّلة عبر tool search — لا يُحمِّلها Claude إلّا عند الحاجة.

التحقّق: /mcp يعرض خادمَين متّصلَين. /context all يجب أن يُشير إلى حمل MCP قريب من الصفر ما لم تُستدعَ أداة.

الخطوة 7 — الـplugin kiosque-tools

plugins/kiosque-tools/plugin.json يُصرِّح بـplugin محلّيّ: name وversion وdescription وقوائم commands وskills مُشيرة إلى المجلّدات الفرعيّة. يتضمّن نسخة من /notes-de-version قابلة لإعادة الاستعمال على مستودع داخليّ آخر، وskill changelog-hebdo تُلخّص أسبوع commits. التفعيل عبر enabledPlugins في .claude/settings.json، وهو موجود سلفًا.

التحقّق: /plugin list يذكر kiosque-tools@local بحالة enabled. تظهر أوامر الـplugin في اللوحة ببادئة kiosque-tools:.

الخطوة 8 — Workflow في GitHub Actions

.github/workflows/claude.yml يستأنف هيكل الوحدة 14: مُفعِّلات issue_comment وpull_request_review_comment (types [created])، وحارس if: contains(github.event.comment.body, '@claude')، وصلاحيّات أدنى (contents: write وpull-requests: write وissues: write وid-token: write وactions: read)، وactions/checkout@v6 مع fetch-depth: 1، ثمّ anthropics/claude-code-action@v1 مع anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }} وclaude_args: --max-turns 8 --model claude-sonnet-5 --allowedTools "Bash(make test),Bash(make lint),Read,Edit".

التحقّق: افتح PR، وعلِّق @claude انظر في هذا الـdiff وصحّح مشاكل lint؛ ينطلق الـworkflow، ويُدفَع commit على الفرع، ويبقى make test أخضر.

سيناريو عرض في عشر دقائق

إيقاع مجرَّب لعرض صندوق الأدوات لزميل جديد.

• 0 - 1 د — استنساخ المستودع، إطلاق claude في الجذر. /status يؤكّد الإعدادات المشتركة، والـplugins النشطة، وخادمَي MCP متّصلَين.
• 1 - 3 د — /nouveau-endpoint POST /articles/{id}/lu. يُولِّد Claude route وschéma وmigration واختبارًا. hook Stop يُشغّل make test: أخضر.
• 3 - 5 د — اطلب «أظهر لي محتوى .env». قاعدة deny ترفض، ويعرض الأثر ذلك.
• 5 - 6 د — /revue: يذكر السب-agent revieweur نقطتَين طفيفتَين، بالحكم مقبول.
• 6 - 7 د — /commit يُنتج رسالة conventional، staged، جاهزة للدفع.
• 7 - 9 د — ادفع الفرع، وافتح PR، وعلِّق @claude تحقّق من غياب الانحدار. ينطلق الـworkflow، ويعلّق Claude على الـPR.
• 9 - 10 د — /usage: كلفة العرض نحو 0.25 EUR، وPrompt cache (main) بقراءة 90 ٪.

شبكة التقييم

عشرون نقطة على خمسة محاور.

المحور	المعيار	النقاط
تهيئة مشتركة	.claude/settings.json تحت الإدارة الإصداريّة، permissions.allow/deny متّسقة، enabledPlugins مضبوطة	4
Skills وسب-agents	Skills الستّ موجودة، السب-agentان بدور واضح وقصير، /nouveau-endpoint يُنتج route + test + migration	4
Hooks	PostToolUse ruff، وPreToolUse حماية .env/migrations، وStop make test جاهزة ومُطلقة	3
MCP وplugin	.mcp.json تحت الإدارة الإصداريّة مع github وpostgres، وplugin kiosque-tools مُفعَّل ومختبر	3
Workflow في CI	claude.yml يُطلَق على @claude، بأدنى صلاحيّات، و--allowedTools مُقيِّد، وPR عرض خضراء	3
الكلفة والنظافة	CLAUDE.md < 200 سطرًا، /usage يعرض Prompt cache (main) حارًّا، كلفة العرض < 0.50 EUR	3

مشروع دون 15 من 20 يُشير إلى نقص في محور: غالبًا workflow في CI أو الـhooks. مشروع بـ18 من 20 فأكثر يصمد في إنتاج داخليّ — الوحدة 15 تذكّر بالحركات الشهريّة (مراجعة behavior flags، وقراءة ~/.claude/usage-data/report.html).

متغيّرات

ثلاث متغيّرات للتكيّف دون إعادة البناء:

• Kiosque-mono. مطوّر واحد: ثلاث skills (/commit، /revue، /nouveau-endpoint)، وسب-agent واحد (testeur)، ولا workflow (يكفي cron الوحدة 14).
• Kiosque-scale. خمسون مطوّرًا: managed settings لإقفال permissions.deny وenabledPlugins وmodelPricing بتعرفة تعاقديّة؛ نشر kiosque-tools في marketplace خاصّة.
• Kiosque-cloud. فريق يعمل غالبًا عبر Claude Code on the web: .claude/settings.json و.mcp.json وCLAUDE.md وskills وworkflow تعمل؛ وما يعيش في ~/.claude/ (إعدادات user، وplugins بنطاق user) يجب نقله إلى المستودع أو إلى managed settings.

فخوخ متكرّرة

• skill مُثرثرة. /nouveau-endpoint يُضمِّن دليل FastAPI يتجاوز ميزانيّة السياق؛ احفظ الجوهر، ودع Claude يقرأ الملفّات.
• سب-agent يكتب. revieweur مأذون بالكتابة يُصلح بنفسه ما ينبغي أن يُشير إليه؛ frontmatter بلا Edit ولا Write.
• hook Stop طويل جدًّا. make test بثلاث دقائق يحجب كلّ دور؛ اعزل هدف make test-rapide للـhook.
• MCP postgres بالكتابة. دائمًا رابط بمستخدم readonly — DROP TABLE عرضيّ لا يمكن استرجاعه.
• --dangerously-skip-permissions في الـworkflow. أبدًا على runner غير معزول؛ دائمًا --permission-mode dontAsk و--allowedTools ضيّق.
• CLAUDE.md الجذر يتضخّم. انقل التعليمات المفصَّلة إلى skill قابلة للاستدعاء، واحفظ الثوابت المستقرّة في ملفّ الجذر.

نقطة الوصول

كلّ حاسوب يشترك في نفس اللوحة: نفس الأوامر، ونفس قواعد الصلاحيّة، ونفس السب-agents، ونفس الـhooks، ونفس خوادم MCP. يُعيد workflow GitHub Actions تشغيل اللوحة في CI. cron ليليّ (الوحدة 14) قادر على استدعاء claude --bare -p بنفس الضمانات. لم يعد Claude Code أداةً تُستعمل، بل مكوّنًا تحت الإدارة الإصداريّة يطبّق القواعد بصرامة تنسيقيّة توازي الـlinter والاختبارات.

أنت جاهز للمراجعة والاختبار.