وحدة أساس الهندسة تعلّم الحسّ المهني وراء وثائق الأساس الثلاث. وهذه هي حقيبة الأصول: القوالب الجاهزة للتعبئة ومكتبة الـ prompts التي يثبّتها فريقك مرة واحدة ويرثها في كل جلسة Claude وكل PR وأسبوعِ كلِّ موظف جديد الأول.
ملاحظة قبل النسخ: القوالب نفسها بالإنجليزية عن قصد — فهي ملفات تعيش في الـ repo بجوار الكود، والكود ومعرّفاته وأدواته إنجليزية (هذا هو المعيار الذي يعلّمه المسار نفسه: الكود إنجليزي، والنقاش يتبع قارئه). أما مكتبة الـ prompts فمعروضة باللغتين — الصيغة العربية تليها الإنجليزية الأصلية — فاستعمل أيّهما أطبع على لسانك.
قالب CLAUDE.md الإنتاجي — املأ الـ stack الخاص بك
انسخ هذا القالب إلى جذر مشروعك باسم CLAUDE.md. واملأ الأقسام المعقوفة. قسم السياق الثنائي اللغة اختياري للفرق الإنجليزية وحدها، وواجب لمنتجات سوق المنطقة.
# [Project name] — engineering context
## Stack
- Runtime: [e.g. Node.js 22 / Python 3.12 / Go 1.22]
- Frontend: [e.g. Astro 6 / Next.js 14 / React 18]
- Database: [e.g. Supabase (PostgreSQL) / PlanetScale (MySQL)]
- Testing: [e.g. Vitest (unit) + Playwright (E2E)]
- Infra: [e.g. Cloudflare Workers / Vercel / Railway]
## Commands
[test-unit-command] # Unit tests (fast, no external deps)
[test-e2e-command] # End-to-end tests (requires running services)
[typecheck-command] # Type-checker (no emit)
[lint-command] # Linter
[dev-command] # Dev server
## Key conventions
- [e.g. All DB access goes through src/lib/queries/ — never call the ORM/SDK
directly from a route handler]
- [e.g. Error responses use { error: string, code: string } — no raw throws
that reach the client]
- [e.g. Async functions always have explicit return types]
- [e.g. Tests mirror the src/ structure — a test for src/lib/foo.ts lives at
tests/unit/lib/foo.test.ts]
## Do not touch
- [e.g. database/migrations/ — use the migration CLI to add new migrations;
never edit existing migration files]
- [e.g. src/lib/db.ts directly — extend the query helpers instead]
- [List other protected files and why]
## Bilingual context (MENA teams — delete if not applicable)
Product language: [EN + AR / EN only]
Arabic sections: [e.g. invoice PDFs, client-facing emails, src/content/ar/]
AR strings are authored in [Gulf Arabic / MSA] register — not translated.
RTL layout: [e.g. uses CSS logical properties throughout — never use physical
left/right in new styles]
Arabic-language review: flag changes to @[handle]قالب ARCHITECTURE.md — الخريطة التي يملؤها الموظف الجديد في يومه الأول
انسخه إلى جذر المشروع باسم ARCHITECTURE.md. وخير وقت لملئه حين تُعرّف موظفًا جديدًا أو بعد إعادة هيكلة كبرى — على أنه وثيقة حية، لا لقطة تُلتقط مرة.
# [Project name] — architecture
Last updated: [date], by [name].
## Top-level structure
[directory/] [what lives here — one line each]
[directory/] [...]
## [The most important flow] — end to end
[Entry point] (e.g. POST /invoices)
→ [file:function] ([what it does])
→ [file:function] ([what it does])
→ [file:function] ([what it does, what it writes])
→ [return shape]
## Landmines
- [Fragile part]: [why it's fragile, what breaks if you touch it wrong]
- [Implicit assumption]: [what the code assumes, where it breaks if wrong]
- [Uncovered path]: [what's missing from the test suite that looks load-bearing]
## Other notable flows (optional)
[Repeat the end-to-end trace section for any other flows worth documenting]مذكرة عرف الـ commit — تُلصق في CLAUDE.md أو تُحفظ وحدها
## Commit convention
Format: type(scope): subject (50 chars max, imperative mood)
<blank line>
Body: why this change was needed (not what it does).
Wrap at 72 chars. Reference the ticket if one exists.
Types: feat / fix / refactor / test / chore / docs / perf
One concern per commit. Never mix a bug fix with a refactor.
Examples:
fix(invoice): correct AED rounding on totals above 10,000
Supabase stores amounts as integers (fils). The calculation rounded
before multiplying, introducing a 1-fil error on totals > AED 10,000.
Added a unit test for the boundary value.
feat(pdf): add invoice PDF export via @react-pdf/renderer
Closes #142. Renders the same data as the web invoice view into a
PDF, with the Mizan logo and the client's billing address. Arabic
invoice PDFs use the ar-invoice template (RTL, Gulf Arabic register).مكتبة prompts الهندسة
الصقها مباشرة في محادثة Claude Desktop ومجلد المشروع مفتوح. كل prompt جاهز للاستعمال؛ والرموز المعقوفة هي كل ما تملؤه.
الخريطة والتعارف
ارسم خريطة الـ codebase
اقرأ هذا الـ repo وأعطني الخريطة: الوحدات العليا بمسارات مجلداتها
الحقيقية، وكيف يجري الطلب فعلًا من الـ route إلى قاعدة البيانات في
[الميزة / المسار الذي يهمك أكثر]، وأين تعيش المصادقة. بلغة مفهومة —
سمِّ الملفات الحقيقية، لا محاضرة عامة عن الـ framework.
Read this repo and give me the map: the top-level modules with their real
directory paths, how a request actually flows from the route to the database
for [the feature / flow you care about most], and where authentication lives.
Plain English — name the real files, not a generic framework lecture.تتبّع مسارًا واحدًا من أوله إلى آخره
خذني خطوة خطوة في ما يحدث بالضبط عند [فعل المستخدم / نداء API]:
أي الملفات تجري، وبأي ترتيب، وأي دالة في كل ملف. وأشِّر على كل ما
فاجأك — أثر جانبي خفي، أو طابور، أو كتابة ثانية.
Walk me through exactly what happens when [user action / API call]:
which files run, in what order, and which function in each. Flag anything
that surprised you — a hidden side effect, a queue, a second write.جِد الألغام
لو كان عليّ تعديل [المنطقة التي توشك أن تمسّها] الأسبوع القادم، ما
الذي سيعضّني؟ اذكر الأجزاء الشديدة الترابط، والافتراضات الضمنية،
والمسارات التي بلا اختبارات، وكل ما يبدو حاملًا وهو غير موثّق.
If I had to change [the area you're about to touch] next week, what would bite
me? List the tightly-coupled parts, the implicit assumptions, the paths with
no tests, and anything that looks load-bearing but undocumented.اكتب ARCHITECTURE.md
بناءً على الخريطة التي بنيناها للتوّ، اكتب ARCHITECTURE.md لهذا الـ
repo: البنية العليا بمسارات حقيقية، و[المسار الرئيسي] مُتتبَّعًا من
أوله إلى آخره بمؤشرات file:function، وقسم ألغام. أبقِه في صفحة
واحدة — موظف جديد يقرؤه في خمس دقائق ويعرف أين يضع يديه.
Based on the map we just built, write an ARCHITECTURE.md for this repo:
top-level structure with real paths, the [main flow] traced end to end with
file:function pointers, and a landmines section. Keep it to one page —
a new hire should be able to read it in five minutes and know where to put
their hands.المراجعة والـ commit
مراجعة كود بعين الخصم
هذا هو الـ diff وهذا ما يُفترض أن يفعله: [القصد في جملة واحدة].
راجعه كمهندس متمرّس متشكك، منظَّمًا بالأبعاد: الصحة، والحالات
الحدّية، والأمن، والتشغيل (ما الذي يوقظ أحدهم الثالثة فجرًا).
لكل مشكلة أعطني الملف والسطر، ولماذا هي مشكلة، ودرجة خطورتها.
ثم افترض أن فيه خطأ حقيقيًا واحدًا على الأقل وجِد أسوأه.
Here's the diff and what it's meant to do: [intent in one sentence].
Review it like a skeptical senior engineer, organized by dimension:
correctness, edge cases, security, and operability (what pages someone at 3am).
For each issue give me the file and line, why it's a problem, and the severity.
Then assume there's at least one real bug and find the worst one.تحقق من نتيجة
للنتيجة [النتيجة] التي أشّرت عليها، أرني الأسطر بعينها التي تثبت
أنها حقيقية — الكود الذي يصنع المشكلة، لا وصفها. وإن لم تستطع أن
تريني الأسطر، فقلها وسنسقط تلك النتيجة.
For the [finding] you flagged, show me the exact lines that prove it's real —
the code that creates the problem, not a description of it. If you can't show
me the lines, say so and we'll drop that finding.commit نظيف
جهّز هذه التعديلات في [العدد] من الـ commits المركّزة — همّ واحد لكل
commit. ولكل commit صُغ رسالة: عنوانًا (50 حرفًا، بصيغة الأمر) ومتنًا
يشرح لماذا لزم التعديل، لا ماذا يفعل. أرني الرسائل قبل الالتزام ولا
تشغّل شيئًا لم أعتمده.
Stage these changes as [number] focused commits — one concern per commit.
For each commit draft a message: a subject line (50 chars, imperative mood)
plus a body that explains why the change was needed, not what it does.
Show me the messages before committing and don't run anything I haven't
approved.الشحن والإثبات
اكتب الـ spec
أريد أن أبني: [وصف الميزة].
حوّله إلى spec قصير: خلاصة من فقرة واحدة، و4–6 معايير قبول مصوغة
عباراتٍ قابلة للاختبار، وقائمة «خارج النطاق حاليًا» صريحة. لا تكتب
أي كود بعد.
I want to build: [feature description].
Turn this into a short spec: a one-paragraph summary, 4–6 acceptance criteria
phrased as testable statements, and an explicit "out of scope for now" list.
Don't write any code yet.خذ الخطة أولًا
استعمل plan mode. من هذا الـ spec، ارسم خطة التنفيذ: أي الملفات
ستمسّ ولماذا، وترتيب التعديلات، والأنواع والواجهات المعنية، وأين
تذهب الاختبارات. لا تكتب كودًا — أريد مراجعة المنهج أولًا.
Use plan mode. Given this spec, lay out the implementation plan: which files
you'll touch and why, the order of changes, the types/interfaces involved,
and where the tests go. Don't write code — I want to review the approach first.اكتب اختبارات تثبّت السلوك
اكتب اختبارات تغطي كل معيار قبول اتفقنا عليه، ومعها الحالات الحدّية
البديهية — المدخل الفارغ، وقيم الحدود، ومسار الخطأ. شغّل الحزمة
كاملة وأرني أنها خضراء.
Write tests that cover every acceptance criterion we agreed on, plus the
obvious edge cases — empty input, boundary values, the error path.
Run the full suite and show me it's green.التغيير الآمن والـ migration
خطة refactor قبل أي تعديل
اقرأ [الملف / الوحدة] وقل لي أكبر ثلاث مشكلات بنيوية وكيف تصلح كل
واحدة، بالترتيب، دون تغيير في السلوك. لا تعِد الهيكلة بعد — أريد
الخطة نثرًا أولًا.
Read [file / module] and tell me the three biggest structural problems and
how you'd fix each, in order, without changing behaviour. Don't refactor yet —
I want the plan in prose first.مسح الـ migration
نحن ننتقل من [القديم] إلى [الجديد].
جِد كل استخدام عبر الـ repo وصنّفها: التحويلات المباشرة واحدًا
لواحد، والتي لا مكافئ نظيفًا لها، وكل ما هو غير معتاد. أعطني
الأعداد وقائمة الملفات. لا تغيّر شيئًا بعد.
We're moving from [old thing] to [new thing].
Find every usage across the repo and group them: the straightforward one-to-one
conversions, the ones with no clean equivalent, and anything unusual.
Give me the counts and the file list. Don't change anything yet.وطِّن من الإنجليزية إلى العربية (سجلّ خليجي)
هذا هو النص الإنجليزي لـ[السياق — فاتورة PDF / رسالة خطأ / بريد
تهيئة]. ألّف النسخة العربية بسجلّ خليجي — لا تترجم كلمة بكلمة.
استعمل مسرد المصطلحات في CLAUDE.md. يجب أن تُقرأ العربية أصيلة عند
محترف خليجي، لا ترجمة.
Here is the English copy for [context — invoice PDF / error message /
onboarding email]. Author the Arabic version in Gulf Arabic (خليجي) register
— do not translate word for word. Use the term glossary in CLAUDE.md.
The Arabic must read as native to a Gulf-based professional, not as a
translation.