Rani Zilpelwar’s Post

🔬 SDK Architecture Deep Dive — Building a great SDK is far more than writing convenient wrappers around an API. It demands thoughtful systems design that carefully balances abstraction, performance, extensibility, and long-term maintainability. Here’s what a robust modern SDK architecture typically involves: Layered Architecture: Clean separation between transport, protocol, domain logic, and developer-facing interfaces Strong Typing & Schema-Driven Generation: Ensuring contract fidelity through code generation from OpenAPI, Protocol Buffers, or similar schemas Middleware & Interceptor Pipelines: Elegant handling of cross-cutting concerns like authentication, retries, rate limiting, telemetry, logging, and caching Concurrency & Async Models: Well-designed async/await patterns and thread-safety that work consistently across languages and runtime environments Structured Error Taxonomy: Predictable, actionable error handling that helps developers debug and recover gracefully Semantic Versioning & Compatibility: Strategies for evolving the SDK without breaking existing integrations Dependency Injection & Modularity: Enabling easy testing, customization, and extension by advanced users Built-in Observability: Rich instrumentation hooks for tracing, metrics, and debugging in production From a systems and research lens, SDK design lives at the fascinating intersection of API ergonomics, distributed systems reliability, and software architecture principles. I’m particularly interested in the trade-offs: How much abstraction is too much? When does flexibility become complexity? How do large organizations manage SDKs across dozens of languages and hundreds of versions? If you’re working on SDKs, developer platforms, API infrastructure, or systems tooling — I’d love to hear your thoughts, war stories, or favorite design patterns in the comments. #SDK #SoftwareArchitecture #SystemsDesign #DistributedSystems #APIEngineering #DeveloperExperience #DevTools #ResearchEngineering

𝗖𝗟𝗔𝗨𝗗𝗘. 𝗺𝗱 𝗶𝘀 𝗻𝗼𝘁 𝗮 𝗥𝗘𝗔𝗗𝗠𝗘. It's onboarding docs for your AI teammate. Most engineers treat it like a wiki page. That's why their agents drift, hallucinate conventions, and rebuild the same patterns three different ways. A CLAUDE. md that actually works is an architecture decision — not a documentation chore. Here's the structure I've been refining: 𝗧𝗵𝗲 𝟯 𝘀𝗰𝗼𝗽𝗲𝘀 (𝗹𝗮𝘀𝘁 𝗼𝗻𝗲 𝘄𝗶𝗻𝘀)  → Global · ~/.claude/CLAUDE. md — your defaults across every project  → Project · ./CLAUDE. md — build commands, test setup, team conventions  → Folder · ./src/CLAUDE. md — module-level overrides for APIs, components, utils 𝗧𝗵𝗲 𝗪𝗵𝗮𝘁 / 𝗪𝗵𝘆 / 𝗛𝗼𝘄 𝗳𝗿𝗮𝗺𝗲𝘄𝗼𝗿𝗸  → 𝗪𝗛𝗔𝗧 — project name, tech stack, repo map, key dependencies  → 𝗪𝗛𝗬 — architecture decisions, naming conventions, anti-patterns  → 𝗛𝗢𝗪 — npm run build, npm test, eslint --fix, commit format, deploy steps 𝟱 𝗿𝘂𝗹𝗲𝘀 𝘁𝗵𝗮𝘁 𝘀𝗲𝗽𝗮𝗿𝗮𝘁𝗲 𝗰𝗵𝗮𝗼𝘀 𝗳𝗿𝗼𝗺 𝗰𝗹𝗮𝗿𝗶𝘁𝘆  1. Run /init first — let Claude scaffold the baseline, then curate  2. Stay under 500 lines — too long means ignored context  3. Use Hooks for 100% enforcement — CLAUDE. md is ~70% followed  4. Update it monthly — it's a living document, not a setup ritual  5. Reference files, don't duplicate — point to package.json, tsconfig, don't copy contents 𝗩𝗮𝗴𝘂𝗲 𝗸𝗶𝗹𝗹𝘀 𝗶𝘁. 𝗣𝗿𝗲𝗰𝗶𝘀𝗲 𝘀𝗮𝘃𝗲𝘀 𝗶𝘁.  → ❌ "Write clean code"  → ✅ "Use camelCase for variables, PascalCase for components"  → ❌ "Test everything"  → ✅ "npm test --watch, min 80% coverage for utils/" The agents that ship reliably aren't the ones with the smartest models. They're the ones with the cleanest context architecture. What's the one rule in your CLAUDE. md that changed your agent's behavior the most?

Check out my article on the differences between traditional software development and AI-integrated software development. Share & Comment if you find it insightful.

