SEASON 1 · EPISODE 4সিজন ১ · এপিসোড ৪

CROSS-SESSION
COORDINATION ক্রস-সেশন
কোঅর্ডিনেশন

RIFAT · SENIOR ENGINEER, NOP-STATION "Three sessions running. All three hit the same database table. Nobody told anyone. Merge day was not fun." "তিনটা সেশন চলছিল। তিনটাই একই ডেটাবেজ টেবিলে হাত দিল। কেউ কাউকে জানায়নি। মার্জের দিন ভালো ছিল না।"
RECAP · EP 1–3সারসংক্ষেপ · এপিসোড ১–৩

The Story So Farএ পর্যন্ত গল্প

EP 1
You are the bottleneck. Claude waits on you. Run 3 sessions = 3× AI-hours. তুমিই বাধা। ক্লদ তোমার জন্য অপেক্ষা করে। ৩ সেশন = ৩× কাজ।
EP 2
Multiple sessions. Worktrees, focused prompts, 20-min rotation, one PR per session. একাধিক সেশন। ওয়ার্কট্রি, ফোকাসড প্রম্পট, ২০ মিনিট রোটেশন।
EP 3
Subagents. Fan-out inside one session. Claude orchestrates. You collect results. সাবএজেন্ট। একটি সেশনেই ফ্যান-আউট। ক্লদ অর্কেস্ট্রেট করে।
Today: what happens when parallel sessions need to share decisions — same schema, same API contract, same files. আজ: যখন প্যারালেল সেশনগুলো একই সিদ্ধান্ত শেয়ার করতে হয় — একই স্কিমা, একই API কন্ট্রাক্ট, একই ফাইল।
THE PROBLEMসমস্যা

Sessions Are Islandsসেশন হলো দ্বীপ

RIFAT Each session has its own context window. It doesn't know what the other sessions decided five minutes ago. That's fine — until they all need to agree on something. প্রতিটা সেশনের নিজস্ব কনটেক্সট উইন্ডো আছে। অন্য সেশন পাঁচ মিনিট আগে কী সিদ্ধান্ত নিয়েছে সেটা সে জানে না। ঠিক আছে — যতক্ষণ না তাদের একমত হতে হয়।
🏝 Session A — auth module🏝 সেশন A — অথ মডিউল
🏝 Session B — payments🏝 সেশন B — পেমেন্ট
🏝 Session C — API layer🏝 সেশন C — API লেয়ার
All three need: the same user_id field type, the same error response format, the same DB migration file. None of them know what the others chose. তিনটারই দরকার: একই user_id ফিল্ড টাইপ, একই এরর রেসপন্স ফরম্যাট, একই DB মাইগ্রেশন ফাইল। কিন্তু কেউ জানে না অন্যরা কী বেছেছে।
WHEN IT MATTERSকখন সমস্যা হয়

The Coordination Trigger Listকোঅর্ডিনেশন ট্রিগার লিস্ট

  • 📋Two+ sessions touch the same DB table or migration fileদুই বা বেশি সেশন একই DB টেবিল বা মাইগ্রেশন ফাইলে কাজ করে
  • 🔗Sessions share an API interface — one builds, others consumeসেশনগুলো একই API ইন্টারফেস ব্যবহার করে — একটা তৈরি করে, বাকিরা ব্যবহার করে
  • ⚙️Shared config or environment variables one session might changeশেয়ার করা কনফিগ বা এনভায়রনমেন্ট ভেরিয়েবল যা একটি সেশন পরিবর্তন করতে পারে
  • 🔀PRs that will need to merge in a specific orderPR যেগুলো নির্দিষ্ট ক্রমে মার্জ করতে হবে
  • ✅Fully independent modules with no shared data model → no coordination neededসম্পূর্ণ স্বাধীন মডিউল, কোনো শেয়ার্ড ডেটা নেই → কোনো কোঅর্ডিনেশন দরকার নেই
THREE PATTERNSতিনটি প্যাটার্ন

The Coordination Toolkitকোঅর্ডিনেশন টুলকিট

1

Shared Filesশেয়ার্ড ফাইল

