لماذا يبدو كود كلود مستقرًا للغاية: تعمق مطور في تصميم التخزين المحلي الخاص بها

انتشر كود كلود في كل مكان مؤخرًا. يستخدمه المطورون لشحن الميزات بشكل أسرع، وأتمتة سير العمل، ووضع نماذج أولية للعوامل التي تعمل بالفعل في مشاريع حقيقية. والأمر الأكثر إثارة للدهشة هو عدد الأشخاص غير المبرمجين الذين قفزوا أيضاً - حيث قاموا ببناء الأدوات، وتوصيل المهام، والحصول على نتائج مفيدة دون أي إعداد تقريباً. من النادر رؤية أداة برمجة ذكاء اصطناعي تنتشر بهذه السرعة عبر العديد من مستويات المهارة المختلفة.

لكن ما يبرز حقاً هو مدى استقرارها. يتذكر Claude Code ما حدث عبر الجلسات، وينجو من الأعطال دون فقدان التقدم، ويتصرف كأداة تطوير محلية أكثر من كونه واجهة دردشة. تأتي هذه الموثوقية من كيفية تعامله مع التخزين المحلي.

فبدلاً من التعامل مع جلسة البرمجة على أنها دردشة مؤقتة، يقوم Claude Code بقراءة وكتابة ملفات حقيقية، ويخزن حالة المشروع على القرص، ويسجل كل خطوة من خطوات عمل الوكيل. يمكن استئناف الجلسات أو فحصها أو التراجع عنها دون تخمين، ويبقى كل مشروع معزولاً بشكل نظيف - مما يجنبك مشاكل التلوث المتبادل التي تواجهها العديد من أدوات الوكيل.

في هذا المنشور، سنلقي نظرة فاحصة على بنية التخزين الكامنة وراء هذا الاستقرار، ولماذا تلعب دوراً كبيراً في جعل Claude Code يبدو عملياً للتطوير اليومي.

التحديات التي يواجهها كل مساعد ترميز ذكاء اصطناعي محلي

قبل شرح كيفية تعامل Claude Code مع التخزين، دعونا نلقي نظرة على المشكلات الشائعة التي تواجهها أدوات ترميز الذكاء الاصطناعي المحلية. تظهر هذه المشاكل بشكل طبيعي عندما يعمل المساعد مباشرةً على نظام الملفات الخاص بك ويحتفظ بالحالة مع مرور الوقت.

1. تختلط بيانات المشروع عبر مساحات العمل.

يقوم معظم المطورين بالتبديل بين عدة مستودعات على مدار اليوم. إذا كان المساعد ينقل الحالة من مشروع إلى آخر، يصبح من الصعب فهم سلوكه ويسهل عليه وضع افتراضات غير صحيحة. يحتاج كل مشروع إلى مساحة نظيفة ومعزولة خاصة به للحالة والتاريخ.

2. يمكن أن تتسبب الأعطال في فقدان البيانات.

أثناء جلسة البرمجة، ينتج المساعد دفقًا مستمرًا من تعديلات البيانات المفيدة - تعديلات الملفات، واستدعاءات الأدوات، والخطوات الوسيطة. إذا لم يتم حفظ هذه البيانات على الفور، يمكن أن يؤدي التعطل أو إعادة التشغيل القسري إلى محوها. يقوم النظام الموثوق بكتابة الحالة المهمة على القرص بمجرد إنشائها حتى لا يضيع العمل بشكل غير متوقع.

3. ليس من الواضح دائمًا ما فعله الوكيل بالفعل.

تتضمن الجلسة النموذجية العديد من الإجراءات الصغيرة. بدون سجل واضح ومرتب لتلك الإجراءات، من الصعب تتبع كيفية وصول المساعد إلى مخرجات معينة أو تحديد الخطوة التي حدث فيها خطأ ما. السجل الكامل يجعل تصحيح الأخطاء ومراجعتها أكثر سهولة.

4. يتطلب التراجع عن الأخطاء الكثير من الجهد.

في بعض الأحيان يقوم المساعد بإجراء تغييرات لا تعمل تمامًا. إذا لم يكن لديك طريقة مدمجة للتراجع عن هذه التغييرات، فسينتهي بك الأمر بالبحث يدويًا عن التعديلات عبر الريبو. يجب أن يتتبع النظام تلقائيًا ما تم تغييره حتى تتمكن من التراجع عنه بشكل نظيف دون بذل جهد إضافي.

5. تحتاج المشاريع المختلفة إلى إعدادات مختلفة.

