كتابة القواعد

القواعد ملفات Markdown في src/apothem/rules/ بامتداد .md.

الـfrontmatter الخاص بالقاعدةCopy Anchor Link

---
name: "..."
description: "..."
pathFilter: ""            # empty string for always-on; a glob for path-filtered
alwaysApply: true         # true for always-on; false for path-filtered
---

نطاقات القاعدةCopy Anchor Link

يُحدَّد نطاق القاعدة بحقلين في الـfrontmatter، هما alwaysApply وpathFilter:

خمس من القواعد المشحونة مفعّلة دائمًا: agnostic-posture، وauthority-inquiry، وsession-closure، وcontext-management، وفهرس القواعد. تُكلِّف القاعدة المفعّلة دائمًا سياقًا في كل جلسة، لذا ينبغي أن تكون القاعدة الجديدة مُرشَّحة بالمسار بأنماط glob تُسمّي الملفات التي تحكمها؛ والمُرشِّح المؤلَّف من ** وحده لا يحصر شيئًا، ويُحمِّل Claude Code تلك القاعدة عند الإطلاق كما يُحمِّل القاعدة المفعّلة دائمًا. ويُقيِّد المتن المشحون المجموعةَ المفعّلة دائمًا بتلك القائمة وبسقف للبايتات؛ والقاعدة التي تُرقّى إلى مفعّلة دائمًا تُغيِّر كليهما في التغيير نفسه. سمِّ كل قاعدة تُضيفها في فهرس القواعد (apothem-rule-index)، حتى تعثر عليها جلسة على إطار عمل لا يحصر القواعد بالمسار. وتأخذ القاعدة المرافقة (<parent>-<aspect>) قيمة pathFilter الخاصة بقاعدتها الأم، أو قيمة أضيق منها، فلا تُحمَّل أبدًا من دون قاعدتها الأم. لا تُعطِ قاعدةً من قواعدك الاسم apothem-rule-index: فالتثبيت يأخذ نسخة احتياطية من ملف القاعدة الذي يحمل ذلك الاسم ثم يكتب فوقه.

مثال على قاعدةCopy Anchor Link

---
name: "python-conventions"
description: "Python style conventions for this project"
pathFilter: "**/*.py"
alwaysApply: false
---

# Python conventions

- Use type annotations on all public functions.
- Maximum line length: 88 characters.
- Prefer explicit over implicit.

تطبيق القواعد على أُطُر العملCopy Anchor Link

بعد كتابة القاعدة، حدِّث كل محوّل لإطار عمل مُثبَّت. شغّل apothem harnesses list لرؤية المجموعة المُثبَّتة، ثم استدعِ update مرة واحدة لكل إطار عمل:

apothem update --harness claude-code
apothem update --harness cursor --project /path/to/project

يحتاج إطار العمل ذو نطاق المشروع إلى --project عند التحديث، كما في السطر الثاني؛ أما إطار العمل ذو نطاق المستخدم فلا يحتاج إليه.

التحقق من القواعدCopy Anchor Link

شغِّل أداة التحقّق من الـfrontmatter على ملف القاعدة الذي كتبته. من نسخة مسحوبة من Apothem، يجعل PYTHONPATH=src الحزمة قابلة للاستيراد؛ وبعد التثبيت بالسكربت، استخدم PYTHONPATH="$HOME/.apothem/src" مكانه.

PYTHONPATH=src python -m apothem.conformity.gate --check frontmatter-grep src/apothem/rules/<rule>.md

يأخذ الفحص الخاص بكل عملية كتابة مثل frontmatter-grep الملفَ المراد فحصه، أو --stdin لقراءة المحتوى من الدخل القياسي؛ ومن دون أيٍّ منهما ينتظر مُدخَلًا على الدخل القياسي. أما الفحص المستقلّ فيأخذ دليلًا جذرًا بدلًا من ذلك، كما في --check naming-grep ..