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 بيظهّرها على طول بدل ما يسيب الكسر يتراكم.

ده كمان ليه prompts agentic بتعيش في context windows طويلة. الخطة، الـ invariants، الملاحظات الجارية — كلهم محتاجين يفضلوا مرئيين للموديل عشان يتصرف بثبات. Context windows قصيرة بتجبر prompting متكرر؛ الأطول بتسيب الـ agent متماشي لـ sessions بحجم feature كاملة.

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