تختلف البيئات المحلية. فبعض المشاريع تتطلب أذونات أو أدوات أو قواعد دليل محددة؛ والبعض الآخر لديه برامج نصية أو سير عمل مخصص. يحتاج المساعد إلى احترام هذه الاختلافات والسماح بإعدادات لكل مشروع مع الحفاظ على اتساق سلوكه الأساسي.

مبادئ تصميم التخزين الكامنة وراء كلود كود

تصميم تخزين كلود كود مبني على أربع أفكار مباشرة. قد تبدو هذه الأفكار بسيطة، لكنها معًا تعالج المشاكل العملية التي تظهر عندما يعمل مساعد الذكاء الاصطناعي مباشرةً على جهازك وعبر مشاريع متعددة.

1. يحصل كل مشروع على مساحة تخزين خاصة به.

يربط كلود كود جميع بيانات الجلسة بدليل المشروع الذي ينتمي إليه. وهذا يعني أن المحادثات والتعديلات والسجلات تبقى مع المشروع الذي أتت منه ولا تتسرب إلى مشاريع أخرى. إن إبقاء التخزين منفصلًا يجعل من السهل فهم سلوك المساعد ويجعل من السهل فحص أو حذف البيانات الخاصة بريبو معين.

2. يتم حفظ البيانات على القرص مباشرةً.

بدلًا من الاحتفاظ ببيانات التفاعل في الذاكرة، يكتب Claude Code البيانات على القرص فور إنشائها. يتم إلحاق كل حدث - رسالة أو استدعاء أداة أو تحديث حالة - كمدخل جديد. إذا تعطل البرنامج أو تم إغلاقه بشكل غير متوقع، فإن كل شيء تقريبًا يظل موجودًا. هذا النهج يحافظ على استمرارية الجلسات دون إضافة الكثير من التعقيد.

3. كل إجراء له مكان واضح في التاريخ.

يربط كود كلود كود كل رسالة وإجراء أداة بالإجراء الذي يسبقها، مما يشكل تسلسلاً كاملاً. هذا التاريخ المرتب يجعل من الممكن مراجعة كيفية تطور الجلسة وتتبع الخطوات التي أدت إلى نتيجة محددة. بالنسبة للمطورين، فإن وجود هذا النوع من التتبع يجعل تصحيح الأخطاء وفهم سلوك الوكيل أسهل بكثير.

4. من السهل التراجع عن التعديلات البرمجية.

قبل أن يقوم المساعد بتحديث ملف ما، يحفظ Claude Code لقطة من حالته السابقة. إذا اتضح أن التغيير خاطئ، يمكنك استعادة الإصدار السابق دون البحث في الريبو أو تخمين ما تغير. شبكة الأمان البسيطة هذه تجعل التعديلات التي تعتمد على الذكاء الاصطناعي أقل خطورة بكثير.

تخطيط التخزين المحلي لكود كلود كود

يخزن كلود كود جميع بياناته المحلية في مكان واحد: الدليل الرئيسي الخاص بك. هذا يحافظ على إمكانية التنبؤ بالنظام ويسهل فحصه أو تصحيحه أو تنظيفه عند الحاجة. يتم بناء تخطيط التخزين حول مكونين رئيسيين: ملف تكوين عام صغير ودليل بيانات أكبر حيث تعيش جميع الحالات على مستوى المشروع.

مكونان أساسيان:

• ~/.claude.jsonيخزن التكوين العام والاختصارات العامة، بما في ذلك تعيينات المشروع وإعدادات خادم MCP والمطالبات المستخدمة مؤخرًا.

• ~/.claude/دليل البيانات الرئيسي، حيث يخزِّن كلود كود المحادثات وجلسات المشروع والأذونات والمكونات الإضافية والمهارات والمحفوظات وبيانات وقت التشغيل ذات الصلة.

بعد ذلك، دعنا نلقي نظرة فاحصة على هذين المكونين الأساسيين.

(1) التكوين العام: ~/.claude.json

يعمل هذا الملف كفهرس وليس مخزن بيانات. إنه يسجل المشاريع التي عملت عليها، والأدوات المرفقة بكل مشروع، والمطالبات التي استخدمتها مؤخرًا. لا يتم تخزين بيانات المحادثة نفسها هنا.

{
  "projects": {
    "/Users/xxx/my-project": {
      "mcpServers": {
        "jarvis-tasks": {
          "type": "stdio",
          "command": "python",
          "args": ["/path/to/run_mcp.py"]
        }
      }
    }
  },
  "recentPrompts": [
    "Fix the bug in auth module",
    "Add unit tests"
  ]
}

(2) دليل البيانات الرئيسي: ~/.claude/

الدليل ~/.claude/ هو المكان الذي توجد فيه معظم الحالة المحلية لكلود كود. يعكس هيكله بعض أفكار التصميم الأساسية: عزل المشروع، والمثابرة الفورية، والاسترداد الآمن من الأخطاء.