𝗘𝘃𝗲𝗿𝘆 𝘁𝗲𝗮𝗺 𝘂𝘀𝗶𝗻𝗴 𝗖𝗹𝗮𝘂𝗱𝗲 𝗖𝗼𝗱𝗲 𝗵𝗮𝘀 𝗮 𝘄𝗼𝗿𝗸𝗳𝗹𝗼𝘄. 𝗧𝗵𝗲 𝗾𝘂𝗲𝘀𝘁𝗶𝗼𝗻 𝗶𝘀 𝘄𝗵𝗲𝘁𝗵𝗲𝗿 𝗶𝘁'𝘀 𝗶𝗻𝘁𝗲𝗻𝘁𝗶𝗼𝗻𝗮𝗹 𝗼𝗿 𝗮𝗰𝗰𝗶𝗱𝗲𝗻𝘁𝗮𝗹. Coding agents on enterprise codebases need a contract. Here it is 👇 ─────────────────── 🔵 𝗣𝗟𝗔𝗡 Define the feature, scope & constraints before the agent writes a single line. The agent has zero business context. You have all of it. 𝘛𝘩𝘪𝘴 𝘴𝘵𝘦𝘱 𝘪𝘴 𝘺𝘰𝘶𝘳𝘴. 𝘕𝘰𝘵 𝘵𝘩𝘦 𝘢𝘨𝘦𝘯𝘵'𝘴. 🟡 𝗗𝗢𝗖𝗨𝗠𝗘𝗡𝗧 Write a Claude.md — codebase conventions, architecture patterns, what to avoid. This is your agent's brain. 𝘚𝘬𝘪𝘱 𝘪𝘵 𝘢𝘯𝘥 𝘺𝘰𝘶'𝘳𝘦 𝘧𝘭𝘺𝘪𝘯𝘨 𝘣𝘭𝘪𝘯𝘥 𝘦𝘷𝘦𝘳𝘺 𝘴𝘪𝘯𝘨𝘭𝘦 𝘵𝘪𝘮𝘦. ⚡ 𝗖𝗢𝗗𝗘 Let it generate. Boilerplate, scaffolding, repetitive logic — it shines here. Complex business logic & edge cases? 𝘐𝘵 𝘭𝘪𝘦𝘴. 𝘊𝘰𝘯𝘷𝘪𝘯𝘤𝘪𝘯𝘨𝘭𝘺. 🔴 𝗥𝗘𝗩𝗜𝗘𝗪 Treat every output like a PR from a brilliant-but-junior dev. Read it. Question it. Simplify it. 𝘠𝘰𝘶𝘳 𝘯𝘢𝘮𝘦 𝘪𝘴 𝘰𝘯 𝘵𝘩𝘦 𝘤𝘰𝘮𝘮𝘪𝘵. 𝘈𝘤𝘵 𝘭𝘪𝘬𝘦 𝘪𝘵. ─────────────────── 🚨 𝟰 𝘀𝗶𝗴𝗻𝘀 𝘆𝗼𝘂𝗿 𝗮𝗴𝗲𝗻𝘁 𝘄𝗼𝗿𝗸𝗳𝗹𝗼𝘄 𝗶𝘀𝗻'𝘁 𝗿𝗲𝗮𝗹: ❌ No Claude.md → the agent guesses your architecture every time ❌ Accepting the first output → plausible ≠ correct ❌ Skipping review → mistakes compound silently across 100k+ lines ❌ Waterfall thinking → generate everything, then try to fix it all at once ─────────────────── 🏆 𝗧𝗵𝗲 𝗿𝘂𝗹𝗲: 🔵 Plan → 𝘰𝘸𝘯𝘴 𝘵𝘩𝘦 𝘎𝘖𝘈𝘓 🟡 Document → 𝘰𝘸𝘯𝘴 𝘵𝘩𝘦 𝘊𝘖𝘕𝘛𝘌𝘟𝘛 ⚡ Code → 𝘰𝘸𝘯𝘴 𝘵𝘩𝘦 𝘚𝘗𝘌𝘌𝘋 🔴 Review → 𝘰𝘸𝘯𝘴 𝘵𝘩𝘦 𝘘𝘜𝘈𝘓𝘐𝘛𝘠 Let the contracts blur → your codebase becomes an unmaintainable mess that moves fast and breaks everything. 𝗧𝗵𝗲 𝗮𝗴𝗲𝗻𝘁 𝗱𝗶𝗱𝗻'𝘁 𝗯𝘂𝗶𝗹𝗱 𝗶𝘁. 𝗬𝗼𝘂 𝗱𝗶𝗱. 🎯 ─────────────────── #ClaudeCode #EnterpriseEngineering #CodingAgents #AI

