في مقال ماذا كشف Vibe Coding عن بناء المنتجات قلنا إن الكود صار أرخص جزء في المنتج، والمشكلة انتقلت لمكان ثاني هل نفهم وش بنينا بما يكفي عشان نحافظ عليه؟ وفي مقال استخدم opencode من الـTerminal شفنا الحلقة اللي يدور فيها الـAgent. الكلام جميل، لكن الشيء اللي ما حليناه لما تكتب للـAgent “ابن لي API” ويرجع لك بمئتين سطر، وين النية اللي بنيت عليها؟ في الدردشة. والدردشة تضيع.
في هذا المقال بنسوي ثلاثة أشياء. أولا نفهم وش Spec Kit ووش الفكرة اللي وراه، وليش تهمك أنت كمهندس مو كمتفرج. ثانيا نثبته ونربطه بـopencode ونموذج مجاني من Meta، بدون ما ندفع ريال. وثالثا نبني فيه مشروع كامل API لقائمة مهام، وبعدها واجهة ويب فوقه بنفس الطريقة، والنتيجة النهائية بتجربها بنفسك داخل المقال.
وش Spec Kit؟
الـSpec Kit مشروع مفتوح المصدر من GitHub، وصل للإصدار 1.0.0 في أغسطس 2026. الفكرة كلها في جملة واحدة كتبوها في ملف spec-driven.md لعقود كان الكود هو الملك، والمتطلبات سقالة نرميها بعد ما نخلص. Spec-Driven Development يقلبها المتطلبات هي مصدر الحقيقة، والكود مجرد تعبير عنها بلغة وإطار معين. تبي تغيّر البرنامج؟ غيّر المتطلبات وخل الـAgent يعيد البناء.
ليش هذا صار ممكن الحين؟ لأن النماذج صارت تقرأ مواصفة مكتوبة بلغة طبيعية وتحولها لخطة ثم كود بشكل معقول. وليش صار ضروري؟ لأن البناء بدون بنية يطلع فوضى، وهذا بالضبط اللي نشوفه في Vibe Coding. Spec Kit هو البنية.
عمليًا Spec Kit ثلاثة أشياء:
- أداة specify تضيف في مشروعك مجلد .specify/ (قوالب، سكربتات، ملف الدستور) وأوامر /speckit.* لوكيلك المفضل، وتدعم أكثر من 30 وكيل.
- سير عمل ثابت: constitution ← specify ← clarify ← plan ← tasks ← analyze ← implement ← converge. كل خطوة تطلع ملف تراجعه وتحفظه في Git.
- امتدادات مثل bug (تشخيص ← إصلاح ← اختبار) وassess (تقييم فكرة قبل ما تصرف عليها جهد)، وpresets لقطاعات مثل healthcare-compliance.
ملاحظة سريعة عن الأسماء عشان ما تتلخبط. Spec Kit هو المشروع والمنهجية. specify هي أداة سطر الأوامر. وspec-kit-copilot مستودع ثاني فيه “مهارات” تعلّم الـAgent يستخدم الأداة، بنرجع له بعد شوي.
ليش تهمك كمهندس؟
الكلام النظري عن “المتطلبات مصدر الحقيقة” ما يقنع أحد. اللي أقنعني هو أشياء شفتها أثناء التجربة، وبتشوفها معي في هذا المقال:
تراجع النية قبل الكود. المتطلبات اللي طلعت من /speckit.specify قصص مستخدم مرتبة بالأولوية، وسيناريوهات قبول بصيغة Given/When/Then، ومتطلبات مرقمة. ولا كلمة عن FastAPI ولا SQLite. هذا ملف تقدر تحطه في Pull Request ويراجعه زميلك قبل ما ينكتب سطر كود.
الدستور يغيّر سلوك الـAgent فعلًا. كتبت مبدأ واحد حاسم “كل endpoint لها اختبارات، غير قابل للتفاوض”. ما كررته ولا مرة، ومع ذلك ظهر أثره في الخطة (بوابة Constitution Check)، وفي المهام (اختبار لكل قصة يكتب أولا ولازم يفشل)، وفي التنفيذ وأنا أتابع الـAgent يكتب الاختبارات ويشغلها وتفشل قبل ما يكتب الكود.
كل قرار تقني له سبب مكتوب. ملف research.md فيه 11 قرار بصيغة القرار، السبب، البدائل المرفوضة. ليش حد العنوان 200 حرف مو 255؟ مكتوب. هذا اللي يضيع دايم في الدردشة.
نفس الطريقة تشتغل على كود موجود. وهذا الاختبار الحقيقي. أعدت الدورة على نفس المشروع لإضافة واجهة ويب، والـAgent قرأ الدستور والمتطلبات الأولى وما لمس الـAPI.
ما تنحبس مع Agent أو نموذج. المواصفات ملفات Markdown في مستودعك. نفس specs/ يشتغل مع Copilot اليوم وClaude Code بكرة وopencode بنموذج مجاني مثل ما بنسوي الحين.
قبل ما نبدأ الـAgent يظل هو اللي يكتب الكود. اللي تغير إن “وش المفروض يكون الكود” صار ملفات تكتبها وتراجعها وتعيش في Git، مو في نافذة شات.
التثبيت
تحتاج Git، وPython 3.11 أو أحدث (أو خل uv يجيبه لك). أنا على Windows 11 وPowerShell 7، والأوامر على ماك ولينكس نفسها إلا اللي أنبه عليه.
bash
irm https://astral.sh/uv/install.ps1 | iex # ماك/لينكس: curl -LsSf https://astral.sh/uv/install.sh | sh
uv tool install specify-cli
specify --versionطلع لي specify 1.0.4. وإذا تبي تتأكد من بيئتك كاملة شغّل specify check، يفحص Git ويدور على الوكلاء المثبتين عندك.
الـAgent والنموذج: opencode ونموذج Meta المجاني
ال،Spec Kit ما يفرض عليك وكيل. اخترت opencode مفتوح المصدر، من الطرفية، وفيه نماذج مجانية عبر OpenCode Zen بدون مفتاح API. وهذي المرة استخدمت نموذج Meta المجاني بدل Big Pickle.
bash
npm install -g opencode-ai
opencode models | Select-String "^opencode/.*free"
opencode run -m opencode/muse-spark-1.3-contributor-free "Reply with exactly: OK"
سبعة نماذج مجانية، والنموذج رد بـ OK من أول مرة بدون تسجيل دخول. ولاحظ شريط الحالة في كل لقطات هذا المقال: Muse Spark 1.3 Free، يعني الرحلة كلها قابلة للإعادة عندك بدون ما تدفع شيء.
تنبيه مهم. كلمة Contributor في اسم النموذج معناها إن Meta تستخدم طلباتك ومخرجاتك لتدريب نماذجها مقابل السعر المجاني. ممتاز للتجارب والمشاريع المفتوحة مثل هذا المقال، ولا تستخدمه على كود شغل سري. ومع Copilot أو Claude Code تتخطى هذا القسم كله، وبقية الأوامر ما تتغير.
المهارات Skills خل الـAgent يعرف أوامر specify بنفسه
هنا يجي دور مستودع spec-kit-copilot. فيه تسع مهارات (ملفات SKILL.md) تشرح للوكيل متى وكيف يشغّل كل أمر من أوامر specify: init وcheck وextension وpreset وbundle وworkflow وworkflow-step وself وcli-setup. صُممت لـCopilot CLI، لكن الصيغة هي نفس صيغة المهارات اللي شرحناها في مقال opencode، فتنسخها لنفس المجلد وتشتغل.
bash
git clone --depth 1 https://github.com/github/spec-kit-copilot.git
$SkillsDir = "$env:USERPROFILE\.config\opencode\skills" # ماك/لينكس: ~/.config/opencode/skills
Copy-Item spec-kit-copilot\skills\* $SkillsDir -Recurse -Force
opencode debug skill | ConvertFrom-Json | Where-Object name -like "speckit-*" | Select-Object name
انتبه لشيء واحد. مهارة speckit-init في المستودع مكتوبة عمدًا عشان تشغّل –integration copilot –integration-options=”–skills”، يعني تطلع لك ملفات في .github/skills/ ما يشوفها opencode. استبدلتها بنسخة تستهدف –integration opencode، وحاطها لك كاملة في آخر المقال. بقية المهارات الثمان تشتغل مثل ما هي.
وش الفايدة من المهارات إذا أنا أقدر أكتب الأوامر بنفسي؟ إنك تقول للـAgent “أضف امتداد bug للمشروع” وهو يختار مهارة speckit-extension ويشغل الأمر الصحيح. المهارة تحفظ “كيف” عشان أنت تركز على “وش”.
bash
mkdir ~\dev\speckit-lab; cd ~\dev\speckit-lab
specify init todo-api --integration opencode --script ps --ignore-agent-tools
cd todo-api
ثلاث ملاحظات من التجربة. مرر دايم –script (ps على Windows وsh على ماك ولينكس)، لأنه بدونه يفتح قائمة اختيار تفاعلية تجمّد الـAgent لو هو اللي يشغل الأمر. و–ignore-agent-tools عشان ما يفشل بسبب وكلاء مو مثبتة عندك. والأمر يشتغل بدون إنترنت لأن القوالب داخل الحزمة.
الأمر طلع لك 30 ملف. الأهم منها مجلد .opencode/commands/ وفيه عشر ملفات تتحول لأوامر داخل opencode، و.specify/memory/constitution.md اللي بنملاه بعد شوي، و.specify/templates/ وهي القوالب اللي تفرض البنية على مخرجات النموذج.
آخر شيء ملف opencode.json في جذر المشروع عشان النموذج المجاني يكون الافتراضي
json
{
"$schema": "https://opencode.ai/config.json",
"model": "opencode/muse-spark-1.3-contributor-free",
"small_model": "opencode/muse-spark-1.3-contributor-free",
"permission": { "edit": "allow", "bash": "allow", "skill": { "speckit-*": "allow" } }
}الصلاحيات هنا مفتوحة لأن المشروع تجريبي ومعزول. في شغل حقيقي خل bash وedit على ask مثل ما شرحنا في قسم الأمان في مقال opencode. وتذكر إن opencode يقرأ الإعدادات والمهارات وقت التشغيل فقط، فأعد تشغيله بعد أي تغيير.
شغل opencode داخل المجلد وبتشوف النموذج في شريط الحالة، والأوامر /speckit.* تظهر لك أول ما تكتب /:
المرحلة الصفر الدستور
أنا سويت الدورة كلها بالوضع غير التفاعلي opencode run –command عشان كل خطوة تنعاد من سكربت. داخل الواجهة تكتب نفس الشيء كأمر /speckit.constitution ….
bash
opencode run --auto --command speckit.constitution "Principles: keep it simple, every endpoint has tests (pytest), follow REST conventions, no premature abstraction, small commits"
الـAgent قرأ القالب عبر سكربت resolve-template.ps1 وكتب constitution.md بخمسة مبادئ مرقمة وقسم حوكمة ورقم إصدار 1.0.0. اكتب في الدستور اللي ما تبي تناقشه مع الـAgent كل مرة: معايير الاختبار، نمط الـAPI، وش ممنوع يضيف. خمسة مبادئ كافية، عشرين بتصير مهمله.
المرحلة الأولى: المطلوب
bash
opencode run --auto --command speckit.specify "Build a REST API for a personal todo list. Users can create a task with a title and optional due date, list tasks (optionally only open ones), mark a task done, and delete a task. No authentication yet."
لاحظ آخر سطرين. الـAgent كتب spec.md وقائمة تحقق requirements.md وفحص المتطلبات ضدها: 16/16 وبدون أي علامة [NEEDS CLARIFICATION]. وهذا مقطع من المتطلبات نفسها
markdown
### User Story 1 - Create a task (Priority: P1)
1. Given an empty task list, When the user creates a task with title "Buy milk",
Then the task is saved as open and returned with its title and a unique identifier.
3. Given a task creation attempt with a missing or blank title, When submitted,
Then the request is rejected with a clear validation error and no task is created.
- FR-001: System MUST allow users to create a task with a required non-blank title.
- FR-006: System MUST allow users to list only open tasks via an open-only filter option.افتح الملف واقرأه الحين. هذي أهم مراجعة في الدورة كلها وأرخصها. ولو لقيت شيء غامض شغّل /speckit.clarify ويسألك أسئلة منظمة قبل الخطة.
المرحلة الثانية: الخطة
هنا بس تدخل التقنية
bash
opencode run --auto --command speckit.tasks
20 مهمة من T001 إلى T020 في سبع مراحل، مجمعة حسب قصة المستخدم، وعلامة [P] على اللي يقدر ينفذها بالتوازي، ونقطة تفتيش بعد كل قصة. ولاحظ الجملة الأخيرة في التقرير: لأن الدستور خلى الاختبارات غير قابلة للتفاوض، الـAgent حط لكل قصة مهمة اختبار “تُكتب أولًا ولازم تفشل قبل التنفيذ”. ما طلبت هذا، الدستور طلبه.
المرحلة الرابعة: التنفيذ
bash
opencode run --auto --command speckit.implement
وهذي أحلى لحظة في التجربة. الـAgent كتب اختبارات القصة الأولى، شغلها، فشلت الخمسة (ما فيه route أصلًا)، وبعدها كتب الـhandler ورجع شغلها
وأتأكد بنفسي من داخل opencode. فتحت الجلسة بـopencode –continue وقرأت تقرير الإتمام، وفي الشريط الجانبي: 123.9K رمز و$0.00:
الخطوة اللي بعدها في المنهجية /speckit.converge: يقارن الكود بالمتطلبات والخطة ويضيف اللي ناقص كمهام، وتكرر التنفيذ لين يقول Converged.
الجولة الثانية: ميزة فوق كود موجود
الـAPI بدون واجهة ما يلمسه أحد، وهذي بالضبط الحالة الواقعية في الشغل ميزة جديدة على كود قائم. أعدت الأوامر الأربعة نفسها بمواصفة جديدة صفحة HTML وحدة تخدم من /، بدون إطار عمل ولا CDN، تشتغل بالكيبورد وعلى الجوال، ومعها وضع تجريبي.
bash
opencode run --auto --command speckit.specify "Add a web UI for the existing todo API, served by the same FastAPI app at the root path '/'. A single HTML page (no build step, no framework, no external CDN) where the user can add a task with a title and optional due date, see the list, toggle 'open only', mark a task done, and delete a task. It must be usable with keyboard only and on a phone-sized screen. It must also support a standalone demo mode (open the same HTML file directly or add ?demo=1) where tasks live in the browser memory instead of the API, so the page can be embedded in documentation."
opencode run --auto --command speckit.plan "Vanilla HTML + CSS + JS in one file src/todo_api/static/index.html, mounted with FastAPI StaticFiles; GET / returns the page. A tiny fetch-based client for the existing endpoints. Demo mode = in-memory array behind the same client interface, selected when ?demo=1 or when the page is opened from file://. Keep the API contract untouched. pytest: add a test that GET / returns 200 text/html."
opencode run --auto --command speckit.tasks
opencode run --auto --command speckit.implement
22 مهمة، 22 اختبار كلها خضراء، سبع دقائق و44 ثانية للدورة كاملة، وثلاث commits نظيفة. ولاحظ في research.md الثاني قرار R5: الـAgent قرر ما يكتب اختبارات متصفح وكتب ليش. حتى القرارات السلبية موثقة.
النتيجة: جربها بنفسك
هذي الصفحة اللي بناها الـAgent ، ملف index.html واحد من 323 سطر، مضمنة هنا بوضع العرض التجريبي اللي قلته في المتطلبات. أضف مهمة، علمها منجزة، فعل Show open only، وجربها بالكيبورد بس
ونفس الملف بدون أي تعديل
bash
uv run uvicorn todo_api.main:app --port 8000
كل سطر في السجل جاء من نقرة حقيقية في المتصفح ثلاث مهام انضافت (POST /tasks بـ201)، ووحدة تغيرت الى منجزة (PATCH /tasks/1/done)، وقراءة القائمة بعد كل تغيير. من جملة وحدة في المتطلبات إلى واجهة شغالة، والمسار كله موثق في specs/.
الأمان قبل ما تشغلها على شغلك
نقطة أخيرة لأهل الشغل. –auto والصلاحيات المفتوحة مناسبة لتجربة مثل هذي، لكن على مستودع حقيقي خل الـAgent يستأذن قبل التعديل والتنفيذ، وامنع اللي ما يرجع
json
{
"permission": {
"edit": "ask",
"bash": { "*": "ask", "git *": "allow", "rm *": "deny" }
}
}ومع Spec Kit عندك بوابات مراجعة جاهزة اقرأ spec.md قبل الخطة، وplan.md قبل المهام، وشغل /speckit.analyze قبل التنفيذ. كل مرحلة أرخص من اللي بعدها بعشر مرات.
الزبدة
السؤال اللي بدأنا فيه وين تروح النية لما يكتب الـAgent الكود؟ الحين الجواب ملفات. دستور فيه مبادئك، مواصفة تراجعها قبل الكود، خطة كل قرار فيها له سبب، مهام مرقمة تتعلم [X] وحدة وحدة، وكود واختبارات في آخر السلسلة مو أولها. ونفس الأربع أوامر تشتغل على ميزة جديدة فوق كود موجود، ومع أي وكيل، وبنموذج مجاني.
الأرقام من التجربة: دورتان، 42 مهمة، 22 اختبار ناجح، نحو 13 دقيقة من وقت النموذج، و$0.00.
نصيحتي نفسها دايم. ابدأ بمشروع صغير مثل هذا، واقرأ المتطلبات بنفسك قبل ما تضغط implement. الـAgent ينجز، لكن “وش نبني” قرارك أنت، وهذا بالضبط الجزء اللي قلنا في مقال Vibe Coding إن الذكاء الاصطناعي ما يقدر يسويه بدالك.
في مقال قادم إن شاء الله نجرب امتداد bug على خلل حقيقي، ونشوف كيف يفرض عليك التشخيص قبل الإصلاح.
ملحق: مهارة speckit-init بنسخة opencode
احفظها في ~/.config/opencode/skills/speckit-init/SKILL.md:
yaml
---
name: speckit-init
description: 'Scaffold a Spec Kit (spec-driven development) project for OpenCode by running `specify init --integration opencode`. USE FOR: starting a new spec-kit project, bootstrapping spec-driven development in an existing repo, installing spec-kit templates/scripts/commands for OpenCode. DO NOT USE FOR: managing extensions/presets/bundles of an already-initialized project (use the speckit-extension / speckit-preset / speckit-bundle skills instead).'
argument-hint: 'project name (or "." / --here for current directory)'
---
# Spec Kit — init (OpenCode edition)
Initialize a spec-driven development project for **OpenCode** with the
**Specify CLI** (`specify`). Always target the OpenCode integration:
`--integration opencode`. This installs the spec-kit slash commands as OpenCode
command files under `.opencode/commands/speckit.<cmd>.md`.
## Prerequisite
`specify --version` — if missing, use the **speckit-cli-setup** skill first.
## How to invoke
Always pass `--script` (`sh` on macOS/Linux, `ps` on Windows) and `--ignore-agent-tools`.
specify init <project-name> --integration opencode --script sh --ignore-agent-tools
specify init --here --integration opencode --script sh --ignore-agent-tools --force
specify init <project-name> --integration opencode --script sh --non-interactive
## Notes
- After init, point the user at `.opencode/commands/` and `.specify/`.
- Tell the user to restart OpenCode so the new `/speckit.*` commands appear.
- Suggest `specify check` to verify the environment.المصادر: github/spec-kit وملف spec-driven.md، github/spec-kit-copilot وملف AGENTS.md فيه، وتوثيق opencode: Skills وConfig وZen.
Originally published on X.