~/.claude/
├── settings.json                    # Global settings (permissions, plugins, cleanup intervals)
├── settings.local.json              # Local settings (machine-specific, not committed to Git)
├── history.jsonl                    # Command history
│
├── projects/                        # 📁 Session data (organized by project, core directory)
│   └── -Users-xxx-project/          # Path-encoded project directory
│       ├── {session-id}.jsonl       # Primary session data (JSONL format)
│       └── agent-{agentId}.jsonl    # Sub-agent session data
│
├── session-env/                     # Session environment variables
│   └── {session-id}/                # Isolated by session ID
│
├── skills/                          # 📁 User-level skills (globally available)
│   └── mac-mail/
│       └── SKILL.md
│
├── plugins/                         # 📁 Plugin management
│   ├── config.json                  # Global plugin configuration
│   ├── installed_plugins.json       # List of installed plugins
│   ├── known_marketplaces.json      # Marketplace source configuration
│   ├── cache/                       # Plugin cache
│   └── marketplaces/
│       └── anthropic-agent-skills/
│           ├── .claude-plugin/
│           │   └── marketplace.json
│           └── skills/
│               ├── pdf/
│               ├── docx/
│               └── frontend-design/
│
├── todos/                           # Task list storage
│   └── {session-id}-*.json          # Session-linked task files
│
├── file-history/                    # File edit history (stored by content hash)
│   └── {content-hash}/              # Hash-named backup directory
│
├── shell-snapshots/                 # Shell state snapshots
├── plans/                           # Plan Mode storage
├── local/                           # Local tools / node_modules
│   └── claude                       # Claude CLI executable
│   └── node_modules/                # Local dependencies
│
├── statsig/                         # Feature flag cache
├── telemetry/                       # Telemetry data
└── debug/                           # Debug logs

هذا التصميم بسيط عن قصد: كل شيء يولده كلود كود يعيش تحت دليل واحد، منظم حسب المشروع والجلسة. لا توجد حالة مخفية مبعثرة حول نظامك، ومن السهل فحصها أو تنظيفها عند الضرورة.

كيف يدير كلود كود التكوين

تم تصميم نظام تهيئة Claude Code حول فكرة بسيطة: الحفاظ على اتساق السلوك الافتراضي عبر الأجهزة، مع السماح للبيئات والمشاريع الفردية بتخصيص ما تحتاج إليه. ولتحقيق ذلك، يستخدم كلود كود نموذج تكوين ثلاثي الطبقات. عندما يظهر الإعداد نفسه في أكثر من مكان، تفوز دائمًا الطبقة الأكثر تحديدًا.

مستويات التكوين الثلاثة

يقوم كلود كود بتحميل التكوين بالترتيب التالي، من الأقل أولوية إلى الأعلى:

┌─────────────────────────────────────────┐
│    Project-level configuration          │  Highest priority
│    project/.claude/settings.json        │  Project-specific, overrides other configs
├─────────────────────────────────────────┤
│    Local configuration                  │  Machine-specific, not version-controlled
│    ~/.claude/settings.local.json        │  Overrides global configuration
├─────────────────────────────────────────┤
│    Global configuration                 │  Lowest priority
│    ~/.claude/settings.json              │  Base default configuration
└─────────────────────────────────────────┘

يمكنك التفكير في ذلك على أنه بدءًا من الإعدادات الافتراضية العامة، ثم تطبيق التعديلات الخاصة بالجهاز، وأخيرًا تطبيق القواعد الخاصة بالمشروع.

بعد ذلك، سنستعرض كل مستوى من مستويات التكوين بالتفصيل.

(1) التكوين العام: ~/.claude/settings.json

يحدد التكوين العام السلوك الافتراضي لـ Claude Code في جميع المشاريع. هذا هو المكان الذي تقوم فيه بتعيين الأذونات الأساسية وتمكين الإضافات وتهيئة سلوك التنظيف.

{
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
  "permissions": {
    "allow": ["Read(**)", "Bash(npm:*)"],
    "deny": ["Bash(rm -rf:*)"],
    "ask": ["Edit", "Write"]
  },
  "enabledPlugins": {
    "document-skills@anthropic-agent-skills": true
  },
  "cleanupPeriodDays": 30
}

(2) التكوين المحلي: ~/.claude/settings.local.json

التكوين المحلي خاص بجهاز واحد. لا يُقصد به أن تتم مشاركته أو التحقق منه في التحكم في الإصدار. هذا يجعله مكانًا جيدًا لمفاتيح واجهة برمجة التطبيقات أو الأدوات المحلية أو الأذونات الخاصة بالبيئة.