I am sharing my killer architecture and patterns for developing software with multi-agentic systems. The tools are here. The patterns are learnable. The bottleneck, as always, is discipline in the process. A good process captures all aspects of Multi-Agentic Software Development Life Cycle (MASDLC). Hope you will leverage these concepts. https://lnkd.in/gXt3zPAC #multi-agent #software #development #ai #agents #asdlc

Most developers think software problems come from bad code. But in real systems, 𝐭𝐡𝐞 𝐫𝐞𝐚𝐥 𝐩𝐫𝐨𝐛𝐥𝐞𝐦 𝐢𝐬 𝐧𝐨𝐭 𝐜𝐨𝐝𝐞 — 𝐢𝐭 𝐢𝐬 𝐚𝐫𝐜𝐡𝐢𝐭𝐞𝐜𝐭𝐮𝐫𝐞. We are entering an era where applications are no longer “frontend + backend”. They are becoming distributed API ecosystems. And this is where things start breaking: 👉 Multiple APIs per feature 👉 Different data formats everywhere 👉 Business logic leaking into frontend 👉 No clear ownership of “data flow” 👉 Teams building services in isolation This creates what I call: ⚠️ API Orchestration Chaos And here is the real issue: ❌ Developers mistake it for a coding problem So they try to fix it by: Adding more hooks Writing more client-side logic Creating utility layers everywhere ❌ Companies mistake it for a backend problem So they: Add more microservices Split services further Increase API count But the root problem remains untouched. 🧠 The real cause This chaos happens because: Backend teams design APIs around data models Frontend teams need APIs around user workflows No one owns the end-to-end experience flow This is where architectures like: Backend-for-Frontend (BFF) API Orchestration Layers Experience APIs become critical — not optional. ⚙️ The hidden truth Modern frontend is no longer UI engineering. It is becoming: “Distributed system orchestration at the edge of the user.” And if architecture is wrong, even perfect code cannot save the system. 💡 Key takeaway Before writing more code, ask: 👉 Who owns the data flow for this feature? 👉 Are we building APIs for systems or for users? 👉 Are we scaling architecture or just scaling complexity? Because in modern systems: “Bad architecture scales faster than bad code.” #SystemDesign #SoftwareArchitecture #API #Microservices #FrontendArchitecture #BackendForFrontend #BFF #DistributedSystems #WebDevelopment #ScalableSystems #SoftwareEngineering #TechArchitecture #DevCommunity #mitprogrammer

The traditional IDE is dead. Software engineering is no longer about writing syntax; it is about orchestrating autonomous agents. Cursor 3 just forced a massive strategic pivot across the enterprise development landscape. It is no longer just a VS Code fork with a chat window—it has evolved into a localized, multi-agent orchestration platform capable of parallel execution across local, cloud, and SSH environments. This mirrors a violent macroeconomic shift in developer tooling. With agentic orchestrators like Conductor recently securing $22M in Series A funding, the market consensus is clear: solo engineers armed with multi-agent workspaces are now outbuilding legacy development teams. The Nexus Titan B2B Desk just published our consensus review and architectural breakdown of Cursor 3. We look past the hype to evaluate its true enterprise deployment viability, token-cost scaling, and automated Git isolation capabilities. The Final Verdict: DEPLOY NOW. Read the full technical breakdown and market analysis here: https://lnkd.in/dRrUNt5c

One internal tool I developed previously was essentially a CLI-driven source code scaffolding engine enhanced with AI-assisted generation. From a technical perspective, it functioned as an interactive code generation framework where a user could launch the command line interface, answer structured prompts (functions, classes, modules, logic flows, file names, dependencies, architecture choices), and receive immediately generated source code files with a clean project structure. Think of it as a blend of: • Code scaffolding automation • Template-driven software generation • AI-assisted boilerplate reduction • Rapid project initialization tooling • Developer workflow acceleration Instead of manually creating folders, empty files, repetitive class definitions, and starter logic, the system transformed CLI input into structurally sound code artifacts in seconds. Key engineering value: • Reduced setup time for new projects • Enforced consistent architecture patterns • Lowered repetitive manual coding overhead • Accelerated prototyping cycles • Standardized codebase initialization • Enabled fast iteration for solo developers or teams Today this category overlaps with what many call Developer Experience (DX) tooling, Internal Developer Platforms, or AI-native scaffolding systems. Sometimes the biggest productivity gains don’t come from writing more code—they come from removing the need to write the repetitive parts at all.

