ملفا AGENTS.md وCLAUDE.md لقاعدة معرفة

AGENTS.md وCLAUDE.md ملفا markdown عاديان يقرؤهما وكلاء البرمجة قبل أن يعملوا في أي مجلد. وفي قاعدة المعرفة، هما المكان الذي تشرح فيه للوكلاء كيف نظّمت ملاحظاتك، وما القواعد التي يجب أن يلتزم بها كل مستند. لا حقول إلزامية فيهما ولا مخطط: تكتب التعليمات بلغة markdown عادية.

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

AGENTS.md

AGENTS.md صيغة مفتوحة لتوجيه وكلاء البرمجة، ترعاها Agentic AI Foundation تحت مظلة Linux Foundation. يقرؤها كثير من وكلاء البرمجة، ومنهم OpenAI Codex وCursor. تضع الملف في جذر مجلدك، ويمكنك أن تضيف غيره في المجلدات الفرعية: يُعتمد ملف AGENTS.md الأقرب إلى الملف الذي يجري تعديله، وما تكتبه في المحادثة يتقدّم عليها جميعًا.

CLAUDE.md

CLAUDE.md هو المقابل في Claude Code. وبحسب وثائق Anthropic، يقرؤه Claude Code من عدة أماكن، الأوسع نطاقًا أولًا:

ويمكن للمؤسسات أيضًا أن تعتمد ملف CLAUDE.md مُدارًا مركزيًا. ولا يُلغي أي ملف غيره: يضمّها Claude Code كلها بعضها إلى بعض، من جذر نظام الملفات نزولًا إلى المجلد الذي شغّلته منه، فتأتي التعليمات الأكثر تحديدًا في الآخر. أما ملفات المجلدات الفرعية فتُحمَّل حين يقرأ Claude ملفًا داخلها. ويمكن لملف CLAUDE.md أن يستورد ملفات أخرى بالصيغة @path/to/file، حتى أربعة مستويات في العمق. وتنصح Anthropic بإبقاء كل ملف دون 200 سطر.

في Knowtarium

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

(تُفتح بحجمها الكامل في علامة تبويب جديدة) (تُفتح بحجمها الكامل في علامة تبويب جديدة)

إن كنت تستخدم أكثر من وكيل، فاكتب قواعدك مرة واحدة في AGENTS.md. فالإصدارات الحديثة من Claude Code تقرأ AGENTS.md من تلقاء نفسها حين لا يوجد CLAUDE.md أو CLAUDE.local.md في المجلد أو فوقه (الإصدار v2.1.277 وما بعده). وإن أردت تعليمات خاصة بـClaude أيضًا، أو كنت تستخدم إصدارًا أقدم، فأنشئ CLAUDE.md بجانبه يستورده:

@AGENTS.md
 
## Claude Code
 
- اعمل في وضع plan عند أي تغيير يمسّ أكثر من ثلاثة مستندات.

يقرأ Claude ملف AGENTS.md المستورَد أولًا، ثم الأسطر التي تحته. وكل وكيل آخر يقرأ AGENTS.md مباشرة، فتبقى القواعد واحدة لا تختلف من وكيل لآخر.

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

بنية المجلدات

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

التسمية

مفهوم واحد في كل ملف، ونمط تسمية واحد. وحين تبدأ أسماء القرارات والاجتماعات بالتاريخ، يرتّب المجلد نفسه بنفسه.

الروابط

اختر أسلوب ربط واحدًا ونصّ عليه. فروابط markdown العادية تعمل في كل أداة، أما [[wikilinks]] فلا تعمل إلا في بعضها. وأخبر الوكلاء أن يحدّثوا الروابط حين ينقلون ملفًا، وأن الربط بمستند لم يكتبه أحد بعد مسموح.

frontmatter لمنشأ المستند وحداثته

هذه القاعدة تغفلها معظم القوالب، مع أنها ما يتيح لك لاحقًا أن تفحص قاعدة معرفة كتبها الوكلاء. اشترط أن يذكر كل مستند من كتبه ومتى يصبح قديمًا. وتعطيك Open Knowledge Format، وهي مواصفة مفتوحة نشرتها Google Cloud، أسماء الحقول: type (الحقل المطلوب الوحيد)، وgenerated، وverified، وstatus، وstale_after، وsources. وحين تعتمد صيغة منشورة، تفهم ملاحظاتك أي أداة تقرأ OKF.

الاستشهاد بالمصادر

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

ما يجب ألّا يفعله الوكلاء أبدًا

اكتب الخطوط الحمراء على شكل قواعد تبدأ بـ«لا… أبدًا»: لا تعلّم شيئًا على أنه راجعه إنسان، ولا تحذف أي شيء، ولا تكتب فوق تعديل أجراه إنسان. وتشير وثائق Anthropic إلى أن الوكيل يلتزم بالتعليمات المحددة والموجزة أكثر من التعليمات العامة.