{
  "permissions": {
    "allow": ["Bash(git:*)", "Bash(docker:*)"]
  },
  "env": {
    "ANTHROPIC_API_KEY": "sk-ant-xxx"
  }
}

(3) التكوين على مستوى المشروع: project/.claude/settings.json

ينطبق التكوين على مستوى المشروع فقط على مشروع واحد وله الأولوية القصوى. هذا هو المكان الذي تحدد فيه القواعد التي يجب تطبيقها دائمًا عند العمل في هذا المستودع.

{
  "permissions": {
    "allow": ["Bash(pytest:*)"]
  }
}

مع تحديد طبقات التكوين، فإن السؤال التالي هو كيف يقوم كلود كود بتحديد التكوين والأذونات في وقت التشغيل.

يطبقClaude Code التكوين في ثلاث طبقات: يبدأ بالافتراضيات العامة، ثم يطبق التجاوزات الخاصة بالجهاز، وأخيرًا يطبق القواعد الخاصة بالمشروع. عندما يظهر الإعداد نفسه في أماكن متعددة، تكون الأولوية للتكوين الأكثر تحديدًا.

تتبع الأذونات ترتيب تقييم ثابت:

1. رفض - يحظر دائمًا

2. طلب - يتطلب تأكيدًا

3. السماح - يعمل تلقائيًا

4. افتراضي - يطبق فقط في حالة عدم تطابق أي قاعدة

هذا يحافظ على أمان النظام بشكل افتراضي، مع الاستمرار في منح المشاريع والأجهزة الفردية المرونة التي تحتاجها.

تخزين الجلسات: كيف يحتفظ كلود كود ببيانات التفاعل الأساسية

في كلود كود، الجلسات هي الوحدة الأساسية للبيانات. تلتقط جلسة العمل التفاعل الكامل بين المستخدم والذكاء الاصطناعي، بما في ذلك المحادثة نفسها، واستدعاءات الأداة، وتغييرات الملفات، والسياق ذي الصلة. إن كيفية تخزين الجلسات لها تأثير مباشر على موثوقية النظام وقابلية تصحيح الأخطاء والسلامة العامة.

الاحتفاظ ببيانات الجلسات منفصلة لكل مشروع

بمجرد تحديد الجلسات، فإن السؤال التالي هو كيفية تخزين Claude Code لها بطريقة تحافظ على تنظيم البيانات وعزلها.

يعزلClaude Code بيانات الجلسات حسب المشروع. يتم تخزين جلسات كل مشروع تحت دليل مشتق من مسار ملف المشروع.

يتبع مسار التخزين هذا النمط:

~/.claude/projects/ + path-encoded project directory

لإنشاء اسم دليل صالح، يتم استبدال الأحرف الخاصة مثل / والمسافات و ~ بـ -.

على سبيل المثال:

/Users/bill/My Project → -Users-bill-My-Project

يضمن هذا النهج عدم اختلاط بيانات جلسات العمل من مشاريع مختلفة ويمكن إدارتها أو إزالتها على أساس كل مشروع على حدة.

لماذا يتم تخزين جلسات العمل بتنسيق JSONL

يخزنClaude Code بيانات جلسات العمل باستخدام JSONL (خطوط JSONL) بدلاً من JSON القياسية.

في ملف JSON التقليدي، يتم تجميع جميع الرسائل معًا داخل بنية واحدة كبيرة، مما يعني أنه يجب قراءة الملف بأكمله وإعادة كتابته كلما تغير. في المقابل، يخزن JSONL كل رسالة كسطر خاص بها في الملف. سطر واحد يساوي رسالة واحدة، بدون غلاف خارجي.

الجانب	JSON القياسية	JSONL (خطوط JSON)
كيف يتم تخزين البيانات	بنية واحدة كبيرة	رسالة واحدة لكل سطر
متى يتم حفظ البيانات	عادةً في النهاية	على الفور، لكل رسالة
تأثير التعطل	قد ينقطع الملف بأكمله	يتأثر السطر الأخير فقط
كتابة بيانات جديدة	إعادة كتابة الملف بأكمله	إلحاق سطر واحد
استخدام الذاكرة	تحميل كل شيء	قراءة سطر بسطر

تعمل JSONL بشكل أفضل بعدة طرق رئيسية:

• الحفظ الفوري: تتم كتابة كل رسالة على القرص بمجرد إنشائها، بدلاً من انتظار انتهاء الجلسة.

• مقاومة للأعطال: إذا تعطل البرنامج، قد تُفقد آخر رسالة غير مكتملة فقط. كل شيء مكتوب قبل ذلك يبقى سليماً.

