DEV Community: Aman Kumar

Cursor Rules: Pay More Upfront, Iterate Less Later

Aman Kumar — Tue, 10 Feb 2026 03:26:24 +0000

TL;DR: The hybrid rules approach that saves 70% on context loading and completes tasks in fewer iterations.

Your Cursor AI is Loading Too Much

Every time you ask Cursor for help, it loads your entire .cursorrules file—even when most rules aren't relevant.

The result?

Slower responses (processing 5,000+ unnecessary tokens)
Wasted context budget on rules you don't need
Loading test patterns when writing docs

There's a better way.

The Hybrid Approach

Split your rules into two parts:

1. AGENTS.md (always loaded)

Lightweight file with core principles that apply to every task.

2. .cursor/rules/ (loaded intelligently)

Detailed patterns that load only when relevant to your current file.

Quick Example

AGENTS.md (in project root):

# My TypeScript Project

## Core Workflow
1. RED → Write failing test
2. GREEN → Minimal implementation  
3. REFACTOR → Improve quality

## Critical Rules
- Tests before implementation
- TypeScript strict mode
- 80% test coverage

## See Rules
Details: @tdd-workflow @testing

.cursor/rules/testing.mdc:

---
description: "Testing patterns and best practices"
globs: ["**/*.test.ts"]
---

# Testing Standards
[Detailed test patterns, examples, edge cases...]

What happens?

Cursor always knows your TDD workflow
When you edit test files, detailed patterns auto-load
When you edit docs, testing rules stay dormant
You get smart guidance without constant overhead

Get Started in 5 Minutes

Step 1: Create AGENTS.md

# [Your Project]

## Workflow
[Your main development process]

## Critical Rules  
[Top 3-5 non-negotiable rules]

## See Rules
@rule-name-1 @rule-name-2

Step 2: Create .cursor/rules/

mkdir -p .cursor/rules

Step 3: Add focused rule files

---
description: "Testing patterns"
globs: ["**/*.test.ts"]
---

# Your detailed testing rules here

Pro tip: Keep AGENTS.md under 50 lines. Everything else goes in .cursor/rules/.

The Token Trade-off: More Upfront, Less Overall

Here's the honest truth: Agent Mode with rules uses MORE tokens per session but FEWER total tokens to complete your task.

Without Rules:

Attempt 1: 20K tokens → Wrong architecture
Attempt 2: 30K tokens → Tests need fixing
Attempt 3: 25K tokens → Finally correct
Total: ~75K tokens + frustration + your time

With Rules:

Attempt 1: 70k-100k tokens → Done correctly
Total: ~100K tokens + confidence

When to Use Rules

Use Agent Mode + Rules when:

Building production features
Architecture compliance matters
Consistency is critical
Your time is valuable

Skip Rules when:

Quick prototypes
Exploring ideas
Simple one-line changes
You know exactly what to do

The Smart Workflow

Phase 1: You Think (No Agent Mode)

Write down requirements
Identify edge cases
Plan architecture
Token cost: Minimal

Phase 2: Agent Implements (With Rules)

Provide your spec
Let AI execute with precision
Review at checkpoints
Token cost: Higher, but efficient

Key insight: Rules don't replace your thinking—they ensure AI implements YOUR design correctly.

⚠️ Repository-Specific Rules Matter

Don't copy-paste rules between projects.

Each repository has unique:

File organization patterns
Testing strategies
Architecture decisions
Team conventions

Example:

React Frontend: src/components/, src/hooks/, __tests__/
CLI Tool: src/commands/, src/services/, test/
Monorepo: apps/, packages/, libs/

→ Different structures = Different rules

Think of rules as a custom onboarding document for each repo. Invest 30 minutes per project to create tailored rules that reflect how THAT specific codebase works.

Key Principles for Success

1. Keep AGENTS.md Minimal

Under 50 lines with only what applies to 80%+ of tasks.

2. Make Rules Focused

One concern per file: testing.mdc, architecture.mdc, not everything.mdc

3. Use Smart Loading

---
description: "What this covers"
globs: ["**/*.test.ts"]    # Auto-load for test files
alwaysApply: false           # Don't load everywhere
---

4. Examples Over Essays

Show one good pattern. AI learns from code, not paragraphs.

What You'll Gain

Before (single .cursorrules):

Slower responses
Context budget wasted

After (hybrid approach):

Faster AI responses
Rules load only when relevant

But remember: Agent Mode trades upfront tokens for fewer iterations. You spend more per session, but complete tasks in 1-2 tries instead of 5+.

Your Next Action

Create AGENTS.md with your top 5 rules today
Move detailed patterns to .cursor/rules/
Test it: Ask Cursor to build something and watch it follow your workflow automatically

Your AI pair programmer will be smarter, faster, and more aligned with your team's patterns.

Resources:

Why Your MCP Server Sucks (And How to Fix It)

Aman Kumar — Wed, 28 Jan 2026 22:20:01 +0000

TL;DR: MCP servers aren't failing because of the protocol—they're failing because developers treat them like REST APIs. Here's why that's wrong and how to fix it (explained for everyone, with minimal code).

Why Are Enterprise MCP Servers Disappointing?

Picture this: You've invested 6 months building an MCP server. The protocol works. The integration is live. Claude Desktop connects. Cursor connects.

But when your AI agent tries to use it?

🤖 Agent: "Track my order"
   Your MCP Server: "Here are 47 options. Good luck figuring it out!"
🤖 Agent: *confused* *picks wrong option* *fails*
❌ Result: Complete failure

Sound familiar?

Here's the twist: The protocol isn't broken. Your server design is.

The Fatal Mistake: Treating MCP Like a REST API

For 20+ years, we've built APIs for human developers. Those principles don't work for AI agents.

Think of it this way:

Building for Humans 👤

Read documentation once
Remember relationships between data
Debug when things go wrong
Unlimited memory and patience

Building for AI Agents 🤖

Re-read descriptions with every request (expensive!)
Get confused by too many choices
Can't debug—just tries the same thing again
Limited "memory" (context window)

The Core Problem: Different Users, Different Design

🚗 The Car Analogy

REST API = Manual Transmission

Human drivers: "I love the control! 6 speeds, perfect."
You learn once, drive forever
Expert drivers prefer it

