Claude Code: Planning prompts

Claude Code، agent mode في Cursor، و agentic CLIs مشابهة بيشتغلوا مختلف عن prompt one-shot. بيشغّلوا loop: قراية ملفات، اقتراح تغيير، تطبيقه، تشغيل tests، ملاحظة النتيجة، قرار اللي يعمله بعدين. Prompting الأدوات دي مش بس عن مخرج كويس، أكتر عن تقييد سلوك الـ agent عشان ما يلفش في دواير أو يخرج عن السيناريو.

أكتر نمط مفيد هو plan-then-execute. قبل ما الـ agent يلمس أي ملف، بيقول اللي ناوي يعمله. بتقرا الخطة، توافق أو تعدّل، وبعدين الـ agent بيعدّل الكود.

Prompt plan-then-execute كويس بيبان كده:

I'm going to ask you to refactor src/auth/session.ts so that validateSession is async and returns null instead of throwing on invalid tokens.

Before you change any file, output a plan in this format:

Files I will edit

• (one bullet per file)

Changes per file

• (one bullet per change, with the function or section name)

What I will NOT do

• (one bullet per non-change to confirm understanding)

Wait for me to reply "go" before applying the plan.

"wait for me to reply 'go'" دي البوابة. من غيرها، الـ agent غالباً بيقر بالخطة ويبدأ يعدّل على طول. معاها، بتجيب checkpoint تقدر تصحّح فيها سوء الفهم برخص.

ليه قسم "What I will NOT do" مهم؟ بيمسك أكتر فشل في الـ agents: scope creep في الهدوء. الـ agent بيقرر إن طالما هو بيعدّل session.ts، يحسّن كمان الـ imports، يصلّح typo في comment، أو يطلّع helper. كل واحدة دي تغيير مش مرغوب فيه متلبّس مفيد. بإجبار الـ agent يحط non-changes في list، بتخلّيه يلتزم إنه يسيب الحاجات في حالها.

ماكينة حالة plan-then-execute:

رد plan-then-execute كويس بيبان كده (متصرّف):

## Files I will edit
- src/auth/session.ts
- src/auth/session.test.ts

## Changes per file
- session.ts: change `validateSession` to `async`, return `null`
  on invalid token, remove the `throw` path
- session.test.ts: update existing tests to await the call,
  add new test for the null-on-invalid case

## What I will NOT do
- Will not change other functions in session.ts
- Will not modify imports unless required by the new async signature
- Will not refactor adjacent code for style or clarity

بتقرا الخطة في 15 ثانية. لو صح، تردّ go. لو فيه حاجة غلط، تردّ بتصحيح: "Skip the test file — the test will be added in a separate PR." الـ agent بيحدّث الخطة ويسأل go تاني.

نمط تاني مفيد لـ sessions agentic أطول: invariants. قول من الأول الحاجات اللي لازم تفضل صح طول الـ session، واطلب من الـ agent يأكد عليهم بعد كل خطوة.

Invariants for this session:

1. The repo must always pass npm run typecheck.
2. No new dependencies in package.json.
3. No modifications to files outside src/auth/.

After each apply, run typecheck and report whether invariants 1, 2, 3 still hold.

دلوقتي الـ agent عنده self-check. لو خطوة كسرت invariant، الـ agent بيظهّرها على طول بدل ما يسيب الكسر يتراكم.

شوف الأول لو أداتك بتعمل ده أصلاً

كل اللي فوق نمط prompt: بيشتغل في أي شات، مع أي موديل، من غير أي دعم من الأداة. القابلية دي للنقل هي سبب إنه يستاهل تتعلمه. بس لو إنت شغّال في Claude Code تحديداً، إنك تعمله بإيدك بيسيب أهم نص منه على الترابيزة.

Claude Code بيشحن plan mode كوضع صلاحيات من الدرجة الأولى — اضغط Shift+Tab لحد ما سطر الحالة يوريك plan mode، أو ابدأ الـ session بـ claude --permission-mode plan. جوّاه، Claude بيقرا الملفات وبيجاوب على الأسئلة ومش قادر يعدّل أي حاجة، لأن أدوات التعديل مش متاحة له أصلاً لحد ما تقبل الخطة.¹

الفرق ده هو بيت القصيد، وسهل يفوتك لأن الأسلوبين بيطلّعوا خطة وبيستنوا:

	"wait for me to reply 'go'"	Plan mode
اللي بيمنع التعديل	الموديل وهو بيختار يلتزم	نظام الصلاحيات — أدوات التعديل مش معروضة
لو الموديل تجاهلها	ملفاتك بتتغيّر	مفيش حاجة بتحصل؛ مفيش أداة يناديها
الخطة بتعيش فين	في الـ transcript، وبتروح مع الـ scroll	مخرج خطة تقدر تقراه وتعدّله قبل ما تقبله
قابل للنقل لأدوات تانية	أيوه	لأ — Claude Code بس

البوابة على مستوى الـ prompt طلب. البوابة على مستوى الصلاحيات قيد. الطلبات هي إزاي تخلّي الـ agent يقف غالباً؛ القيود هي إزاي تخلّيه يقف دايماً. لما الاتنين متاحين، استخدم القيد وخلّي نمط الـ prompt للأدوات اللي مالهاش واحد.

اللي بيفضل مفيد مهما كانت الأداة: شكل الخطة اللي بتطلبها. لا plan mode ولا أي أداة تانية هتخترعلك قسم ## What I will NOT do، والقسم ده هو اللي بيمسك الـ scope creep. اطلبه صراحةً، في plan mode أو برّاه.

ونمط الـ invariants كمان يستاهل تحتفظ بيه كـ prompt — plan mode ما بيغطيهوش، لأنه بينطبق أثناء التنفيذ مش قبله.

التالي: تشكيل Copilot completions بالـ comments فوق الـ cursor. :::

Footnotes

1. توثيق Claude Code، أوضاع الصلاحيات. أدوات الشركات بتتحرك بسرعة؛ شوف التوثيق الحالي مش الفقرة دي قبل ما تعتمد على اختصار لوحة مفاتيح بعينه. ↩