• إلحاق سريع: تتم إضافة رسائل جديدة إلى نهاية الملف دون قراءة أو إعادة كتابة البيانات الموجودة.

• استخدام منخفض للذاكرة: يمكن قراءة ملفات جلسات العمل سطرًا واحدًا في كل مرة، لذلك لا يلزم تحميل الملف بأكمله في الذاكرة.

يبدو ملف جلسة عمل JSONL المبسط بهذا الشكل:

{"type":"user","message":{"role":"user","content":"Hello"},"timestamp":"2026-01-05T10:00:00Z"}
{"type":"assistant","message":{"role":"assistant","content":[{"type":"text","text":"Hi!"}]}}
{"type":"user","message":{"role":"user","content":"Help me fix this bug"}}

أنواع رسائل جلسة العمل

يسجل ملف جلسة العمل كل ما يحدث أثناء التفاعل مع Claude Code. للقيام بذلك بوضوح، فإنه يستخدم أنواع رسائل مختلفة لأنواع مختلفة من الأحداث.

• تمثلرسائل المستخدم المدخلات الجديدة القادمة إلى النظام. وهذا لا يشمل فقط ما يكتبه المستخدم، بل يشمل أيضًا النتائج التي تُرجعها الأدوات، مثل مخرجات أمر shell. من وجهة نظر الذكاء الاصطناعي، كلاهما مدخلات يحتاج إلى الاستجابة لها.

• تلتقطالرسائل المساعدة ما يفعله كلود استجابةً لذلك. تتضمن هذه الرسائل منطق الذكاء الاصطناعي، والنص الذي يولده، وأي أدوات يقرر استخدامها. كما أنها تسجّل تفاصيل الاستخدام، مثل عدد الرموز الرمزية، لتوفير صورة كاملة للتفاعل.

• لقطات محفوظات الملفات هي نقاط تفتيش للسلامة يتم إنشاؤها قبل أن يقوم كلود بتعديل أي ملفات. من خلال حفظ حالة الملف الأصلي أولاً، يتيح كلود كود إمكانية التراجع عن التغييرات إذا حدث خطأ ما.

• توفرالملخصات نظرة عامة موجزة عن الجلسة وترتبط بالنتيجة النهائية. فهي تسهل فهم ما كانت عليه الجلسة دون إعادة تشغيل كل خطوة.

لا تسجل أنواع الرسائل هذه معًا ليس فقط المحادثة، ولكن التسلسل الكامل للإجراءات والتأثيرات التي تحدث أثناء الجلسة.

لجعل هذا الأمر أكثر وضوحًا، دعنا نلقي نظرة على أمثلة محددة لرسائل المستخدم والرسائل المساعدة.

(1) مثال على رسائل المستخدم:

{
  "type": "user",
  "uuid": "7d90e1c9-e727-4291-8eb9-0e7b844c4348",
  "parentUuid": null,
  "sessionId": "e5d52290-e2c1-41d6-8e97-371401502fdf",
  "timestamp": "2026-01-05T10:00:00.000Z",
  "message": {
    "role": "user",
    "content": "Analyze the architecture of this project"
  },
  "cwd": "/Users/xxx/project",
  "gitBranch": "main",
  "version": "2.0.76"
}

(2) مثال رسائل المساعد:

{
  "type": "assistant",
  "uuid": "e684816e-f476-424d-92e3-1fe404f13212",
  "parentUuid": "7d90e1c9-e727-4291-8eb9-0e7b844c4348",
  "message": {
    "role": "assistant",
    "model": "claude-opus-4-5-20251101",
    "content": [
      {
        "type": "thinking",
        "thinking": "The user wants to understand the project architecture, so I need to check the directory structure first..."
      },
      {
        "type": "text",
        "text": "Let me take a look at the project structure first."
      },
      {
        "type": "tool_use",
        "id": "toolu_01ABC",
        "name": "Bash",
        "input": {"command": "ls -la"}
      }
    ],
    "usage": {
      "input_tokens": 1500,
      "output_tokens": 200,
      "cache_read_input_tokens": 50000
    }
  }
}

كيف ترتبط رسائل الجلسة

لا يقوم Claude Code بتخزين رسائل الجلسة كمدخلات معزولة. بدلاً من ذلك، فإنه يربطها معًا لتكوين سلسلة واضحة من الأحداث. تتضمن كل رسالة معرّفًا فريدًا (uuid) ومرجعًا للرسالة التي جاءت قبلها (parentUuid). هذا يجعل من الممكن معرفة ليس فقط ما حدث، ولكن لماذا حدث ذلك.