Write decisions into files all sessions can read before they startসিদ্ধান্তগুলো ফাইলে লিখুন যা সব সেশন শুরু করার আগে পড়তে পারে

2

Structured Handoffsস্ট্রাকচার্ড হ্যান্ডঅফ

Session A's output becomes Session B's input — agree on format firstসেশন A-এর আউটপুট সেশন B-এর ইনপুট হয় — আগে ফরম্যাট ঠিক করুন

3

Merge Orchestrationমার্জ অর্কেস্ট্রেশন

Plan the merge order before sessions start — foundation branch merges firstসেশন শুরু করার আগেই মার্জ অর্ডার পরিকল্পনা করুন — ফাউন্ডেশন ব্র্যাঞ্চ আগে মার্জ হবে

All three cost 15 minutes of setup. All three save hours of merge conflict debugging. তিনটাই ১৫ মিনিট সেটআপ নেয়। তিনটাই ঘণ্টার মার্জ কনফ্লিক্ট ডিবাগিং বাঁচায়।
PATTERN 1প্যাটার্ন ১

CLAUDE.md as Coordination LayerCLAUDE.md কোঅর্ডিনেশন লেয়ার হিসেবে

Every session reads CLAUDE.md at startup. Write your shared decisions there before launching any session. It's the one file they all agree on. প্রতিটি সেশন স্টার্টআপে CLAUDE.md পড়ে। যেকোনো সেশন লঞ্চ করার আগে শেয়ার্ড সিদ্ধান্তগুলো সেখানে লিখুন। এটাই একমাত্র ফাইল যেটায় সবাই একমত।
📄 CLAUDE.md — Shared Decisions Section
## Shared Data Contracts user_id: UUID (not integer) — decided 2026-06-19 error format: { code: string, message: string, field?: string } timestamps: ISO 8601, UTC, column name = created_at / updated_at ## DB Migration Rules Only Session A (auth branch) owns migrations/. Sessions B and C must NOT create migration files. Ask Rifat if you need a schema change. ## API Base Path All endpoints under /api/v2/ — no v1 endpoints in new work.
PATTERN 1প্যাটার্ন ১

Live Shared Memory Fileলাইভ শেয়ার্ড মেমরি ফাইল

CLAUDE.md is for pre-launch decisions. For decisions made during a sprint, use a live shared file. Tell each session to read it at the start of each turn. CLAUDE.md লঞ্চ-পূর্ব সিদ্ধান্তের জন্য। স্প্রিন্ট চলাকালীন সিদ্ধান্তের জন্য লাইভ শেয়ার্ড ফাইল ব্যবহার করুন। প্রতিটি সেশনকে প্রতিটি টার্নের শুরুতে এটা পড়তে বলুন।
📄 .claude/shared-state.md — Live Sprint Decisions
## Live Decisions (update as sprint progresses) [2026-06-19 10:32] Auth: JWT expiry = 7 days (not 24h). — Rifat [2026-06-19 11:15] Payments: use Stripe webhooks, not polling. — Habib [2026-06-19 14:02] API: rate limit = 100 req/min per user_id. — Shazzad ## Blocked / Waiting Session C (API) waiting on Session A (auth) for token validation endpoint. ETA: today 16:00.
Prompt each session: "Read .claude/shared-state.md before starting. Append any decisions you make." প্রতিটি সেশনকে প্রম্পট করুন: "শুরু করার আগে .claude/shared-state.md পড়ুন। আপনি যে সিদ্ধান্ত নেন সেগুলো যোগ করুন।"
PATTERN 2প্যাটার্ন ২

The Handoff Protocolহ্যান্ডঅফ প্রোটোকল

