ثلاث ملفات قبل أي مشروع فايب كودينج
غياب هذه الملفات هو السبب الحقيقي لموت أغلب المشاريع.
لو سألت أي شخص ليش تعثّر مشروعه مع كلود أو Cursor، الجواب في الغالب مو "الأداة ما فهمت"، الجواب إنه ما أعطاها سياقاً تفهم منه. كل جلسة جديدة تبدأ من الصفر تماماً، كأن كلود ما رأى مشروعك في حياته. ثلاث ملفات نصية بسيطة تحل هذه المشكلة من الجذر، وتخلي الأداة تشتغل كأنها كانت معك من اليوم الأول.
🧩 إيش هو بالضبط
الفكرة مباشرة: الذكاء الاصطناعي (AI) لا يتذكر بين الجلسات. كل مرة تفتح محادثة جديدة، كلود يبدأ نظيفاً بدون أي معرفة بمشروعك، قراراتك، أو الأخطاء اللي تعبت فيها الأسبوع الماضي. الملفات الثلاثة هي الذاكرة الدائمة اللي تعوّض هذا الغياب.
تخيّل إنك عندك طباخ ممتاز في مطعمك، بس كل يوم تجيه ناسياً كل شيء، مو عارف إيش القائمة، مو عارف مين الزبائن المعتادين، مو عارف اللي اتفقتم عليه بالأمس. لو كتبت له دليلاً ثابتاً يقرأه أول ما يدخل الشغل، المشكلة تنحل. الملفات الثلاثة هي هذا الدليل، موجود دائماً في مجلد مشروعك.
⚙️ كيف تشتغل الملفات الثلاثة
الملف الأول هو الأهم وهو CLAUDE.md أو AGENTS.md. يوضع في جذر مشروعك (Root Folder) ويقرأه كلود تلقائياً في بداية كل جلسة. فيه تكتب كل شيء ثابت عن مشروعك: المكدس التقني (Tech Stack)، القواعد اللي لا تُكسر، والأخطاء اللي لا تريد تكرارها.
📄 CLAUDE.md يحتوي على:
🧱 المكدس التقني بالتفصيل مع الإصدارات، مثلاً: Next.js 14 مع App Router، وSupabase للقاعدة والمصادقة
🚫 قائمة الأشياء المحظورة، مثلاً: "لا تستخدم any في TypeScript إطلاقاً، لا تثبّت حزمة جديدة بدون إذن"
🎯 وصف المشروع في جملتين، من هو المستخدم وإيش المشكلة اللي تحلها
الملف الثاني هو spec.md أو PRD.md. هذا ملف المواصفات. فيه تصف بالضبط إيش تبني، مين يستخدمه، وإيش هي الميزات الأساسية. لما كلود يفهم إيش المنتج يحاول يحقق، قراراته التقنية تصير أذكى وأكثر اتساقاً مع هدفك الفعلي.
📋 spec.md يحتوي على:
👤 من هو المستخدم المستهدف بالضبط وإيش مشكلته
✨ الميزات الأساسية مرتّبة حسب الأولوية
🚧 ما هو خارج النطاق الحين، يعني إيش لن تبنيه في هذه المرحلة حتى يوقف كلود عن اقتراح أشياء تشتت التركيز
الملف الثالث هو TASKS.md أو PROGRESS.md. هذا هو المخطط الحي. تحدّثه في نهاية كل جلسة. فيه المهام المكتملة، اللي يُشتغل عليها الحين، واللي جاية. هذا الملف وحده يمنع 80% من الارتباك والتكرار بين الجلسات. 📌
📝 TASKS.md يحتوي على:
✅ المهام المكتملة مع ملاحظة قصيرة عن الطريقة
🔄 المهمة اللي يُشتغل عليها الحين بتفاصيل كافية يكملها أي شخص
📍 المهام القادمة مرتّبة بالأولوية
🌍 وين تشوفه في حياتك
هذا الإطار يستخدمه مطورون في مشاريع تجارية حقيقية وليس نظرية:
🛒 مشاريع التجارة الإلكترونية: CLAUDE.md يحتوي على قواعد الـ API الخاص بالدفع والمخزون اللي كلود لازم يحترمها في كل طلب
📱 تطبيقات الموبايل: spec.md يحدد بالضبط إيش يختلف بين نسخة iOS وAndroid حتى لا تختلط القرارات
🤖 مشاريع الذكاء الاصطناعي: TASKS.md يتابع تجارب النماذج والنتائج حتى ما تعيد تجربة شيء جربته قبل
🏢 المشاريع الجماعية: الملفات الثلاثة تصبح مرجعاً مشتركاً للفريق كله وتضمن إن كلود يشتغل بنفس الأساس مع كل شخص
🛠️ الأدوات اللي تستخدمها فعلاً
🔧 Claude Code
هو واجهة كلود المخصصة للمطورين من Anthropic. الأداة الأصلية اللي تقرأ CLAUDE.md تلقائياً في كل جلسة بدون أي إعداد إضافي، وهي أقرب تطبيق مباشر لهذا الإطار.
كيف تبدأ:
1️⃣ ثبّت الـ CLI عبر الطرفية بالأمر: npm install -g @anthropic-ai/claude-code
2️⃣ شغّله داخل مجلد مشروعك بالأمر: claude
3️⃣ أنشئ ملف CLAUDE.md في جذر المشروع وكلود يقرأه تلقائياً من الجلسة الجاية
🔧 Cursor
محرر كود (Code Editor) مبني على VS Code ومدمج فيه ذكاء اصطناعي قوي داخل بيئة التطوير نفسها. يدعم ملف AGENTS.md أو .cursorrules كسياق ثابت يُقرأ في كل محادثة.
كيف تبدأ:
1️⃣ حمّل Cursor من الموقع الرسمي: cursor.com
2️⃣ افتح مجلد مشروعك داخله
3️⃣ أنشئ ملف AGENTS.md في جذر المشروع، Cursor يقرأه تلقائياً في كل محادثة ذكاء اصطناعي جديدة داخل هذا المشروع
💡 جرّب بنفسك: خطوة بخطوة
السيناريو: عندك مشروع فايب كودينج شتغلت عليه أكثر من جلسة وكلود يبدأ من الصفر كل مرة. إليك كيف تحل هذا الحين في عشرين دقيقة.
1️⃣ افتح مجلد مشروعك وأنشئ ملف باسم CLAUDE.md. اكتب فيه ثلاثة أشياء: اسم المشروع وهدفه في جملتين، المكدس التقني اللي تستخدمه مع الإصدارات بالضبط، وقائمة من ثلاثة إلى خمسة قواعد لا تريد كلود يكسرها. لا تزيد على صفحة واحدة.
2️⃣ أنشئ ملف ثانٍ باسم spec.md. اكتب فيه فقرة واحدة تصف من هو مستخدمك وإيش مشكلته. ثم أضف قائمة بالميزات الأساسية الثلاثة أو الأربعة اللي تريد الوصول إليها في هذه المرحلة. في الأسفل أضف قسم "خارج النطاق" وفيه اذكر إيش لن تبنيه الآن.
3️⃣ أنشئ ملف ثالث باسم TASKS.md. قسّمه إلى ثلاثة أقسام: "مكتمل" و"جاري" و"قادم". في المكتمل اذكر كل شيء أنجزته. في جاري اكتب المهمة اللي تشتغل عليها الحين مع تفاصيل كافية. في القادم رتّب مهامك القادمة بالأولوية.
4️⃣ افتح Claude Code أو Cursor في نفس المجلد وابدأ جلسة جديدة من دون ما تقول أي شيء في البداية. لاحظ كيف إن كلود في أول رد يُظهر فهماً حقيقياً لمشروعك، مكدسك، والمرحلة اللي أنت فيها.
وش تسوي بعد ذا
✅ افتح أي مشروع فايب كودينج عندك الحين وأنشئ الملفات الثلاثة، حتى لو بدأت بمحتوى بسيط
✅ في نهاية كل جلسة، خصص دقيقتين لتحديث TASKS.md قبل ما تغلق المحرر
✅ اسأل نفسك: لو أعطيت هذه الملفات لمطور ما شاف مشروعك قبل، يقدر يكمل شغلك؟
المشاريع لا تموت لأن الذكاء الاصطناعي غبي، تموت لأن السياق ضاع.
———— English ————
Three Files Before Any Vibe Coding Project
The real reason most AI coding projects stall has nothing to do with the model.
If you have started a project with Claude or Cursor, built real momentum over a few sessions, then come back the next day to find the AI talking about your project like a stranger, you have already hit this problem. Every new session starts from zero. The model has no memory of your architecture decisions, your preferences, or the mistakes you spent an hour fixing last week. Three plain text files solve this permanently, and they take less than thirty minutes to set up.
What it actually is
This framework is not a productivity system or a workflow template. It is a persistent context layer that lives inside your project folder and tells the AI everything it needs to know before a single line of code gets written. Think of it like an employee handbook sitting open on the desk. Every time a new shift starts, the AI reads it first, then gets to work.
The three files are CLAUDE.md (or AGENTS.md), spec.md, and TASKS.md. Each one covers a different layer of memory: who you are as a developer working on this project, what you are building, and where you stand right now.
How it works
The system depends on one mechanic: most modern AI coding tools read a special file at session start before you type your first message. Claude Code reads CLAUDE.md automatically. Cursor reads AGENTS.md or .cursorrules. That file becomes the AI's baseline understanding for everything it does in that session.
Here is what each file does and what belongs in it:
📄 CLAUDE.md carries your project context and constraints
This file sits in the root of your project. It tells the AI your tech stack, your rules, and your non-negotiable preferences. It is the most important of the three because it prevents the AI from making architectural decisions that contradict choices you already made and spent time on.
What belongs in it:
🧱 Your exact tech stack with versions (for example: Next.js 14 with App Router, Supabase for auth and the database, Tailwind for styling)
🚫 A short list of things the AI must never do (for example: "never use any in TypeScript," "never install new packages without asking first")
🎯 A description of the project in two sentences, covering who the user is and what problem the product solves
📋 spec.md carries what you are building
This file describes the product, not the code. When the AI understands what you are actually trying to ship, it makes better technical decisions and stops suggesting patterns or features that drift away from your actual goal.
What belongs in it:
👤 Who the user is and what specific problem they have
✨ The core features ranked by priority for the current version
🚧 A clear out of scope section so the AI does not suggest scope creep you will have to walk back later
📝 TASKS.md carries where you are right now
This is the living document. You update it at the end of every session. It tells the AI what is done, what is in progress, and what comes next. Without this file, every session begins with a long explanation of your current state before any real work happens.
What belongs in it:
✅ Completed tasks with a short note on how they were implemented
🔄 The current task with enough detail that someone new could pick it up mid-way
📌 Upcoming tasks ranked by priority
Where you see it
This pattern shows up across different real project types:
🛒 E-commerce builds: CLAUDE.md holds the payment API rules and inventory logic the AI must respect on every request, so it never generates code that skips a validation step
📱 Mobile apps: spec.md defines the exact feature differences between iOS and Android versions so the AI never confuses the two platforms mid-session
🤖 AI wrapper products: TASKS.md tracks which prompt variations were tested and what the results were, preventing redundant experiments
🏢 Team projects: all three files become a shared foundation so every team member prompts the AI from the same starting point and gets consistent behavior
🛠️ Tools you actually use
🔧 Claude Code
Claude Code is Anthropic's official CLI and editor integration built for developers. It reads CLAUDE.md automatically at the start of each session, which makes it the most direct implementation of this three-file system with zero additional configuration.
How to get started:
1️⃣ Install via terminal with: npm install -g @anthropic-ai/claude-code
2️⃣ Navigate to your project folder and run: claude
3️⃣ Create CLAUDE.md in your project root. Claude Code picks it up immediately on the next session start.
🔧 Cursor
Cursor is a code editor built on VS Code with an AI layer deeply integrated into the editing environment. It supports AGENTS.md and .cursorrules as persistent context files that load automatically in every new AI chat session inside that project.
How to get started:
1️⃣ Download Cursor from cursor.com
2️⃣ Open your project folder inside Cursor
3️⃣ Create AGENTS.md in the project root. Cursor reads it at the start of every new AI conversation in that workspace.
💡 Try it yourself: step by step
Scenario: you have a vibe coding project you have been working on across multiple sessions and the AI keeps losing your context. Here is how to fix it in the next twenty minutes.
1️⃣ Open your project folder and create a file called CLAUDE.md. Write three things inside: the name and purpose of the project in two sentences, the exact tech stack you are using with version numbers, and a short list of rules the AI must follow without exception. Keep it under one page.
2️⃣ Create a second file called spec.md. Write one paragraph describing what you are building and for whom. Then add a prioritized list of the three or four features that define the current version of the product. Add a short section at the bottom called "Out of Scope" and list what you are not building right now.
3️⃣ Create a third file called TASKS.md. Add three sections: Completed, In Progress, and Up Next. Under Completed, write everything you have already built with a brief note on implementation. Under In Progress, describe what you are working on now in enough detail that someone else could continue it. Under Up Next, list your next tasks in order of priority.
4️⃣ Open Claude Code or Cursor in the same folder and start a fresh session without typing anything first. Watch how the AI's first response already reflects your stack, your constraints, and your current progress. The difference from a session without these files is immediate and obvious.
What to do next
✅ Create the three files in your current project today, even if they start mostly empty and you fill them in over the next few sessions
✅ At the end of your next coding session, spend two minutes updating TASKS.md before you close the editor
✅ Ask yourself: if you handed these three files to a developer who had never seen your project, could they continue where you left off?
Your project's memory is now something you control.