تبدأ الجلسة برسالة مستخدم، والتي تبدأ السلسلة. يشير كل رد من كلود إلى الرسالة التي تسببت في حدوثها. تتم إضافة مكالمات الأدوات ومخرجاتها بنفس الطريقة، مع ربط كل خطوة بالخطوة التي تسبقها. عندما تنتهي الجلسة، يتم إرفاق ملخص بالرسالة النهائية.

نظرًا لارتباط كل خطوة، يمكن لـ Claude Code إعادة تشغيل التسلسل الكامل للإجراءات وفهم كيفية إنتاج النتيجة، مما يجعل التصحيح والتحليل أسهل بكثير.

تسهيل التراجع عن تغييرات التعليمات البرمجية باستخدام لقطات الملفات

لا تكون التعديلات التي يتم إنشاؤها بالذكاء الاصطناعي صحيحة دائمًا، وأحيانًا تسير في الاتجاه الخاطئ تمامًا. لجعل هذه التغييرات آمنة للتجربة، يستخدم Claude Code نظام لقطات بسيط يتيح لك التراجع عن التعديلات دون البحث في الاختلافات أو تنظيف الملفات يدويًا.

الفكرة واضحة ومباشرة: قبل أن يقوم كلود كود بتعديل ملف ما، يحفظ نسخة من المحتوى الأصلي. إذا تبين أن التعديل كان خطأً، يمكن للنظام استعادة النسخة السابقة على الفور.

ما هي لقطة تاريخ الملف؟

لقطة تاريخ الملف هي نقطة تدقيق تم إنشاؤها قبل تعديل الملفات. وهي تسجل المحتوى الأصلي لكل ملف يوشك كلود على تحريره. تعمل هذه اللقطات كمصدر بيانات لعمليات التراجع والاسترجاع.

عندما يرسل أحد المستخدمين رسالة قد تغير الملفات، يقوم كلود كود بإنشاء لقطة فارغة لتلك الرسالة. قبل التحرير، يقوم النظام بعمل نسخة احتياطية من المحتوى الأصلي لكل ملف مستهدف في اللقطة، ثم يطبق التعديلات مباشرةً على القرص. إذا قام المستخدم بتشغيل عملية التراجع، يستعيد Claude Code المحتوى المحفوظ ويكتب فوق الملفات المعدّلة.

من الناحية العملية، تبدو دورة حياة التعديل القابل للتراجع كما يلي:

1. يرسل المستخدم رسالةيقومكلودكود بإنشاء سجل جديد فارغ file-history-snapshot.

2. كلود يستعد لتعديل الملفاتيحددالنظام الملفات التي سيتم تحريرها ويقوم بعمل نسخة احتياطية من محتواها الأصلي في trackedFileBackups.

3. يقومكلود بتنفيذالتعديليتم إجراء عملياتالتحريروالكتابة، ويتم كتابة المحتوى المعدل على القرص.

4. يقوم المستخدم بتشغيل عملية التراجعيضغطالمستخدم على Esc + Esc، مما يشير إلى أنه يجب التراجع عن التغييرات.

5. تتم استعادة المحتوى الأصلييتم استعادة المحتوى الأصلييقوم كلودكود بقراءة المحتوى المحفوظ من trackedFileBackups ويكتب فوق الملفات الحالية، ويكمل عملية التراجع.

لماذا يعمل التراجع: اللقطات تحفظ الإصدار القديم

يعمل التراجع في كلود كود لأن النظام يحفظ محتوى الملف الأصلي قبل حدوث أي تعديل.

فبدلاً من محاولة عكس التغييرات بعد حدوثها، يتبع كلود كود نهجًا أبسط: فهو ينسخ الملف كما كان موجودًا قبل التعديل ويخزن تلك النسخة في trackedFileBackups. عندما يقوم المستخدم بتشغيل عملية التراجع، يستعيد النظام هذه النسخة المحفوظة ويستبدل الملف الذي تم تعديله.

يوضح الرسم البياني أدناه هذا التدفق خطوة بخطوة:

┌─────────────────────────┐
│    before edit,  app.py │
│    print("old")         │───────→  Backed up into snapshot trackedFileBackups
└─────────────────────────┘
↓
┌──────────────────────────┐
│   After Claude edits     │
│    print(“new”)          │───────→  Written to disk (overwrites the original file)
└──────────────────────────┘
↓
┌──────────────────────────┐
│    User triggers undo    │
│    Press   Esc + Esc     │───────→ Restore “old” content to disk from snapshot
└──────────────────────────┘

كيف تبدو لقطة ملف-تاريخ الملف داخلياً

يتم تخزين اللقطة نفسها كسجل منظم. وهو يلتقط البيانات الوصفية حول رسالة المستخدم، ووقت اللقطة، والأهم من ذلك - خريطة للملفات بمحتوياتها الأصلية.