Some sessions run in sequence — Session A produces something Session B needs. The rule: agree on the output format before either session starts. কিছু সেশন ক্রমানুসারে চলে — সেশন A কিছু তৈরি করে যেটা সেশন B-এর দরকার। নিয়ম: কোনো সেশন শুরু করার আগেই আউটপুট ফরম্যাটে একমত হন।
Session Aসেশন A
Auth module
Builds token endpointঅথ মডিউল
টোকেন এন্ডপয়েন্ট তৈরি
→ writes: .claude/auth-contract.md
→
Session Cসেশন C
API layer
Consumes token endpointAPI লেয়ার
টোকেন এন্ডপয়েন্ট ব্যবহার করে
← reads: .claude/auth-contract.md
Session A finishes → writes its API contract → Session C launches, reads the contract, and integrates correctly. No guessing. সেশন A শেষ করে → API কন্ট্রাক্ট লেখে → সেশন C চালু হয়, কন্ট্রাক্ট পড়ে, সঠিকভাবে ইন্টিগ্রেট করে। কোনো অনুমান নেই।
PATTERN 2প্যাটার্ন ২

Output Contractsআউটপুট কন্ট্রাক্ট

An output contract is a structured format the producing session must write and the consuming session reads. Keep it simple — markdown or JSON. আউটপুট কন্ট্রাক্ট হলো একটি স্ট্রাকচার্ড ফরম্যাট যেটা প্রডিউসিং সেশন লিখবে এবং কনজিউমিং সেশন পড়বে। সহজ রাখুন — মার্কডাউন বা JSON। 
# .claude/auth-contract.md — written by Session A, read by Session C

## Token Endpoint
POST /api/v2/auth/token
Body:   { email: string, password: string }
200:    { token: string, expires_at: ISO8601 }
401:    { code: "INVALID_CREDENTIALS", message: string }
429:    { code: "RATE_LIMITED", retry_after: number }

## Token Validation Middleware
import { validateToken } from '@/lib/auth'
# Returns: { user_id: UUID, email: string } or throws AuthError

## Status
COMPLETE — endpoint live on feat/auth-agent branch
Session C prompt: "Read .claude/auth-contract.md before integrating the token endpoint. Do not assume the shape — use exactly what's documented." সেশন C প্রম্পট: "টোকেন এন্ডপয়েন্ট ইন্টিগ্রেট করার আগে .claude/auth-contract.md পড়ুন।"
BRANCH STRATEGYব্র্যাঞ্চ কৌশল

One Worktree, One Session, One Branchএক ওয়ার্কট্রি, এক সেশন, এক ব্র্যাঞ্চ

# Set up three worktrees before launching any session
git worktree add ../worktrees/auth     -b feat/auth-agent
git worktree add ../worktrees/payments -b feat/payments-agent
git worktree add ../worktrees/api      -b feat/api-agent

# Then launch each session in its own worktree
cd ../worktrees/auth     && claude # Session A
cd ../worktrees/payments && claude # Session B
cd ../worktrees/api      && claude # Session C
✓ Isolated file systems — no accidental overwrites✓ আলাদা ফাইল সিস্টেম — কোনো ভুল ওভাররাইট নেই
✓ Clear branch-to-session mapping for review✓ রিভিউর জন্য স্পষ্ট ব্র্যাঞ্চ-সেশন ম্যাপিং
✓ Shared files (CLAUDE.md, .claude/) visible across all✓ শেয়ার্ড ফাইল সবার কাছে দৃশ্যমান
PATTERN 3প্যাটার্ন ৩

Merge Orchestrationমার্জ অর্কেস্ট্রেশন

Merge order isn't optional when sessions have dependencies. The foundation branch must land first. Dependent branches rebase onto it before their PR goes up. যখন সেশনগুলোর মধ্যে নির্ভরতা থাকে তখন মার্জ অর্ডার ঐচ্ছিক নয়। ফাউন্ডেশন ব্র্যাঞ্চ আগে মার্জ হতে হবে। নির্ভরশীল ব্র্যাঞ্চগুলো PR দেওয়ার আগে তার উপর রিবেজ করে।
① Auth branch① অথ ব্র্যাঞ্চ
Merges first.
DB schema owner.প্রথমে মার্জ হয়।
DB স্কিমার মালিক।
→
② Payments branch② পেমেন্ট ব্র্যাঞ্চ
Rebases onto auth.
Merges second.অথের উপর রিবেজ করে।
দ্বিতীয়তে মার্জ হয়।
→
③ API branch③ API ব্র্যাঞ্চ
Rebases onto both.
Merges last.দুটোর উপর রিবেজ করে।
শেষে মার্জ হয়।
Write the merge order in CLAUDE.md before the sprint. No surprises on merge day. স্প্রিন্টের আগে CLAUDE.md-এ মার্জ অর্ডার লিখুন। মার্জের দিন কোনো চমক নেই।
LIVE EXAMPLEলাইভ উদাহরণ