كيف يسجّل الوكيل مراجعته

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

في Knowtarium

في المجلدات التي فعّلت فيها المراجعة، يحوّل Knowtarium هذه المدخلات إلى مستوى ثقة: مدخل الوكيل يجعل المستند machine-confirmed، ومدخلك يجعله human-reviewed، ووجود الاثنين بعد آخر تغيير يجعله fully verified. وحين توافق هناك على تغيير أجراه وكيل، يكتب التطبيق مدخلك نيابةً عنك.

(تُفتح بحجمها الكامل في علامة تبويب جديدة) (تُفتح بحجمها الكامل في علامة تبويب جديدة)

انسخ هذا إلى AGENTS.md في جذر مجلد ملاحظاتك، ثم عدّل قائمة المجلدات لتطابق مجلداتك. وهو أقصر بكثير من الحدّ الذي تنصح به Anthropic، أي 200 سطر.

---
type: Instructions
title: قواعد للوكلاء
---
 
# قاعدة المعرفة: قواعد للوكلاء
 
هذا المجلد قاعدة معرفة يكتبها الناس والوكلاء معًا.
كل ملف فيه markdown عادي يبدأ بـfrontmatter بصيغة YAML (OKF v0.2).
اقرأ هذا الملف كله قبل أن تغيّر أي شيء.
 
## البنية
 
- في كل مجلد ملف index.md يسرد ما يحويه. اقرأه أولًا.
- يسجّل log.md ما تغيّر، الأحدث أولًا. أضف سطرًا عن كل جلسة.
- company/     الرسالة، والمسرد، وطريقة عملنا
- customers/   الشرائح، وinterviews/ (ملف لكل مقابلة)
- metrics/     ملف لكل مقياس، وcomputations/ للاستعلامات المعتمدة
- decisions/   ملف لكل قرار، باسم YYYY-MM-DD-short-title.md
- references/  نسخ من المواد المصدرية التي تستشهد بها (PDF، CSV، صفحات محفوظة)
- لا تنشئ مجلدًا جديدًا في المستوى الأعلى أبدًا. اسأل أولًا.
 
## البحث عن المعلومات
 
- ابدأ من index.md في الجذر واتبع الروابط. لا تقرأ كل ملف.
- ابحث قبل أن تكتب. إن وجدت مستندًا عن الموضوع، فحدّثه.
 
## التسمية
 
- مفهوم واحد في كل ملف. أسماء الملفات lowercase-with-hyphens.md.
- index.md وlog.md اسمان محجوزان. لا تسمِّ بهما أي مستند.
 
## الروابط
 
- استخدم روابط markdown العادية، ولا تستخدم [[wikilinks]] أبدًا.
- اربط من جذر الحزمة: [التسرّب](/metrics/churn.md).
- لا بأس أن تربط بمستند لم يُكتب بعد. ولا تنشئ
  ملفًا فارغًا لمجرد إصلاح الرابط.
- حين تعيد تسمية ملف أو تنقله، حدّث كل رابط إليه.
 
## Frontmatter
 
يبدأ كل مستند بـfrontmatter. اترك المفاتيح التي لا تعرفها
كما هي تمامًا.
 
```yaml
---
type: Metric                # مطلوب: Metric أو Decision أو Interview أو ...
title: التسرّب
description: جملة واحدة، تُستخدم في index.md وفي البحث.
status: stable              # draft | stable | deprecated
generated: { by: <your-name>/<version>, at: <وقت UTC بصيغة ISO 8601> }
stale_after: <وقت UTC>      # الموعد الذي لا يعود الاقتباس منه بعده آمنًا
sources:
  - id: billing-export
    resource: /references/billing-2026-09.csv
    title: تصدير الفواتير، سبتمبر 2026
---
```
 
- وقّع كل مستند تكتبه أو تغيّره في `generated`.
  وحدّث `generated.at` مع كل تغيير جوهري.
- ضع `stale_after`: 90 يومًا للمقاييس، وسنة واحدة للقرارات.
- يبدأ كل مستند جديد بالقيمة `status: draft`.
 
## المصادر
 
- لا بد لكل رقم وتاريخ واسم واقتباس من مصدر.
- أضف المصدر إلى `sources` بمعرّف `id` قصير وثابت، ثم أشر إليه
  بحاشية بعد المعلومة: انخفض التسرّب إلى 2.4%.[^billing-export]
- لا تستشهد إلا بمصدر فتحته في هذه الجلسة. لا تخترع رابطًا أبدًا.
- إن لم تجد مصدرًا، فاكتب المعلومة تحت
  "## أسئلة مفتوحة" بدل أن تقدّمها على أنها حقيقة.
 
## مراجعة تعديل شخص
 
- اقرأ التغيير، ثم كل مستند يربط إليه أو يشاركه
  مصدرًا.
- إن بقي كل شيء متّسقًا، فأضف نفسك إلى `verified`:
  - { by: <your-name>/<version>, at: <وقت UTC> }