Bad MCP Server = Manual with 47 Gears

Even experts get confused
"Wait, am I in gear 23 or 24?"
Constant grinding, failures
Nobody can drive it reliably

Good MCP Server = Automatic Transmission

"I want to go from A to B"
The system handles complexity
Just works. Every time.
Anyone can use it

The Real-World Example: Order Tracking

Old Way (Bad):
Your MCP server exposes 3 separate tools:

Find the customer
Find their orders
Check shipping status

Agent has to:

Figure out the right sequence
Call each tool separately (3 round-trips)
Remember results between calls
Combine everything into an answer

Result: Fails 40% of the time, takes 6+ seconds

New Way (Good):
Your MCP server exposes 1 tool:

track_order(email) → Returns "Order #98765 shipped via Flipkart, arriving Thursday"

Agent:

Calls once
Gets complete answer immediately
Always works

Result: Fails 2% of the time, takes 2 seconds

Same outcome. 3x faster. 20x more reliable.

The Six Principles of Good MCP Servers

1. Outcomes Over Operations

Wrong Thinking: "I have 3 database tables, so I need 3 tools"

Right Thinking: "Users want to track orders. I need 1 tool for that."

2. Keep It Simple (No Complex Inputs)

The Menu Analogy:

Bad MCP Server Menu:

Tool: order_food
Input: A complex form with nested sections:
  - Customer info (name, address, phone, preferences)
  - Order details (items, quantities, modifications, special instructions)
  - Delivery info (time, address, contact, instructions)
  - Payment info (method, billing address, tip percentage)

Agent gets confused, fills it out wrong 60% of the time.

Good MCP Server Menu:

Tool: order_food
Inputs (simple, clear):
  - customer_email: john@example.com
  - item: "Cheeseburger"
  - delivery_time: "6:00 PM"
  - address: "123 Main St"

Agent fills it out correctly 95% of the time.

Key principle: Simple, flat inputs = fewer mistakes

3. Instructions Matter (Guide the Agent)

The GPS Analogy:

Bad GPS:

"Turn"

Where? When? Which direction? You crash.

Good GPS:

"In 500 feet, turn right onto Main Street.
Use this when: You want to reach the mall
You'll know you're there when: You see the big parking lot"

Clear, specific, helpful. You succeed.

Same with MCP tools: Every tool needs crystal-clear instructions on:

When to use it
How to use it
What you'll get back
What to do if something goes wrong

4. Less Is More (Curate Ruthlessly)

The Netflix Paradox:

When Netflix shows you 10,000 movies, what happens?

You spend 30 minutes scrolling
Get overwhelmed
Watch nothing
Or pick randomly and regret it

When Netflix shows you 15 carefully curated picks "Because you watched..."

You find something in 2 minutes
Higher satisfaction
Better experience

Same with MCP servers:

❌ 50 tools = Agent is overwhelmed, picks wrong one, fails

✅ 5-10 tools = Agent finds right one immediately, succeeds

The Golden Rule: If you can't explain what each tool does in 10 seconds, you have too many.

Real Example:

Before: 50 tools for our CMS. Success rate: 31%
After: 8 focused tools. Success rate: 89%

5. Names That Make Sense

The Coffee Shop Problem:

Imagine 3 coffee shops in one building, all with the same menu names:

☕ Shop A: "Coffee"
☕ Shop B: "Coffee"  
☕ Shop C: "Coffee"

You ask your assistant: "Get me coffee"
They guess randomly. Wrong shop 67% of the time.

Now imagine clear names:

☕ Starbucks: "Starbucks Coffee"
☕ Peet's: "Peets Coffee"
☕ Dunkin: "Dunkin Coffee"

You ask: "Get me Starbucks coffee"
They get it right 99% of the time.

Same with MCP tools:

❌ Bad: send_message() (Which service? Slack? Email? Teams?)

✅ Good: slack_send_message() (Crystal clear!)

6. Don't Overwhelm with Data 📄

The Phone Book Problem:

Bad approach:
"Show me everyone named John"
→ Returns 10,000 results
→ Your screen crashes
→ You can't process it

Good approach:
"Show me everyone named John"
→ Returns first 20 results
→ "Found 10,000 total. Here are the first 20. Want more?"
→ You can actually use it

Key principle: Show digestible amounts, offer to show more if needed.

The Core Insight

MCP is not just another API. It's a User Interface—for AI agents.

When you build a regular UI:

You think about user experience
You simplify complex workflows
You guide users with clear labels
You test with real users

Do the same for your MCP server:

Think about agent experience
Simplify complex operations into single tools
Guide agents with clear descriptions
Test with real agents

💡 Quick Self-Check

Ask yourself these simple questions:

Can an AI accomplish user goals in 1-2 steps? (Not 5+ steps)
Do you have fewer than 15 tools? (5-10 is ideal)
Are inputs simple? (No complex nested forms)
Do tools have clear instructions? (When and how to use them)
Do you limit response sizes? (Show 20, not 2,000 items)

If you answered "no" to any of these, your server needs work. 🔧

Three Steps to Fix Your Server

Audit - Test your MCP server. Where does it fail?
Consolidate - Find 3-5 tools you can merge into 1 outcome-focused tool
Simplify - Remove one layer of complexity from your most-used tool

Start small. Fix one tool. Measure improvement. Repeat.

You don't need to rebuild everything at once. Every improvement helps.

The Bottom Line

Building a good MCP server is like building a good UI:

Know your user (it's an AI agent, not a human)
Simplify ruthlessly (fewer choices = better outcomes)
Guide clearly (instructions matter)
Test with real users (run it with actual agents)

The protocol works fine. Build your server right, and your AI will actually be useful.

💬 Your Turn!

Are you building with MCP? Share your experience in the comments!

Questions:

What's your biggest MCP challenge?
Have you seen agents struggle with your tools?
Which principle surprised you most?

P.P.S. - Thanks to Philipp Schmid for the research that inspired this post.

Why Client-Side Rate Limiting is Your API's Best Friend 🤝

Aman Kumar — Sat, 24 Jan 2026 07:46:25 +0000

TL;DR: We reduced API failures from 38% to 0.2% by implementing smart client-side rate limiting. Here's why it matters and how it works (explained for everyone, not just engineers).

Why Did Our Tool Keep Failing?

Picture this: You're a content manager at a large company. It's 9 AM Monday. You need to publish 10,000 blog posts to your CMS before the marketing campaign launches at noon.

You run the bulk publish command, grab coffee ☕, and return 20 minutes later expecting good news.

Instead:

❌ Failed: 3,847 out of 10,000 entries
⚠️  Rate limit exceeded
⚠️  Please try again later

Uh oh. It's 9:30 AM. Campaign launch in 2.5 hours. You're sweating. 😰

This was a real problem our users faced. And it wasn't their fault—it was ours.

The Real Culprit: We Were Being a Bad API Neighbor

Imagine you're at a coffee shop. There are 100 people in line. Everyone's polite, ordering one at a time.

Suddenly, 10 people rush to the counter simultaneously, all shouting orders. The barista gets overwhelmed, stops serving everyone, and puts up a sign: "CLOSED - Come back in 30 minutes"

That's basically what our old CLI was doing to APIs.

Our Old Approach (The Bad Neighbor):

Fixed speed: Always drove at 60 mph, even in school zones
Stubborn retries: Failed twice? Give up immediately
Loud and proud: When one request fails, ALL retries happen at once
No learning: Kept making the same mistakes over and over

Result? 38% failure rate. Users had to manually retry thousands of times. Not cool.

The Solution: Four Layers of "Being Polite" to APIs

We rebuilt our system with four simple principles that work together like a well-oiled machine:

The Four-Layer Approach

Think of it like defensive driving with a GPS that warns you about traffic ahead:

Layer 0 - Listen to Traffic Reports (Real-Time Intelligence)
- The API tells us: "I'm getting busy, slow down!"
- We proactively adjust BEFORE hitting any limits
- Like having a co-pilot who sees problems before you do
Layer 1 - Speed Governor (Prevention)
- Don't go too fast in the first place
- Slow down automatically when you see trouble ahead
Layer 2 - Smart Braking (Recovery)
- If something goes wrong, back off intelligently
- Don't try the same thing immediately
Layer 3 - Avoid Traffic Jams (Coordination)
- Don't retry at the exact same time as everyone else
- Spread out the load

Layer 0: Real-Time Intelligence (Server Header Integration)

This is the secret weapon!

The GPS Analogy

Imagine driving to work:

Without GPS (Old way):

You drive at the speed limit
Hit traffic jam unexpectedly
Now you're stuck!

With GPS (New way with headers):

GPS: "Traffic building up ahead, slow down now"
You slow down BEFORE the traffic
You smoothly merge into the slower lane
Never get stuck!

How API Headers Work

Modern APIs are like that GPS—they send you real-time traffic reports with every response:

// Every API response includes these "traffic reports"
Response Headers:
  x-ratelimit-limit: 10        // Speed limit: 10 requests/second
  x-ratelimit-remaining: 3     // Only 3 "slots" left this second
  x-ratelimit-reset: 1732108801 // Traffic clears at this timestamp

The Magic: Proactive Slowdown

Here's what makes this brilliant:

Traditional approach (blind driving):

Request 1 → Success (you don't know you're running out of quota)
Request 2 → Success (still no warning)
Request 3 → Success (uh oh, almost there)
Request 4 → 429 RATE LIMIT! (crash!)
Request 5 → 429 again! (stuck in traffic)

Our smart approach (with headers):

Request 1 → Success 
  ← Headers say: "8/10 remaining" 
  → You: "Cool, I'm good"

Request 2 → Success
  ← Headers say: "3/10 remaining" 
  → You: "Whoa! Traffic ahead! Slowing down to 4 req/sec"

Request 3 → Success (slower pace)
  ← Headers say: "7/10 remaining" 
  → You: "Traffic clearing! Speeding up to 6 req/sec"

Request 4 → Success
  ← Headers say: "8/10 remaining"
  → You: "All clear! Back to 10 req/sec"

Result: ZERO 429 errors!

Real-World Example

Publishing 5,000 blog posts:

9:00:00 AM - Start publishing at 10 req/sec
            ↓
9:00:01 AM - Header: "8/10 remaining" ✅ All good
            ↓
9:00:03 AM - Header: "2/10 remaining" ⚠️ Getting low!
            → Proactively throttle to 4 req/sec
            ↓
9:00:05 AM - Header: "6/10 remaining" ✅ Recovering
            → Gradually increase to 7 req/sec
            ↓
9:00:10 AM - Header: "9/10 remaining" ✅ Fully recovered
            → Back to 10 req/sec

RESULT: Published all 5,000 with ZERO 429 errors!

Why This is a Game-Changer

Without headers:

Guessing the safe speed
Hit 429 errors (average 38 per 5,000 requests)
Waste time on retries
Frustrating experience

With headers:

Know EXACTLY how much quota remains
Prevent 429 errors BEFORE they happen (down to 0-4 errors)
Optimal speed (never too slow, never too fast)
Smooth, predictable experience

It's like having X-ray vision into the API's capacity!

Layer 1: The Smart Speed Governor (Token Bucket + Sliding Window)

The Coffee Shop Analogy

Imagine you have a token bucket full of coffee vouchers:

Start with 20 vouchers (burst capacity)
Use 1 voucher per order
Get 10 new vouchers every second (refill rate)
Can't exceed 20 vouchers total

Why this works:

You can handle a rush (use 20 vouchers quickly)
Then you settle into a steady pace (10 per second)
You never overwhelm the barista

The Adaptive Part (The Secret Sauce!)

Here's where it gets smart. Our system learns and adapts:

When things go well:

10 successful orders → Speed up by 5%
Another 10 successes → Speed up another 5%
Keep improving until you hit the speed limit

When you get rate limited:

Got rejected? → Slow down by 30%
Rejected again? → Slow down another 30%
10 rejections in a row? → STOP. Take a 5-second break

Real-world example:

9:00 AM → Start at 10 requests/second
9:01 AM → Got rate limited! Drop to 7 req/sec
9:03 AM → Things stable. Increase to 7.35 req/sec
9:05 AM → Still good. Increase to 7.7 req/sec
9:10 AM → Back to 10 req/sec (fully recovered)

It's like cruise control that automatically slows down on curvy roads and speeds up on straightaways!

Layer 2: Exponential Backoff (The "Back Off, Buddy" Strategy)

The Wisdom of Waiting

When something fails, don't try the exact same thing immediately. That's the definition of insanity!

Instead, wait progressively longer:

Attempt 1: Failed → Wait 1 second
Attempt 2: Failed → Wait 2 seconds  
Attempt 3: Failed → Wait 4 seconds
Attempt 4: Failed → Wait 8 seconds
Attempt 5: Failed → Wait 16 seconds
Attempt 6: Failed → Give up (or wait 32 seconds max)

Why this works:

Gives the API time to recover
Reduces server load during problems
Shows respect to the service you're using

The Jitter Secret (Preventing Traffic Jams)

Here's a problem: What if 1,000 people all fail at the same time and all wait exactly 2 seconds?

Without randomization:

┌─────────────────────────────────────────┐
│ 9:00:00 → 1,000 requests → ALL FAIL     │
│ 9:00:02 → 1,000 retries  → ALL FAIL     │
│ 9:00:06 → 1,000 retries  → ALL FAIL     │
└─────────────────────────────────────────┘
         Problem NEVER gets solved!

With randomization (jitter):

┌─────────────────────────────────────────┐
│ 9:00:00 → 1,000 requests → ALL FAIL     │
│ 9:00:01.6 → 50 retries   → Success ✓    │
│ 9:00:01.9 → 100 retries  → Success ✓    │
│ 9:00:02.1 → 150 retries  → Success ✓    │
│ 9:00:02.4 → 200 retries  → Success ✓    │
│   ... spread across 800ms window        │
└─────────────────────────────────────────┘
         Smooth recovery!

We add ±20% randomness to prevent everyone from retrying at once. It's like zipper merging in traffic—much more efficient!

How All Four Layers Work Together

Let's follow a single request through the system:

The Perfect Path (With Server Headers)

1. Request arrives
2. Token available? → YES
3. Make API call → SUCCESS
4. Read response headers: "7/10 remaining"
5. Rate limiter: "Good capacity! Staying at current speed"
6. Process next request smoothly

The Proactive Path (Headers Prevent Problems)

1. Request arrives
2. Token available? → YES
3. Make API call → SUCCESS
4. Read response headers: "2/10 remaining" ⚠️
5. Rate limiter: "Whoa! Getting low! Reducing speed by 60%"
6. NEW SPEED: 10 → 4 req/sec
7. Next requests are slower
8. Later headers show: "6/10 remaining" ✅
9. Rate limiter: "Traffic clearing! Gradually increasing speed"
10. ZERO 429 errors encountered!

The Recovery Path (If Headers Aren't Available or We Miss Them)

1. Request arrives  
2. Token available? → YES
3. Make API call → 429 RATE LIMIT!
4. Tell rate limiter: "We got rejected!"
5. Rate limiter: "Oops! I'll slow down by 30%"
6. Wait 2.3 seconds (with jitter)
7. Try again → SUCCESS

The Circuit Breaker Path (Serious Problems)

1-10. Ten requests in a row → ALL FAIL
11. Rate limiter: "STOP EVERYTHING!"
12. Reduce speed to 10% of original
13. Take a 5-second coffee break ☕
14. Resume slowly
15. Gradually recover as things improve

Think of it like a self-driving car:

Layer 0: GPS warns about traffic ahead (headers)
Layer 1: Cruise control maintains safe speed (token bucket)
Layer 2: Automatic braking when needed (exponential backoff)
Layer 3: Anti-collision system prevents pile-ups (jitter)

Why Should YOU Care?

For Developers

Better User Experience:

Users don't need to understand rate limits
"It just works" out of the box

- Automatic recovery from transient failures

The Bigger Picture: Being a Good API Citizen

This isn't just about making our tool work better. It's about playing nice in a shared ecosystem.

Six Key Principles (For Everyone!)

Whether you're building a CLI tool, web app, or mobile app:

Listen First - Check what the API is telling you (use rate limit headers!)
Respect Speed Limits - Just like driving, follow the rules
Learn from Mistakes - If you fail, adapt your behavior
Be Patient - Sometimes waiting is faster than rushing
Avoid Rush Hour - Spread out your requests
Know When to Stop - Don't keep trying if something's really broken

Four Things to Remember

Listen > Guess - Use rate limit headers when available for perfect information
Prevention > Reaction - Don't wait for errors, control your speed proactively
Adapt > Assume - API capacity varies; adjust based on real feedback
Coordinate > Compete - When multiple clients fail, don't all retry at once

💬 Your Turn!

Have you dealt with rate limiting nightmares? Share your stories in the comments!

Questions I'd love to discuss:

What's your worst API rate limit horror story?
How do you handle rate limits in your projects?
Are you using client-side rate limiting? Why or why not?

Want to Learn More?

For the technically curious:

How Token Bucket Algorithm Works - Visual explanation
AWS on Exponential Backoff and Jitter - From the experts

From Monolithic CLIs to Modular Plugins: Applying the Strangler Fig Pattern

Aman Kumar — Thu, 04 Dec 2025 03:41:49 +0000

How the same patterns that saved backend APIs can transform your CLI architecture

💡 TL;DR - The Safe Migration Strategy:

Extract commands to external plugins (publish as beta)

Add plugins as dependencies in your core (v2.x - zero breaking changes)

Gather feedback, iterate, stabilize

Remove dependencies in v3.0.0 (breaking change, but prepared)

Users install only what they need

Result: Safe migration + independent plugin evolution

Remember when your CLI was just a little tool with 3 commands? Yeah, me too.

Then product asked for "just one more feature"... and another... and another. Now you're maintaining a 50-command behemoth where changing one line breaks three unrelated commands. Welcome to the CLI monolith trap.

Here's the thing: CLIs go through the exact same evolution as backend APIs. And guess what? The same architectural patterns that rescued backend teams work beautifully for CLIs too.

In this post, I'll show you:

Why CLI monoliths form (spoiler: it's inevitable)
How plugin architectures mirror microservices
How to use the Strangler Fig Pattern for safe migration
Real benefits you'll see immediately

The Problem: How CLIs Become Unmaintainable

Your CLI probably started like this:

cli/
├── commands/
│   ├── deploy.js
│   └── status.js
├── utils/
│   └── helpers.js
└── index.js

Clean. Simple. Everything in its place.

Six months later:

cli/
├── commands/ (37 files)
├── utils/ (23 files)
├── services/ (15 files)
├── integrations/ (12 files)
└── shared/ (who even knows?)

And now you're dealing with:

Tight coupling - Every command imports 10+ utility files
Shared state nightmares - Global config that everything touches
Risky releases - One change requires testing the entire CLI
Slow development - Adding features takes weeks of coordination
Breaking change hell - Can't evolve one part without breaking everything

Sound painfully familiar? You've built a monolith.

💡 The Backend Lesson: From Monoliths to Modularity

The backend world already solved this problem. Let me show you the evolution:

The Old Way (Monolithic API)

Everything in one codebase
↓
Tightly coupled domains
↓
Coordinated releases
↓
High-risk deployments
↓
Slow feature velocity

The Modern Way (Microservices/Modular)

Thin API Gateway
↓
Isolated domain services
↓
Independent deployments
↓
Versioned contracts
↓
Fast, safe iterations

The key insight?

Isolate domains. Establish clear boundaries. Enable independent evolution.

Here's the beautiful part: This works for CLIs too!

🏗️ The Solution: Core + Plugins Architecture

Think of it like this:

Core = API Gateway (stable, lightweight, routing layer)
Plugins = Microservices (isolated domains with independent lifecycles)

The Thin Core

Your core should be boring and stable:

core/
├── auth/           // Auth logic
├── config/         // Config management  
├── dispatcher/     // Command routing
├── utils/          // Cross-cutting concerns
└── plugin-loader/  // Plugin discovery

That's it. The core provides infrastructure and gets out of the way.

The Plugins

Each plugin is a self-contained domain:

plugins/
├── deploy-plugin/
│   ├── commands/
│   ├── tests/
│   ├── README.md
│   └── package.json  // Independent versioning!
├── logs-plugin/
└── backup-plugin/

Each plugin:

Owns exactly one responsibility
Has its own semantic version
Installs independently (npm i @cli/deploy-plugin)
Changes without affecting others
Tests in complete isolation

🌳 The Migration Strategy: Strangler Fig Pattern

"Cool story," you're thinking, "but I have a 50k-line CLI. I'm not rewriting everything."

Good news: You don't have to!

Enter the Strangler Fig Pattern (from Martin Fowler). It lets you migrate gradually without a risky big-bang rewrite.

How It Works

The pattern is named after strangler fig trees that grow around other trees, eventually replacing them. Same concept for code.

Here's how to apply it to your CLI:

Step 1: Release External Plugins in Beta

Start by extracting functionality into external plugins and release them in beta:

# Release your first plugin in beta
npm publish @my-cli/deploy-plugin@1.0.0-beta.1
npm publish @my-cli/logs-plugin@1.0.0-beta.1

Why beta?

Users can opt-in to test
You can iterate quickly
Breaking changes are expected
Gives you real-world feedback

// deploy-plugin/package.json
{
  "name": "@my-cli/deploy-plugin",
  "version": "1.0.0-beta.1",
  "main": "dist/index.js",
  "peerDependencies": {
    "@my-cli/core": "^2.0.0"
  }
}

Step 2: Add Plugins as Dependencies in Core (Temporarily)

During migration, include plugins as dependencies in your core package:

// core/package.json
{
  "name": "@my-cli/core",
  "version": "2.5.0",
  "dependencies": {
    // Legacy plugins bundled during migration
    "@my-cli/deploy-plugin": "^1.0.0-beta.1",
    "@my-cli/logs-plugin": "^1.0.0-beta.1"
  }
}

What happens:

Users install core → plugins come along automatically
No breaking changes for existing users
Plugins work standalone for early adopters
You validate the plugin architecture safely

Step 3: Gradually Migrate Commands

Track your progress as you extract:

v2.5.0 (Initial Beta)

 deploy  → Plugin (bundled as dependency)
 logs    → Legacy in core
 backup  → Legacy in core

v2.8.0 (Beta 2)

 deploy  → Plugin (bundled as dependency)
 logs    → Plugin (bundled as dependency)
 backup  → Legacy in core

Each step:

Ships to production safely
Users see no difference
Plugins mature in the wild
You gather feedback

Step 4: The Big Switch - Remove Dependencies (v3.0.0)

Once all plugins are stable, release a breaking change that removes plugin dependencies:

// core/package.json v3.0.0
{
  "name": "@my-cli/core",
  "version": "3.0.0",
  "dependencies": {
    // No more plugin dependencies!
  },
  "peerDependencies": {
    // Plugins are now optional
  }
}

Migration guide for users:

# Old way (v2.x) - everything bundled
npm install -g @my-cli/core

# New way (v3.x) - install what you need
npm install -g @my-cli/core
npm install -g @my-cli/deploy-plugin  # Only if you need deploy
npm install -g @my-cli/logs-plugin    # Only if you need logs

Why this is a major version:

Breaking change: plugins no longer auto-installed
Users must explicitly install plugins they use
But: more control, smaller footprint, faster installs

Step 5: Users Install According to Their Needs

Now users have full control:

# Minimal installation (just core utilities)
npm install -g @my-cli/core

# À la carte (only what I use)
npm install -g @my-cli/core @my-cli/deploy-plugin

# Everything (opt-in to all plugins)
npm install -g @my-cli/all  # Metapackage

Benefits:

Smaller installations (15MB vs 250MB)
Faster startup (fewer plugins to load)
Better security (only install trusted plugins)
Independent updates (update deploy plugin without touching core)

The Result: Independent Plugin Releases

Once your plugins are stable and external, this is where the magic happens:

The Old Way (v2.x - bundled):

# Breaking change in deploy command
# Forces major version bump for ENTIRE CLI
npm publish @my-cli/core@3.0.0

# Now everyone needs to:
# - Update the entire CLI
# - Regression test everything
# - Coordinate with all teams

The New Way (v3.x - modular):

# Breaking change in deploy plugin only
npm publish @my-cli/deploy-plugin@3.0.0

# Everything else?
# - Core stays at v3.x
# - Logs plugin stays at v1.5.3
# - Backup plugin stays at v2.1.0
# - Zero cross-testing needed

This is massive for teams with multiple stakeholders!

Even better: Users who don't use deploy aren't affected at all!

End State: Minimal Core, Maximum Flexibility

After migration, your core becomes tiny and stable:

// Final core: ~500 lines total
core/
├── auth.ts        // 150 lines
├── config.ts      // 120 lines  
├── dispatcher.ts  // 100 lines
├── loader.ts      // 80 lines
└── utils.ts       // 50 lines

Everything else lives in plugins:

plugins/
├── @my-cli/deploy-plugin   (v2.0.0)
├── @my-cli/logs-plugin     (v1.5.3)
├── @my-cli/backup-plugin   (v3.1.0)
├── @my-cli/migrate-plugin  (v1.0.0-beta.2)
└── @my-cli/docs-plugin     (v2.2.1)

The core is now:

Easy to maintain (rarely changes)
Easy to test (minimal surface area)
Easy to understand (just infrastructure)
Boring (in the best way!)

The Benefits: Why This Matters

Faster Release Velocity

Before:

"We need to schedule a CLI release. When can everyone test their parts? How about 2 weeks from now?"

After:

"Deploy plugin v2.4.0 is live. Changelog in Slack. Carry on!"

Isolated Breaking Changes

Before:

One breaking change → Entire CLI bumps to v3.0.0

After:

One breaking change → That plugin bumps to v3.0.0
                    → Everything else stays put

Users Install Only What They Need

Before:

npm install -g my-cli
# Downloads: 250MB (includes 30 commands you never use)

After:

npm install -g @my-cli/core           # 12MB
npm install -g @my-cli/deploy-plugin  # 8MB
npm install -g @my-cli/logs-plugin    # 5MB
# Downloads: 25MB (only what you need!)

Faster installs. Smaller footprint. Happier users.

🤔 "Won't this break my existing users?"

Not with the beta approach! That's the beauty of it:

v2.x: Plugins bundled as dependencies → Zero breaking changes
v3.x: Plugins separate → Breaking change, but well-communicated
Users get months to prepare during the beta phase
Migration guide makes the transition smooth

"Why not just make v3.0 immediately?"

Risk management!

By bundling plugins as dependencies in v2.x first:

You prove the plugin architecture works
Users can test beta plugins early
You gather real-world feedback
No one's workflow breaks during migration
The v3.0 switch is just removing deps (lower risk)

"What about users who want everything?"

Create a metapackage:

// @my-cli/all/package.json
{
  "name": "@my-cli/all",
  "version": "3.0.0",
  "dependencies": {
    "@my-cli/core": "^3.0.0",
    "@my-cli/deploy-plugin": "^2.0.0",
    "@my-cli/logs-plugin": "^1.5.3",
    "@my-cli/backup-plugin": "^3.1.0"
  }
}

npm install -g @my-cli/all  # One command, everything installed

Best of both worlds!

"How do I handle shared code between plugins?"

Rule of thumb:

Used by one plugin → Keep it in the plugin
Used by two plugins → Maybe extract to @my-cli/shared package
Used by three+ plugins → Belongs in core utilities
Used by external plugins → Definitely in core (stable API)

"What if I'm building a new CLI from scratch?"

Even better! Start with the plugin architecture from day one:

Build the thin core first
Make your first command a plugin (proves the pattern)
Release everything as stable v1.0.0 together
Every new feature becomes a new plugin
Future you will be so grateful

But: Still consider releasing as a monolith initially (v1.x), then split in v2.x once you understand usage patterns.

What Changed?

Benefits you get immediately:

Clear interface - Plugin contract vs monolith spaghetti
Injected dependencies - No more deep imports
Self-contained logic - Plugin owns its domain
Trivial testing - Mock the context, done
Independent releases - Deploy updates without touching core
Smaller installs - 25MB vs 250MB

Wrapping Up

CLIs are going through the same architectural evolution that backend systems experienced years ago:

From	To
Monolithic	Modular
Tightly Coupled	Plugin-Based
Coordinated Releases	Independent Lifecycles
Risky Changes	Isolated Changes
Slow Development	Fast Iterations

The Strangler Fig Pattern with Beta Releases gives you a safe, incremental path to get there without a risky rewrite.

The secret sauce:

Extract to external plugins (beta)
Bundle them temporarily (v2.x - safe transition)
Remove dependencies (v3.0.0 - breaking change, but prepared)
Independent evolution forever

By keeping your core thin and moving features into independent plugins, you create a CLI that is:

Easier to maintain - Smaller, focused codebases
Safer to extend - Changes are isolated
Faster to iterate - No coordination needed
More stable for users - Breaking changes are scoped
Future-proof - New plugins without touching core
Lighter weight - Install only what you need

If you're building or maintaining a CLI, modularity isn't optional anymore - it's your architectural advantage.

Start today: Extract one command to a beta plugin. See how it feels. You'll never look back.

Have you hit the CLI monolith wall? What's your biggest pain point with CLI architecture?

Thinking about plugins? What's holding you back?

How Airline Group Fares Really Work: The Business & Tech Behind 'TBA' Passenger Names

Aman Kumar — Fri, 07 Nov 2025 12:48:48 +0000

If you've ever seen "TBA/TBA" as a passenger name in a flight booking, it's not a glitch—it's a feature. After booking a cheap group fare on Yatra.com, I discovered the hidden world of airline group bookings, and uncovered a real bug with same-name passengers.

In this post, we'll unpack:

How group fare booking systems work
Why "TBA" exists in airline PNRs
What developers building travel systems should know
A critical bug I found: Same-name passengers causing seat swaps

✈️ 1. What Are Group Fares?

Group fares are special airline rates for 10+ passengers traveling together on the same flight and date.

Common use cases:

🏢 Corporate trips
💒 Weddings and family gatherings
🕌 Pilgrimage or religious tours
🏀 School or sports teams

Unlike individual bookings, group fares are:

Negotiated directly with airlines or via GDS
More flexible with payment schedules
Allow placeholder names initially

2. Business Logic: The Group Booking Flow

Here's how it works from an OTA or travel agent's perspective:

Step	Process	Description
1️⃣	Group Quote Request	Agency requests fare for route, date, and passenger count
2️⃣	PNR Creation (TBA stage)	Airline/GDS creates group PNR with placeholders like `TBA/TBA`
3️⃣	Deposit & Hold	Group pays deposit to hold seats
4️⃣	Name Finalization	12–72 hours before flight, replace "TBA" with real names
5️⃣	Ticketing	Once names finalized, tickets are issued

📋 3. What Does "TBA" Actually Mean?

TBA = To Be Advised

When creating a group booking, actual passenger details may not be known yet.

Example in GDS (Amadeus/Sabre):

Each entry reserves a seat while allowing the agent to:

Hold inventory without final names
Track blocked seats in airline systems
Display flight details before passenger confirmation

How GDS Systems Power This Magic

Behind the scenes, OTAs don't talk directly to each airline. They use GDS (Global Distribution System) — think of it as the "API gateway" of the travel industry.

The Big Three:

Amadeus (European dominance)
Sabre (Strong in Americas)
Travelport (Galileo/Worldspan/Apollo)

⏰ 4. The 12-Hour Rule

Most airlines require final passenger names no later than 12 hours before departure.

What happens at finalization:

✅ All "TBA" placeholders updated with real names
⚠️ Unnamed passengers may auto-cancel
🎫 Group PNR transitions to ticketed state

This is why Yatra/MMT show "flight details visible before 12 hours" — the system holds the group block, but names are pending.

5. System Architecture Flow

Key technical points:

Placeholders stored in PNR until replaced
Airlines track via group booking IDs (not individual tickets)
Background jobs handle PNR sync and updates

💻 6. How OTAs Handle This (Developer View)

For platforms like Yatra or MakeMyTrip:

// Simplified model
const groupBooking = {
  pnr: "ABC123",
  status: "TBA_PENDING",
  passengers: [
    { firstName: "TBA", lastName: "TBA", title: "MR" },
    { firstName: "TBA", lastName: "TBA", title: "MS" }
  ],
  finalizationDeadline: "2025-11-08T10:00:00Z",
  flightDetails: { visible: false } // visible after name update
};

Backend requirements:

Handle placeholder data models
Schedule PNR refresh/update jobs
Implement deadline alerts
Validate against duplicate names (see bug below!)

7. CRITICAL BUG I DISCOVERED: Same-Name Collision

The Problem

When booking through Yatra's group fare system, I found:

If two passengers have the same name:

❌ During web check-in, the system will display both passengers names when the PNR and last name are entered together.
❌ Boarding passes get mixed up
❌ Airport staff can't distinguish passengers
❌ Potential security and check-in issues

Example Scenario

// Booking for two people with same name
passengers: [
  { firstName: "Amit", lastName: "Kumar", seat: "12A" },
  { firstName: "Amit", lastName: "Kumar", seat: "12B" }
]

// What happens in airline system:
// PNR shows: KUMAR/AMIT MR + KUMAR/AMIT MR
// Boarding pass generates wrong seat for one passenger

Why This Happens

GDS Name Formatting: Airlines use PNR and LASTNAME combination
Duplicate Detection: System may treat as duplicate entry
Seat Assignment Logic: Uses last name as primary key
Group PNR Merge: Multiple "AMIT KUMAR" entries cause confusion

Recommended fixes for OTAs:

🔍 Pre-booking validation for duplicate last names
📝 Force middle name or mobile number for duplicates

🔮 8. Future: NDC and Modern APIs

IATA's NDC (New Distribution Capability) is modernizing group fares:

⚡ Real-time quotes and seat holds
🔄 Easier passenger data updates via REST APIs
📉 Reduced reliance on "TBA" placeholders
🤝 Direct airline-to-OTA connections

Though many airlines still support TBA for backward compatibility.

9. Key Takeaways

Point	Reality Check
✅ "TBA" is a feature, not a bug	Intentional placeholder system for group inventory management
⏰ The 12-hour rule has a twist	Names often start reflecting from midnight (not exactly 12 hours), which can frustrate travelers expecting earlier updates
💰 How OTAs really make money	Indian OTAs like Yatra/MMT book group fares and mark them up—this is on top of convenience charges. That "cheap fare" might just be a group booking arbitrage
🚨 Same-name = system chaos	Multiple passengers with identical last names create PNR conflicts, seat swaps, and boarding issues
🎭 The agent model	OTAs aren't always direct airline partners—many operate as super-agents booking group blocks and reselling individually

💬 Discussion

For developers building travel systems:

How does your system handle group booking placeholders?
Ever encountered the same-name bug I found?

Drop your experiences in the comments! 👇

🔗 Useful Resources

This post is based on real-world experience booking through Yatra.com. If you found this helpful, consider sharing it with your travel-tech friends! ✈️

Tags: #traveltech #backend #systemdesign #api #devstory

How YouTube Tracks Your Location Even with GPS and History Turned Off

Aman Kumar — Tue, 14 Oct 2025 20:55:40 +0000

"I had location turned off. I was in incognito mode. Still, YouTube recommended a nearby concert of the band I just listened to. What?!"

If that sounds familiar, you're not alone. Many users have reported the accuracy of YouTube's recommendations, especially around location-based content—even when they've gone to great lengths to remain private.

Let's break down how YouTube (and by extension, Google) can still estimate your location without GPS, location history, or account activity.

🛰️ 1. IP Address Geolocation – The Primary Tracker

Even without GPS, your IP address gives away your general location.

Every internet-connected device is assigned an IP address by your Internet Service Provider (ISP). These addresses are mapped to geographic regions using public and commercial IP geolocation databases.

Accuracy: Generally within 50–100 km, but it can be even more precise—especially in cities.

// Example: How IP geolocation might work
fetch('https://ipapi.co/json/')
  .then(response => response.json())
  .then(data => {
    console.log(`City: ${data.city}`);
    console.log(`Region: ${data.region}`);
    console.log(`Country: ${data.country_name}`);
    // YouTube uses similar (but more sophisticated) techniques
  });

✅ You can't completely hide from IP-based geolocation unless you're using a VPN or proxy.

🔐 2. Google Account Data (Even If You're in Incognito)

Even if you're browsing in Incognito Mode, Google might still know who you are if:

You're logged into a Google account in another tab or device
You've ever saved a home or work address in your Google Account
You've used Google Maps or other location-based services in the past

Google keeps past location history (if it was ever turned on) and uses that to infer your habits and regions of interest.

💡 Dev Tip: Incognito mode only prevents local storage—it doesn't prevent network-level tracking.

🧠 3. Device & Network Fingerprinting

Google collects metadata from your device and local network to build a digital fingerprint, including:

Wi-Fi network names (SSID) and nearby access points
Device timezone, language, and region settings
Your ISP and general network behavior

This information can correlate with known locations and help Google guess your approximate whereabouts, even without direct GPS data.

// Browser fingerprinting example
const fingerprint = {
  timezone: Intl.DateTimeFormat().resolvedOptions().timeZone,
  language: navigator.language,
  platform: navigator.platform,
  screenResolution: `${screen.width}x${screen.height}`,
  // ... and dozens more data points
};

🔄 4. Cross-Device & Cross-Platform Learning

If you're using multiple devices connected to the same Google account or Wi-Fi network, Google's ecosystem shares information across them:

A smart TV, laptop, or tablet on the same home network might leak contextual data to your phone
YouTube recommendations can be influenced by other people watching on the same IP or shared account (roommates, family, etc.)
Even if you didn't search for a concert, your household might have, and that can affect what shows up

😱 Real-World Example: YouTube Recommending Nearby Concerts

Here's what likely happened in this scenario:

The user listened to a band in YouTube's incognito mode
YouTube picked up their IP address (revealing their approximate location)
It correlated that with known tour dates in that area
Recommendation: "🎤 Don't miss [Band Name] live in [Your City]!"

All that, without needing GPS or location history.

🔐 How to Protect Yourself (If You Want To)

If you're concerned about this level of tracking, here are some steps:

For Regular Users:

✅ Use a reliable VPN to mask your IP address
🚫 Avoid logging into Google accounts when browsing privately
📵 Turn off YouTube watch history and ad personalization
⚙️ Regularly clear cookies and site data from your browser

For Developers:

🧪 Consider using privacy-focused alternatives (e.g., NewPipe for YouTube, or Firefox Focus)
🔍 Implement Privacy by Design principles in your own applications
📊 Be transparent about data collection in your projects

⚠️ Note: Even with these measures, total privacy is difficult in an ecosystem as interconnected as Google's.

🏗️ Implications for Web Developers

As developers, we should be aware of these tracking mechanisms:

User Trust: Be transparent about what data you collect
GDPR/Privacy Laws: Ensure compliance with regulations
Ethical Considerations: Just because you can track users doesn't mean you should
Alternative Monetization: Explore privacy-respecting business models

// Example: Respect user privacy preferences
if (navigator.doNotTrack === "1") {
  // Skip analytics and personalization
  console.log("User has requested not to be tracked");
} else {
  // Initialize analytics with consent
  initAnalytics();
}

🔍 Final Thoughts: You're Not Paranoid—It's Just Smart Algorithms

YouTube's ability to serve accurate, location-based recommendations without GPS or location sharing isn't magic—it's data science.

By blending signals from your IP address, network environment, device metadata, and cross-platform behavior, YouTube can pinpoint your probable location with surprising accuracy.

So, the next time you see a "nearby" event on YouTube while in incognito mode… know that it's not spying—it's just very, very good at guessing.

📚 Additional Resources

What's your experience with location-based recommendations? Have you noticed similar patterns? Share your thoughts in the comments below! 👇

Best Practices for Public npm Packages: Lock Files, Publishing & Dependency Management

Aman Kumar — Mon, 06 Oct 2025 13:30:21 +0000

Confused about whether to commit package-lock.json when publishing to npm? Here's the standard practice for public repositories.

When maintaining an open source project or reusable package on npm, it’s easy to run into uncertainty:

Should you commit package-lock.json?
How do you ensure consistent dependency resolution?
What do end users get when they install your package?

This post breaks down the standard industry practice for open-source npm packages — especially regarding lock files, dependency pinning, CI, and secure publishing.

🔒 Should I Commit `package-lock.json`?

Yes, commit package-lock.json to your Git repo — but know that:

package-lock.json is ignored when you publish a package to the npm registry.

This means it benefits you and your contributors, but has no direct effect on your package consumers.

Benefits of committing it:

✅ Consistent installs during development
✅ Reproducible CI environments
✅ Easier debugging & auditing
✅ Clear diffs when dependencies are upgraded

📦 What Gets Published to npm?

By default, npm publishes:

Your package.json
Files not listed in .npmignore (or included in the files field)
But not package-lock.json (unless you publish a npm-shrinkwrap.json — more on that below)

TL;DR:

Consumers install dependencies based on your package.json semver ranges, not your lock file.

🛠 How to Pin Dependencies for Safety

Even though you can’t ship a lock file, you can prevent surprises:

✅ Use exact versions in `package.json`:

"dependencies": {
  "lodash": "4.17.21"   // Not ^4.17.21
}

Avoid semver ranges like ^ or ~ if you want deterministic installs.

📄 What About npm-shrinkwrap.json?

npm-shrinkwrap.json is published with your package and locks the entire dependency tree.
But:
⚠️ It can conflict with your consumers' dependencies
⚠️ It makes updating harder for downstream projects
✅ Useful for CLI tools or apps where you want full control of the install
For libraries, it's not standard to use shrinkwrap.

🧪 CI & Testing Best Practices

Use npm ci in CI — this installs from the lock file and ensures reproducible builds.
Test the final output using:
npm pack
This shows you exactly what your users will get before you publish.
Automate checks before publishing:

"scripts": {
  "prepublishOnly": "npm test && npm run lint && npm run build"
}

🤝 Use Peer Dependencies Wisely

If your library is designed to plug into another framework (e.g. React, Next.js, ESLint):
Declare those as peerDependencies in package.json.
Don’t bundle them in your dependencies.
This avoids version conflicts and duplication.
Example:

"peerDependencies": {
  "react": "^18.0.0"
}

🔐 Security Practices

Run npm audit regularly
Use tools like:
Dependabot
Snyk
GitHub security alerts

Keep your dependencies updated — responsibly!

✨ Final Thoughts

Committing your lock file doesn’t harm your npm package — it helps your team. And while npm won’t publish it, you can still enforce reliable builds and secure installs by pinning versions, using CI properly, and testing your tarballs.
If you’ve ever been burned by a subtle dependency upgrade breaking your users — you’re not alone. Following these practices can save you (and your users) hours of debugging.