Rifat's Feature Sprintরিফাতের ফিচার স্প্রিন্ট

Session A · Shazzadসেশন A · শাজ্জাদ
feat/auth-agent
User login, JWT, token refresh, logout. Owns migrations/. feat/auth-agent
লগইন, JWT, টোকেন রিফ্রেশ, লগআউট। migrations/ মালিক।
Session B · Habibসেশন B · হাবিব
feat/payments-agent
Stripe integration, webhook handlers, payment records. feat/payments-agent
স্ট্রাইপ ইন্টিগ্রেশন, ওয়েবহুক হ্যান্ডলার, পেমেন্ট রেকর্ড।
Session C · Rifatসেশন C · রিফাত
feat/api-agent
REST endpoints, auth middleware wiring, rate limiting. feat/api-agent
REST এন্ডপয়েন্ট, অথ মিডলওয়্যার, রেট লিমিটিং।
All three launched after Rifat spent 20 minutes writing shared decisions into CLAUDE.md and setting up worktrees. Session C launched after Session A wrote its auth contract. রিফাত ২০ মিনিট ব্যয় করে CLAUDE.md-এ শেয়ার্ড সিদ্ধান্ত লিখেছেন এবং ওয়ার্কট্রি সেটআপ করেছেন। সেশন A অথ কন্ট্রাক্ট লেখার পরে সেশন C চালু হয়েছে।
SHOW MEদেখাও

The Pre-Sprint CLAUDE.mdস্প্রিন্ট-পূর্ব CLAUDE.md

📄 CLAUDE.md — Sprint Coordination Section (added before launch)
## Sprint: Checkout Feature · 2026-06-19 ### Shared Contracts - user_id: UUID v4 (string, not integer) - Error shape: { code: SCREAMING_SNAKE, message: string, field?: string } - Timestamps: created_at / updated_at, UTC, ISO 8601 ### File Ownership - migrations/ → Session A ONLY. B and C must not touch it. - src/lib/auth.ts → Session A writes, others import only. - src/payments/ → Session B only. ### Merge Order 1. feat/auth-agent (merges first — schema owner) 2. feat/payments-agent (rebase onto auth, then PR) 3. feat/api-agent (rebase onto both, then PR) ### Shared Memory Read .claude/shared-state.md at start of each turn. Append any new decisions you make.
CONFLICT SCENARIOকনফ্লিক্ট পরিস্থিতি

What Breaks Without Coordinationকোঅর্ডিনেশন ছাড়া কী ভাঙে

Session B (payments) needed a users table field, so it created its own migration. Session A (auth) also created a migration that modifies the same table. Neither knew. সেশন B (পেমেন্ট) একটি users টেবিল ফিল্ড দরকার ছিল, তাই নিজেই মাইগ্রেশন তৈরি করে। সেশন A (অথ) একই টেবিল পরিবর্তন করে মাইগ্রেশন তৈরি করে। কেউ জানত না।
Session A — 0003_auth_users.sqlসেশন A — 0003_auth_users.sql
ALTER TABLE users ADD COLUMN password_hash TEXT, ADD COLUMN jwt_secret UUID;
Session B — 0003_payment_users.sqlসেশন B — 0003_payment_users.sql
ALTER TABLE users ADD COLUMN stripe_customer_id TEXT, ADD COLUMN payment_method_id TEXT;
Both files named 0003_*.sql. Same sequence number. DB refuses to run both. Now you're debugging migration state on merge day. দুটো ফাইলই 0003_*.sql। একই সিকোয়েন্স নম্বর। DB দুটো একসাথে চালাতে অস্বীকার করে। এখন মার্জের দিন মাইগ্রেশন স্টেট ডিবাগ করছেন।
CONFLICT RESOLUTIONকনফ্লিক্ট সমাধান