- إن لم يعد شيء متّسقًا، فاقترح التصحيح، ولا تطبّقه في صمت.
 
## ممنوع
 
- لا تضف أبدًا مدخل `human:` إلى `verified`. هذا يفعله الإنسان وحده.
- لا تحذف مدخلات غيرك في `verified` ولا تغيّر ترتيبها.
- لا تحذف مستندًا أبدًا. ضع `status: deprecated` واذكر السبب.
- لا تكتب فوق تعديل أجراه إنسان. إن خالفته الرأي، فقل ذلك وتوقّف.
- لا تعدّل أي ملف في references/. فهي الأدلة.
 
## حين تنتهي
 
- أضف مدخلًا مؤرَّخًا إلى log.md.
- اذكر كل ملف أنشأته أو غيّرته أو نقلته أو جعلته deprecated.

ضع مدد الصلاحية التي تناسبك مكان تلك المذكورة تحت Frontmatter. تعدّ OKF كل ملف .md مستندًا ما عدا index.md وlog.md، ولذلك يبدأ القالب بـfrontmatter خاص به فيه type، لتبقى الحزمة صالحة. أما مثال frontmatter داخله فهو نموذج ينسخه الوكلاء.

بعض القواعد لا تخصّ إلا مكانًا واحدًا. مع AGENTS.md، ضع ملفًا ثانيًا في ذلك المجلد، مثل metrics/AGENTS.md، فيعتمد الوكلاء الأقرب منهما. وفي Claude Code أيضًا قواعد خاصة بمسارات بعينها: ملفات markdown في .claude/rules/ فيها حقل paths، ولا تُحمَّل إلا حين يقرأ Claude ملفًا يطابقها.

---
paths:
  - "metrics/**/*.md"
---
 
# المقاييس
 
- يربط كل مقياس بالاستعلام الذي يحسبه في metrics/computations/.
- لا تغيّر أي رقم دون أن تضيف له مصدرًا جديدًا.

وهكذا يبقى ملف الجذر قصيرًا. فوثائق Anthropic تحذّر من أن ملفات التعليمات الطويلة تستهلك سياقًا أكبر، ويقلّ التزام الوكيل بها.

في Claude Code، شغّل /context وانظر تحت Memory files لتتأكد أن ملفك قد حُمّل. ومع أي وكيل، ابدأ الجلسة بأن تطلب منه أن يعيد عليك قواعد كتابة مستند جديد. فإن عجز عن ذلك، فإما أنه لا يقرأ الملف، وإما أن الملف أطول مما ينبغي.

ثم احكم على ما يكتبه فعلًا، لا على ما يعد به. يكفي أمرا grep لكشف أكثر الأخطاء شيوعًا:

# مستندات بلا type: حقل OKF الوحيد المطلوب
$ grep -rL "^type:" --include="*.md" . | grep -v -e "/index.md$" -e "/log.md$"
 
# روابط wikilinks تسلّلت إلى الملاحظات
$ grep -rn "\[\[" --include="*.md" .

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

يأتي Knowtarium بمهارة (skill) لقواعد العمل يحصل عليها كل وكيل تربطه مع أدواته (Claude Code وCodex وCursor وClaude Desktop وغيرها)، فلا تحتاج إلى كتابة قواعد العمل في Knowtarium داخل كل ملف تعليمات.

ما تعلّمه للوكيل

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

كيف تتكامل مع ملف AGENTS.md لديك

في Knowtarium، ملف AGENTS.md هو تعليمات المجلد: اكتبه في التطبيق، فيحصل عليه الوكلاء مع كل ملاحظة يكتبونها هناك.

وبعض القواعد لا يتوقف على أن يقرأ أحدٌ ملفًا. ففي Knowtarium، كل تغيير يجريه وكيل موقَّع بمفتاحه هو، ولا يحذف الوكلاء المستندات إلا إن منحتهم هذه الصلاحية، ولا يستطيعون أن يَسِموا أي شيء بأنه راجعه شخص، وفي المجلدات التي فعّلت فيها المراجعة لا يستطيعون تخطّي مراجعتك. ولا يصل الوكيل إلا إلى مساحة العمل والمجلدات التي ربطته بها. ولا يستدعي التطبيق أي ذكاء اصطناعي من تلقاء نفسه: حين تريد مراجعة تعديلاتك، تطلب ذلك من وكيلك، فيتبع المهارة.

يتصل الوكلاء عبر MCP بالأمر npx knowtarium connect، أو بإضافة Knowtarium في Claude Code وCodex (وهي تتضمّن المهارة)، أو بالامتداد في Claude Desktop، أو بنقرة واحدة في Cursor وVS Code. أما موصلات تطبيقات المحادثة مثل claude.ai وChatGPT فتأتي لاحقًا. اطّلع على كيف يعمل الوكلاء مع Knowtarium.