When Claude Code screws up in production, it's almost never because of the model. 👇🏼 It's because the harness around it is weak. So, what is Harness: The harness is every piece of code, configuration, and execution logic that isn't the model itself. Harness engineering has emerged as a discipline focused on designing systems around #LLMs. In Claude Code, the term "harness" is used in two related but distinct ways. Worth knowing both because the hype slides between them. 👉🏼 1. Claude Code itself is a harness - Tools (like Read, Write, Edit, Bash, Grep, etc.) - A permission system (allow/ask/deny pipeline) - Context management - Hooks: - #Subagents and #MCP - Sandboxing and session state (git worktrees, persistent state, memory, etc.) 👉🏼 2. Harness as a pattern you build on top of Claude Code That's the higher-level orchestration you design for long-running tasks.  - The initialiser + coding agent pattern - The generator + evaluator loop So, when someone says "we built our own harness on Claude Code", they almost always mean that they've added their own hooks, custom skills, project-specific CLAUDE.md files, #MCP servers, permission rules, and orchestration logic on top of the base tool. There's now a whole community of these open-source projects that are essentially opinionated harness configurations that bolt on planning loops, memory, guardrails, and review steps. I will put some in the comments. #ClaudeCode #AIEngineering #LLMOps #HarnessEngineering #AgenticAI #AIAgents #MCP #Subagents #AIAutomation #DeveloperTools #ProductionAI #PromptEngineering #AIInfra #GenAI #SoftwareEngineering #DevTools #AIArchitecture #OpenSourceAI #AIWorkflows #Guardrails

𝗢𝗻𝗲 𝗼𝗳 𝗺𝘆 𝗔𝗜 𝗮𝗴𝗲𝗻𝘁𝘀 𝘁𝘂𝗿𝗻𝗲𝗱 𝟴𝟬 𝗺𝗶𝗻𝘂𝘁𝗲𝘀 𝗼𝗳 𝗿𝗲𝗹𝗲𝗮𝘀𝗲 𝘄𝗼𝗿𝗸 𝗶𝗻𝘁𝗼 𝟯𝟬 𝘀𝗲𝗰𝗼𝗻𝗱𝘀. Every release I did required me to: 1. Checkout to main and git pull in the service repo 2. Check the latest tag and create the new version 3. Push the tag 4. Wait for the CI to finish (~6 min) 5. Verify the container version in the cloud provider 6. Go to the infra repo, update the version in the config files, and open a PR 7. Wait for the CI to pass (~1 min) 8. Merge the changes 9. Wait for the main branch CI (~4 min) 10. Trigger the final production deploy (~4 min) That's 𝟭𝟬 𝘀𝘁𝗲𝗽𝘀. ~20 minutes per release. Multiply that by 4 repositories — that's 80 minutes of my day, gone. So I built an agentic workflow with Claude Code + Obsidian to handle it all. Obsidian is the brain — it holds the agent instructions, a release template the agent fills in as it goes, and a dated history of every release for full traceability. I started with Claude Code's "Accept Edits" mode — reviewing every step, catching gaps, and refining the instructions in real time. Only after validating it multiple times did I switch to "Bypass Permissions" mode — letting the agent run 95% autonomously. The other 5%? Sensitive actions like merging PRs — the agent pauses and waits for my approval. I also use the /loop command to poll CI pipelines every 2 minutes — the agent monitors builds and lets me know the moment they finish. 𝗡𝗼 𝗺𝗼𝗿𝗲 𝘁𝗮𝗯-𝘀𝘄𝗶𝘁𝗰𝗵𝗶𝗻𝗴 𝘁𝗼 𝗰𝗵𝗲𝗰𝗸 𝗶𝗳 𝘁𝗵𝗲 𝗖𝗜 𝗽𝗮𝘀𝘀𝗲𝗱. The best part? The agent runs multiple releases in parallel — spinning up sub-agents, one per repo. Instead of 80 min of sequential work: 30 seconds of input, ~15 min of autonomous execution. 𝗧𝗵𝗲 𝗯𝗲𝘀𝘁 𝗮𝗴𝗲𝗻𝘁𝗶𝗰 𝘄𝗼𝗿𝗸𝗳𝗹𝗼𝘄𝘀 𝗮𝗿𝗲𝗻'𝘁 𝗯𝘂𝗶𝗹𝘁 𝗶𝗻 𝗼𝗻𝗲 𝘀𝗵𝗼𝘁. They're refined through iteration — start supervised, validate, then gradually increase autonomy. What repetitive process are you still doing manually that an agent could handle? #AI #ClaudeCode #DevOps #Automation #AgenticWorkflows #SoftwareEngineering #DeveloperProductivity #Obsidian