Detect Early vs Fix Lateআগে ধরুন বনাম পরে ঠিক করুন

✓ Detect Early✓ আগে ধরুন
CLAUDE.md: "Only Session A owns migrations/." Sessions B and C skip migration creation entirely. Conflict never happens. CLAUDE.md: "শুধু সেশন A-এর migrations/ মালিকানা।" সেশন B এবং C মাইগ্রেশন তৈরিই করে না। কনফ্লিক্ট কখনো হয় না।
Cost: 2 lines in CLAUDE.mdখরচ: CLAUDE.md-এ ২ লাইন
✗ Fix Late✗ পরে ঠিক করুন
Two migration files with same sequence number. Now: manually renumber, test locally, verify idempotency, re-test both branches. Half a day lost. একই সিকোয়েন্স নম্বরের দুটো মাইগ্রেশন ফাইল। এখন: ম্যানুয়ালি রিনম্বার করুন, লোকালে টেস্ট করুন, আইডেম্পোটেন্সি যাচাই করুন। আধা দিন নষ্ট।
Cost: ~4 hours on merge dayখরচ: মার্জের দিন ~৪ ঘণ্টা
Early detection always wins. Most coordination cost comes from not coordinating early enough. আগে ধরা সবসময় জেতে। বেশিরভাগ কোঅর্ডিনেশন খরচ আসে যথেষ্ট আগে কোঅর্ডিনেট না করা থেকে।
THE MATHগণিত

When Does Coordination Cost More Than It Saves?কখন কোঅর্ডিনেশন বাঁচানোর চেয়ে বেশি খরচ করে?

Coordination overhead scales with shared surface area — the number of files, schemas, and contracts sessions have in common. কোঅর্ডিনেশন ওভারহেড শেয়ার্ড সারফেস এরিয়ার সাথে বাড়ে — ফাইল, স্কিমা এবং কন্ট্রাক্টের সংখ্যা যা সেশনগুলো ভাগ করে।
0 shared files০ শেয়ার্ড
~5 min setup~৫ মি
1–3 shared১–৩ শেয়ার্ড
~20 min setup~২০ মি
4–6 shared৪–৬ শেয়ার্ড
~45 min setup~৪৫ মি
7+ shared৭+ শেয়ার্ড
reconsiderপুনর্বিবেচনা
High shared surface area? Consider keeping it one session. Parallelism payoff only comes when tasks are genuinely separable. বেশি শেয়ার্ড সারফেস? একটি সেশনেই রাখার কথা বিবেচনা করুন। কাজ সত্যিকারের আলাদা করা যায় তখনই প্যারালেলিজমের সুবিধা আসে।
WATCH OUTসতর্ক থাকুন

Stale Contextপুরনো কনটেক্সট

Session A reads shared-state.md at 10am. Session B updates it at 11am. Session A is still running on the 10am version. It doesn't know the decision changed. সেশন A সকাল ১০টায় shared-state.md পড়ে। সেশন B সকাল ১১টায় এটা আপডেট করে। সেশন A এখনো ১০টার ভার্সনে চলছে। সে জানে না সিদ্ধান্ত পরিবর্তন হয়েছে।
Mitigation 1সমাধান ১
Add to every session's context refresh prompt: "Re-read .claude/shared-state.md before your next task." প্রতিটি সেশনের রিফ্রেশ প্রম্পটে যোগ করুন: "পরবর্তী কাজের আগে .claude/shared-state.md আবার পড়ুন।"
Mitigation 2সমাধান ২
Lock high-impact decisions in CLAUDE.md (not shared-state.md) so they're baked in from start and don't change mid-sprint. উচ্চ-প্রভাবের সিদ্ধান্তগুলো CLAUDE.md-এ লক করুন যাতে শুরু থেকেই বেক হয়ে যায় এবং স্প্রিন্টের মাঝে পরিবর্তন না হয়।
WATCH OUTসতর্ক থাকুন

Merge Order Debtমার্জ অর্ডার ঋণ