يوضح المثال أدناه سجلاً واحداً file-history-snapshot تم إنشاؤه قبل أن يقوم كلود بتحرير أي ملفات. يخزّن كل إدخال في trackedFileBackups محتوى الملف قبل التعديل، والذي يُستخدم لاحقًا لاستعادة الملف أثناء عملية التراجع.

{
  "type": "file-history-snapshot",
  "messageId": "7d90e1c9-e727-4291-8eb9-0e7b844c4348",
  "snapshot": {
    "messageId": "7d90e1c9-e727-4291-8eb9-0e7b844c4348",
    "trackedFileBackups": {
      "/path/to/file1.py": "Original file content\ndef hello():\n    print('old')",
      "/path/to/file2.js": "// Original content..."
    },
    "timestamp": "2026-01-05T10:00:00.000Z"
  },
  "isSnapshotUpdate": false
}

مكان تخزين اللقطات ومدة الاحتفاظ بها

• مكان تخزين البيانات الوصفية للقطات: يتم ربط سجلات اللقطات بجلسة عمل محددة ويتم حفظها كملفات JSONL ضمن~/.claude/projects/-path-to-project/{session-id}.jsonl.

• حيث يتم الاحتفاظ بنسخة احتياطية من محتويات الملف الأصلي: يتم تخزين محتوى ما قبل التحرير لكل ملف بشكل منفصل حسب تجزئة المحتوى تحت~/.claude/file-history/{content-hash}/.

• مدة الاحتفاظ باللقطات افتراضيًا: يتم الاحتفاظ ببيانات اللقطات لمدة 30 يومًا، بما يتوافق مع الإعداد العام cleanupPeriodDays.

• كيفية تغيير فترة الاحتفاظ: يمكن تعديل عدد أيام الاحتفاظ عبر الحقل cleanupPeriodDays في ~/.claude/settings.json.

الأوامر ذات الصلة

الأمر / الإجراء	الوصف
إسك + إسك	التراجع عن الجولة الأخيرة من تعديلات الملف (الأكثر استخدامًا)
/ترجيع	الرجوع إلى نقطة تفتيش محددة مسبقًا (لقطة)
/ديف	عرض الاختلافات بين الملف الحالي والنسخة الاحتياطية للملف الحالي واللقطة الاحتياطية

دلائل مهمة أخرى

(1) المكونات الإضافية/ - إدارة المكونات الإضافية

يخزن الدليل plugins/ الإضافات التي تمنح كلود كود قدرات إضافية.

يخزن هذا الدليل الإضافات المثبتة، ومن أين أتت، والمهارات الإضافية التي توفرها تلك الإضافات. كما أنه يحتفظ بنسخ محلية من الإضافات التي تم تنزيلها حتى لا تحتاج إلى جلبها مرة أخرى.

~/.claude/plugins/
├── config.json
│   Global plugin configuration (e.g., enable/disable rules)
├── installed_plugins.json
│   List of installed plugins (including version and status)
├── known_marketplaces.json
│   Plugin marketplace source configuration (e.g., Anthropic official marketplace)
├── cache/
│   Plugin download cache (avoids repeated downloads)
└── marketplaces/
    Marketplace source storage
    └── anthropic-agent-skills/
        Official plugin marketplace
        ├── .claude-plugin/
        │   └── marketplace.json
        │       Marketplace metadata
        └── skills/
            Skills provided by the marketplace
            ├── pdf/
            │   PDF-related skills
            ├── docx/
            │   Word document processing skills
            └── frontend-design/
                Frontend design skills

(2) المهارات/ - مكان تخزين المهارات وتطبيقها

في Claude Code، المهارة هي قدرة صغيرة قابلة لإعادة الاستخدام تساعد كلود على أداء مهمة محددة، مثل العمل مع ملفات PDF، أو تحرير المستندات، أو اتباع سير عمل برمجي.

لا تتوفر جميع المهارات في كل مكان. فبعضها ينطبق على مستوى العالم، في حين أن بعضها الآخر يقتصر على مشروع واحد أو يتم توفيره بواسطة مكون إضافي. يُخزِّن Claude Code المهارات في مواقع مختلفة للتحكم في مكان استخدام كل مهارة.

يُظهر التسلسل الهرمي أدناه كيف يتم تصنيف المهارات حسب النطاق، من المهارات المتاحة عالميًا إلى المهارات الخاصة بالمشروع والمقدمة من قبل المكوّنات الإضافية.