Session C builds the API layer. It assumes Session A's auth middleware is already in main. But Session A's PR hasn't merged yet. Session C's PR has diverged 3 days of commits from Session A. সেশন C API লেয়ার তৈরি করে। সে ধরে নেয় সেশন A-এর অথ মিডলওয়্যার ইতিমধ্যে main-এ আছে। কিন্তু সেশন A-এর PR এখনো মার্জ হয়নি। সেশন C-এর PR সেশন A থেকে ৩ দিনের কমিট দূরে।
The fix: Session C's launch prompt must say: "Do not assume any other session's work is in main. Import from the feat/auth-agent branch path directly, and note it for rebase." সমাধান: সেশন C-এর লঞ্চ প্রম্পটে লিখুন: "ধরে নেবেন না যে অন্য সেশনের কাজ main-এ আছে। সরাসরি feat/auth-agent ব্র্যাঞ্চ পাথ থেকে ইম্পোর্ট করুন।"
Rebase each dependent branch onto its foundation before raising a PR. The merge order you planned in CLAUDE.md becomes your rebase order. PR তোলার আগে প্রতিটি নির্ভরশীল ব্র্যাঞ্চ তার ফাউন্ডেশনের উপর রিবেজ করুন। CLAUDE.md-এ পরিকল্পিত মার্জ অর্ডারই রিবেজ অর্ডার।
THE RESULTফলাফল

Rifat's Feature — How It Landedরিফাতের ফিচার — কীভাবে শেষ হলো

Setupসেটআপ
20 min to write CLAUDE.md decisions, create worktrees, define contracts CLAUDE.md সিদ্ধান্ত লিখতে, ওয়ার্কট্রি তৈরি করতে, কন্ট্রাক্ট সংজ্ঞায়িত করতে ২০ মিনিট
Sprintস্প্রিন্ট
3 sessions, 2 days. 0 migration conflicts. 0 API contract mismatches. ৩ সেশন, ২ দিন। ০ মাইগ্রেশন কনফ্লিক্ট। ০ API কন্ট্রাক্ট মিসম্যাচ।
Merge dayমার্জের দিন
3 PRs, 3 clean rebases, 1 hour total. Merged in planned order. ৩ PR, ৩ পরিষ্কার রিবেজ, মোট ১ ঘণ্টা। পরিকল্পিত ক্রমে মার্জ।
HABIB "Last sprint this kind of feature took a week and two merge conflict days. This was two days and one boring merge morning." "গত স্প্রিন্টে এই ধরনের ফিচারে এক সপ্তাহ এবং দুইটা মার্জ কনফ্লিক্টের দিন লেগেছিল। এবার দুই দিন এবং একটি বিরক্তিকর মার্জ সকাল।"
WRAP UP · EP 4সারসংক্ষেপ · এপিসোড ৪

Cross-Session Coordinationক্রস-সেশন কোঅর্ডিনেশন

SHARED FILESশেয়ার্ড ফাইল
OUTPUT CONTRACTSআউটপুট কন্ট্রাক্ট
MERGE ORDERমার্জ অর্ডার
EARLY DETECTIONআগে শনাক্তকরণ
Pattern 1প্যাটার্ন ১ Write shared decisions into CLAUDE.md and .claude/shared-state.md before launchলঞ্চের আগে CLAUDE.md এবং shared-state.md-এ শেয়ার্ড সিদ্ধান্ত লিখুন
Pattern 2প্যাটার্ন ২ Agree on handoff format before sessions start — output contract filesসেশন শুরুর আগে হ্যান্ডঅফ ফরম্যাটে একমত হন — আউটপুট কন্ট্রাক্ট ফাইল
Pattern 3প্যাটার্ন ৩ Plan merge order first. Foundation branch merges first. Dependents rebase before PR.আগে মার্জ অর্ডার পরিকল্পনা করুন। ফাউন্ডেশন ব্র্যাঞ্চ আগে। নির্ভরশীলরা PR-এর আগে রিবেজ করে।
Next → Episode 5: Shazzad never sets an alarm again. Hooks, scheduled agents, and always-on automation. পরবর্তী → এপিসোড ৫: শাজ্জাদ আর কখনো অ্যালার্ম দেয় না। হুক, শিডিউলড এজেন্ট, এবং সবসময়-চালু অটোমেশন।