المستوى	موقع التخزين	الوصف
المستخدم	~/.claude/skills/	متاح عالمياً، ويمكن الوصول إليه من قبل جميع المشاريع
المشروع	مشروع/.claude/skills/	متاح فقط للمشروع الحالي، التخصيص الخاص بالمشروع الحالي
المكوّن الإضافي	~/.claude/plugins/ الأسواق/*/المهارات/	مثبت مع المكونات الإضافية، يعتمد على حالة تمكين المكون الإضافي

(3) todos/- تخزين قوائم المهام

يقوم الدليل todos/ بتخزين قوائم المهام التي ينشئها كلود لتتبع العمل أثناء المحادثة، مثل الخطوات التي يجب إكمالها، والعناصر قيد التقدم، والمهام المكتملة.

تُحفظ قوائم المهام كملفات JSON ضمن~/.claude/todos/{session-id}-*.json.يتضمن كل اسم ملف معرّف الجلسة، والذي يربط قائمة المهام بمحادثة معينة.

تأتي محتويات هذه الملفات من الأداة TodoWrite وتتضمن معلومات المهام الأساسية مثل وصف المهمة والحالة الحالية والأولوية والبيانات الوصفية ذات الصلة.

(4) محلي/ - وقت التشغيل المحلي والأدوات المحلية

يحتوي الدليل local/ على الملفات الأساسية التي يحتاجها كلود كود للتشغيل على جهازك.

يتضمن هذا الدليل claude سطر الأوامر القابل للتنفيذ والدليل node_modules/ الذي يحتوي على تبعيات وقت التشغيل. من خلال الاحتفاظ بهذه المكونات محلية، يمكن تشغيل Claude Code بشكل مستقل، دون الاعتماد على الخدمات الخارجية أو التثبيتات على مستوى النظام.

（5） دلائل الدعم الإضافية

• shell-snapshots/: يخزّن لقطات حالة جلسة عمل الصدفة (مثل الدليل الحالي ومتغيرات البيئة)، مما يتيح استرجاع عملية الصدفة.

• خطط/: تخزين خطط التنفيذ التي تم إنشاؤها بواسطة وضع الخطة (على سبيل المثال، التفصيلات التفصيلية لمهام البرمجة متعددة الخطوات).

• statsig/: تخزين تكوينات علامة الميزة بشكل مؤقت (مثل ما إذا كانت الميزات الجديدة ممكّنة) لتقليل الطلبات المتكررة.

• القياس عن بُعد/: تخزين بيانات القياس عن بُعد المجهولة (مثل تكرار استخدام الميزات) لتحسين المنتج.

• التصحيح/: تخزين سجلات التصحيح (بما في ذلك مكدسات الأخطاء وتتبع التنفيذ) للمساعدة في استكشاف الأخطاء وإصلاحها.

الخلاصة

بعد التعمق في كيفية تخزين Claude Code وإدارة كل شيء محليًا، تصبح الصورة واضحة جدًا: تبدو الأداة مستقرة لأن الأساس متين. لا شيء خيالي - مجرد هندسة مدروسة. كل مشروع له مساحة خاصة به، وكل إجراء يتم تدوينه، ويتم نسخ تعديلات الملفات احتياطيًا قبل أن يتغير أي شيء. إنه نوع من التصميم الذي يؤدي عمله بهدوء ويتيح لك التركيز على عملك.

أكثر ما يعجبني هو أنه لا يوجد شيء غامض هنا. كلود كود يعمل بشكل جيد لأن الأساسيات تتم بشكل صحيح. إذا كنت قد حاولت من قبل إنشاء وكيل يلمس ملفات حقيقية، فأنت تعرف مدى سهولة انهيار الأمور - تختلط الحالات، وتختلط الحالات، وتؤدي الأعطال إلى مسح التقدم، ويصبح التراجع تخمينًا. يتجنب Claude Code كل ذلك من خلال نموذج تخزين بسيط ومتسق ويصعب كسره.

بالنسبة للفرق التي تقوم ببناء وكلاء ذكاء اصطناعي محليين أو داخل الشركة، خاصةً في البيئات الآمنة، يوضح هذا النهج كيف أن التخزين القوي والمثابرة يجعلان أدوات الذكاء الاصطناعي موثوقة وعملية للتطوير اليومي.

إذا كنت تصمم وكلاء ذكاء اصطناعيًا محليًا أو محليًا وترغب في مناقشة بنية التخزين أو تصميم الجلسات أو الاستعادة الآمنة بمزيد من التفاصيل، فلا تتردد في الانضمام إلى قناة Slack الخاصة بنا، ويمكنك أيضًا حجز موعد فردي لمدة 20 دقيقة من خلال ساعات عمل Milvus المكتبية للحصول على إرشادات مخصصة.