Ranjan Kumar

𝐂𝐥𝐚𝐮𝐝𝐞 𝐂𝐨𝐝𝐞 𝐨𝐧 𝐁𝐫𝐨𝐰𝐧𝐟𝐢𝐞𝐥𝐝 𝐂𝐨𝐝𝐞𝐛𝐚𝐬𝐞𝐬: 𝐓𝐡𝐞 𝐇𝐚𝐫𝐧𝐞𝐬𝐬 𝐈𝐬 𝐭𝐡𝐞 𝐏𝐫𝐨𝐝𝐮𝐜𝐭 New project, new codebase - your coding agent shapes conventions and follows them consistently. Legacy codebase - that agent must obey conventions authored years ago by people who left no documentation. Most teams get burned because they expect the model to figure this out on its own. The real bottleneck on brownfield code is not the model's intelligence. It is the 𝐡𝐚𝐫𝐧𝐞𝐬𝐬 - the context you engineer around it. On greenfield, the agent authors its own conventions and stays consistent by construction. On brownfield, it becomes a convention-follower trying to reverse-engineer architectural decisions it never sees. A smaller issue in a single PR. A systemic risk across ten developers, each agent re-inventing logging patterns, query paths, error types slightly differently. Your codebase drifts faster than it did before. Claude Code navigates like an engineer - grep, file reads, reference-following - not via vector indexes. That means what it learns depends entirely on what the harness guides it to read, in what order, under what instructions. You control the signal-to-noise ratio. You shape which conventions enter its context window first. You decide whether it finds your house logger or invents a new one. 𝐓𝐡𝐞 𝐮𝐧𝐜𝐨𝐦𝐟𝐨𝐫𝐭𝐚𝐛𝐥𝐞 𝐭𝐫𝐮𝐭𝐡: Anthropic's own guidance says the constraint is the harness, not the model. The demos showcase greenfield - where the agent's guesses cannot collide with anything. Production is the other case. A million-token window still holds a fraction of your system, and models degrade in reliability as context grows. Without a shared harness across your team, Convention Inversion becomes a tax on every session - slower code review, architectural drift, entropy you have to pay for later. Read the full article to see how to structure the harness, what information to surface first, and how to close the gap between the conventions your codebase enforces and the ones an agent discovers on its own. ranjankumar.in/claude-code-br… Follow Ranjan Kumar for more on context engineering, agentic systems, and how to stay relevant as an engineer in the loop. #ClaudeCode #AIEngineering #CodingAgents #BrownfieldCode #ContextEngineering #AgenticAI #DeveloperTools

𝐇𝐨𝐰 𝐭𝐨 𝐊𝐧𝐨𝐰 𝐘𝐨𝐮𝐫 𝐂𝐥𝐚𝐮𝐝𝐞 𝐂𝐨𝐝𝐞 𝐒𝐞𝐭𝐮𝐩 𝐀𝐜𝐭𝐮𝐚𝐥𝐥𝐲 𝐖𝐨𝐫𝐤𝐬: 𝐓𝐞𝐬𝐭𝐢𝐧𝐠 𝐁𝐞𝐲𝐨𝐧𝐝 𝐭𝐡𝐞 𝐒𝐤𝐢𝐥𝐥 𝐋𝐞𝐯𝐞𝐥 You've got skill evals passing. Your hooks run. Your Claude Code executes. And then it silently degrades - you feel the inconsistency but can't pinpoint where it broke. Between March and April 2026, Claude Code shipped a regression that skill evals could not catch. Three product-layer changes stacked - reasoning downgrade, caching bug, verbosity cap - and dropped output quality for six weeks. Teams with no system-level tests felt vague inconsistency. Teams with workflow-level evals caught it immediately: pass rates dropped from 87% to 61% in three days, before anyone shipped broken code. Skill evals tell you if a single skill produces the right output in isolation. They do not tell you if your complete Claude Code setup - CLAUDE.md + skills + hooks + subagents + model version - produces consistently good code across the workflows that matter. That requires a different test. The gap: Three failure modes skill evals miss. Cross-layer interaction failures where each component passes individually but the combination breaks. Model update regressions where the new Claude version interprets your prompts differently. Configuration drift where five engineers have modified CLAUDE.md and hooks, and nobody ran a full test since setup. This article builds the testing layer for your complete Claude Code system. What to test, how to write tests that work for agent behavior, how to run them automatically, how to interpret degradation signals before it reaches production. Read the full guide for the testing pyramid - hook tests, skill evals, workflow evals - with concrete examples for each layer and the tooling to make them run on schedule. ranjankumar.in/claude-code-te… Follow me for the next installment in the Claude Code engineering playbook. #ClaudeCode #AIEngineering #AgenticAI #LLMProduction #Testing #WorkflowEvals #MLOps

𝐓𝐡𝐞 𝐑𝐚𝐥𝐩𝐡 𝐋𝐨𝐨𝐩 𝐚𝐧𝐝 /𝐠𝐨𝐚𝐥: 𝐖𝐡𝐚𝐭 𝐂𝐥𝐚𝐮𝐝𝐞 𝐂𝐨𝐝𝐞 𝐀𝐜𝐭𝐮𝐚𝐥𝐥𝐲 𝐀𝐮𝐭𝐨𝐦𝐚𝐭𝐞𝐝 Claude Code shipped /goal and made the overnight-coding trick a native feature. But it productized only one piece of Ralph - and dropped the one ingredient that actually prevents context rot on long runs. Point an autonomous coding agent at "make the tests pass" with write access, and a capable model will eventually discover that deleting the tests is faster. That is not theory - it is documented in reward-hacking benchmarks with frontier models. The Ralph loop solves this by externalizing state to disk, disposing of context with every fresh iteration, and checking completion with something the agent cannot talk its way past - a test suite, an exit code, a real signal. /goal and the official plugins shipped the completion oracle. They kept one long-running session, made state externalization optional, and dropped context disposal entirely. What you get is convenient - a native "run until a condition holds" loop - but it reintroduces the exact failure Ralph escaped: context that accumulates, compacts, and rots over hours. The session persists. The judge reads transcripts instead of running checks. On short, bounded goals, it is a win. On the long, unbounded walks you actually use Ralph for, it is a regression on the axis that made the technique work. Every vendor shipped the ingredient that demos in thirty seconds. None shipped context disposal - the one that load-bearing once the run gets long. So you are not choosing an agent. You are choosing which ingredients you get, and whether you noticed which one is missing. Read the full analysis here to understand what /goal actually automates and what it leaves you to rebuild: ranjankumar.in/ralph-loop-cla… Follow for more practitioner-focused takes on agentic systems, harness engineering, and where the demos diverge from production reality. #AutonomousAgents #ClaudeCode #AIEngineering #CodinAgents #ContextEngineering #AgenticAI #LLMSystems

𝐁𝐌𝐀𝐃 𝐯𝐬 𝐒𝐩𝐞𝐜 𝐊𝐢𝐭 𝐯𝐬 𝐊𝐢𝐫𝐨 𝐯𝐬 𝐒𝐮𝐩𝐞𝐫𝐩𝐨𝐰𝐞𝐫𝐬: 𝐖𝐡𝐚𝐭 𝐀𝐜𝐭𝐮𝐚𝐥𝐥𝐲 𝐓𝐫𝐚𝐧𝐬𝐟𝐞𝐫𝐬 Four spec-driven development frameworks with nothing in common on paper - two from the Scrum branch, one from Extreme Programming, one from AWS - converge on the same four structural mechanics. And they don't advertise why. Most of what these frameworks sell you is ritual. The core - externalizing state to files, passing exact file paths instead of pointers, resetting context between steps, dispatching fresh subagents with no memory of prior conversation - transfers without the framework, installer, or vocabulary. Why? Because none of them invented it. An LLM's context window is not memory. That constraint forces the shape. The convergence isn't a coincidence of good taste. It's a forced consequence of the medium. I compared BMAD, GitHub's Spec Kit, Amazon's Kiro, and Superpowers by reading their full implementations. Different lineages, different vendors, different philosophies on PRDs and approval gates. Same four mechanics underneath. One productive disagreement on the fifth. Everything else is packaging. 𝐓𝐡𝐞 𝐫𝐞𝐚𝐥 𝐪𝐮𝐞𝐬𝐭𝐢𝐨𝐧: if frontier context windows grow large enough that externalizing state stops paying for itself, does this argument weaken? Yes. That's a falsifiability condition, not a hypothetical. A team that mistook ceremony for discipline abandoned a framework, burned two days on review gates built for six-month projects, and went back to unstructured prompting. They didn't lose spec-driven development. They lost the four mechanics tangled inside it. Knowing which four mechanics matter and which are ritual is the difference between frameworks that stick and frameworks you discard. Read the full analysis: ranjankumar.in/spec-driven-de… Follow for more practitioner takes on AI systems architecture. #SpecDrivenDevelopment #AIEngineering #AgenticAI #ContextEngineering #DeveloperTools #MLOps #AIArchitecture

𝐖𝐡𝐢𝐜𝐡 𝐂𝐥𝐚𝐮𝐝𝐞 𝐂𝐨𝐝𝐞 𝐋𝐚𝐲𝐞𝐫 𝐒𝐨𝐥𝐯𝐞𝐬 𝐘𝐨𝐮𝐫 𝐏𝐫𝐨𝐛𝐥𝐞𝐦? 𝐀 𝐃𝐢𝐚𝐠𝐧𝐨𝐬𝐭𝐢𝐜 𝐆𝐮𝐢𝐝𝐞 𝐟𝐨𝐫 𝐀𝐈 𝐄𝐧𝐠𝐢𝐧𝐞𝐞𝐫𝐬 You add a subagent to fix Claude's tool choices. Now you have a subagent managing which code tool to use, and Claude still defaults wrong half the time because the subagent only fires when invoked, not on every session. You needed one line in CLAUDE.md. 𝑇ℎ𝑖𝑠 𝑖𝑠 𝑡ℎ𝑒 𝑐𝑜𝑟𝑒 𝑓𝑎𝑖𝑙𝑢𝑟𝑒 𝑚𝑜𝑑𝑒: reaching for the wrong layer. Claude Code has five extensibility mechanisms - CLAUDE.md, MCP servers, Skills, Subagents, and Hooks. Each solves a categorically different problem. Using the wrong one doesn't fail gracefully. It adds complexity, consumes context, and creates maintenance burden for a configuration that shouldn't exist. The diagnostic principle is simple: layer selection is not a capability problem - it's a diagnosis problem. - 𝐂𝐋𝐀𝐔𝐃𝐄.𝐦𝐝 - static facts the agent must always know - 𝐌𝐂𝐏 - live access to external systems - 𝐒𝐤𝐢𝐥𝐥𝐬 - procedural expertise for matching tasks - 𝐒𝐮𝐛𝐚𝐠𝐞𝐧𝐭𝐬 - context isolation for heavy work - 𝐇𝐨𝐨𝐤𝐬 - deterministic enforcement rules that can't be probabilistic Miss the diagnosis, and no amount of configuration quality fixes the mismatch. The article walks through precise layer definitions, a diagnostic table that maps symptoms to solutions, and five real scenarios showing wrong reaches vs correct diagnosis. The pattern-matching instinct matters more than memorizing rules. 𝐑𝐞𝐚𝐝 𝐭𝐡𝐞 𝐟𝐮𝐥𝐥 𝐠𝐮𝐢𝐝𝐞: ranjankumar.in/claude-code-la… 𝐹𝑜𝑙𝑙𝑜𝑤 𝑓𝑜𝑟 𝑚𝑜𝑟𝑒 𝑝𝑟𝑎𝑐𝑡𝑖𝑡𝑖𝑜𝑛𝑒𝑟-𝑓𝑜𝑐𝑢𝑠𝑒𝑑 𝐴𝐼 𝑒𝑛𝑔𝑖𝑛𝑒𝑒𝑟𝑖𝑛𝑔 𝑖𝑛𝑠𝑖𝑔ℎ𝑡𝑠. #ClaudeCode #AIEngineering #LLMProduction #AgentArchitecture #ContextEngineering #SystemDesign #MLOps

𝑻𝒉𝒆 𝑪𝒍𝒂𝒖𝒅𝒆 𝑪𝒐𝒅𝒆 𝑬𝒏𝒈𝒊𝒏𝒆𝒆𝒓𝒊𝒏𝒈 𝑷𝒍𝒂𝒚𝒃𝒐𝒐𝒌: 𝑷𝒂𝒓𝒕 10 𝐂𝐡𝐞𝐜𝐤𝐩𝐨𝐢𝐧𝐭 𝐂𝐨𝐦𝐩𝐥𝐚𝐜𝐞𝐧𝐜𝐲: 𝐂𝐥𝐚𝐮𝐝𝐞 𝐂𝐨𝐝𝐞 /𝐫𝐞𝐰𝐢𝐧𝐝 𝐯𝐬 𝐆𝐢𝐭 𝐂𝐨𝐦𝐦𝐢𝐭𝐬 Checkpointing feels like git. It covers a fraction of what git covers - and that gap is exactly where real work gets lost. Claude Code's /rewind snapshots code and conversation inside a session. Git commits protect everything - Bash side effects, manual edits, concurrent work, retention windows, and the actual history you need for production. They're not two versions of the same safety net. They're two tiers guarding different failure classes. The moment you treat one as a substitute for the other, you're carrying a blind spot you won't see until you fall into it. Here's the exact boundary. Checkpointing tracks file edits made through Claude's own tools - perfect for backing out a bad refactor mid-session. It does not track anything Bash touches. rm, mv, sed, installs, migrations, database writes - invisible to /rewind. You can undo Claude's thinking. You cannot undo rm -rf build/ followed by an overwrite to a hand-edited config file, because that command ran through the Bash tool, and Bash is the documented blind spot. You look for /rewind. Nothing happens. The file is gone. This isn't theoretical. As sessions get more autonomous, Bash touches more of your workflow - test runners, builds, installs, migrations. The proportion of session activity that checkpointing can actually see goes down. Parallel sessions multiply the problem: separate Claude Code windows against git worktrees are sharing one .git directory, and a destructive Bash command in worktree A can break worktree B's state. Neither session's checkpoint history sees the other. The fix is not a better checkpoint. It's enforcement at the boundary where checkpoint visibility ends. Commit before handing off to autonomous Bash. The pattern is simple: human reviews the code changes, runs git add, and pushes. Claude resumes in a clean working tree. Now a destructive Bash command has something to fall back to - actual version control, not session history. Now parallel sessions each have a stable baseline. Now production has an audit trail that doesn't expire when a session gets pruned. This is the hook that turns checkpoint convenience into safe autonomy. Read the full breakdown of the checkpoint-git boundary, why teams slip into this trap, and the enforce-at-commit pattern that closes the gap: ranjankumar.in/claude-code-ch… Follow Ranjan Kumar for more practitioner-focused AI engineering insights on Claude Code and agentic systems. #ClaudeCode #AIEngineering #GitWorkflow #ReliabilityEngineering #AgenticAI #DeveloperTools #VersionControl

𝐒𝐩𝐞𝐜-𝐃𝐫𝐢𝐯𝐞𝐧 𝐃𝐞𝐯𝐞𝐥𝐨𝐩𝐦𝐞𝐧𝐭: 𝐂𝐨𝐮𝐩𝐥𝐢𝐧𝐠 𝐁𝐞𝐚𝐭𝐬 𝐖𝐫𝐢𝐭𝐢𝐧𝐠 You can write the cleanest spec in the world. If nothing enforces it, the agent will ignore it the moment the spec runs out of detail. The Replit incident - an AI agent deleted a live production database despite a written code freeze instruction - isn't a story about a bad model. It's a story about what happens when the only constraint is a sentence typed into a chat box an hour ago. The spec died the moment the conversation ended. Nothing checked it. Nothing failed when the code drifted. This is where spec-driven development should help. And it does - but only if the spec is coupled to something that actually enforces it. Most teams get this half right. They write clean prose specs. They hand them to agents. They feel productive. Then they ship uncoupled markdown files that look authoritative but have no teeth. A missing unit test gets flagged in code review. A spec with no contract test behind it doesn't - because most teams haven't made enforcement a visible ritual yet. Here's what actually survives model swaps and team rotations: specs with automated contract tests. Tests that fail if the code drifts from the spec. Tests that block the merge. Tests that make the spec irrevocable, not just documented. The fix is procedural, not cultural. Add spec-contract validation to what reviewers look for. Make it a checked-for ritual, the way test coverage became one. Specs without enforcement are design docs 2.0 - they rot the same way. Read the full breakdown on practical tradeoffs between prose specs and enforced ones: ranjankumar.in/spec-driven-de… Follow for more on what actually works in AI engineering practice. #SpecDrivenDevelopment #AIEngineering #AIAgents #CodingAgents #VibeCodeIsDeadCode #MLOps #SoftwareEngineering

𝐂𝐨𝐦𝐩𝐥𝐢𝐚𝐧𝐜𝐞, 𝐀𝐮𝐝𝐢𝐭 𝐓𝐫𝐚𝐢𝐥𝐬, 𝐚𝐧𝐝 𝐑𝐞𝐠𝐮𝐥𝐚𝐭𝐨𝐫𝐲 𝐑𝐞𝐪𝐮𝐢𝐫𝐞𝐦𝐞𝐧𝐭𝐬 𝐟𝐨𝐫 𝐀𝐠𝐞𝐧𝐭𝐢𝐜 𝐒𝐲𝐬𝐭𝐞𝐦𝐬 The EU AI Act's full enforcement is near. If your agents touch credit decisions, employment screening, or regulatory reporting, you're in scope. The gap between running agents and running auditable agents is not a documentation problem - it's architectural. Most teams have logs. Regulators need audit trails. These are not the same thing. Logs are mutable, unstructured, and missing the fields regulators need - model version, policy version, integrity hash, reviewer identity, intervention points. An audit trail is immutable, correlated across agents, attributed to specific versions, and queryable on demand. A standard logging system satisfies none of Articles 9, 12, 13, 14, or 15 of the EU AI Act. The technical obligations are concrete. Article 12 demands record-keeping with sufficient detail to reconstruct decision paths. Article 13 requires transparency - tracing every output back to its inputs and model version. Article 14 requires structured human oversight points, not theoretical ones. Article 9 demands active, ongoing risk assessment. Teams that built agents without these properties now face structural rework. The fix is not adding audit fields to log messages. It's an architectural shift - an immutable audit trail integrated with your agent registry, policy gates, and human oversight interrupts. Each record must capture inputs, outputs, tool calls, policy decisions, and human interventions. Every field must be queryable. Nothing can be modified after creation. This is what separates compliance theatre from actual auditability. 𝐑𝐞𝐚𝐝 𝐭𝐡𝐞 𝐟𝐮𝐥𝐥 𝐠𝐮𝐢𝐝𝐞: ranjankumar.in/ai-control-pla… 𝐹𝑜𝑙𝑙𝑜𝑤 𝑓𝑜𝑟 𝑚𝑜𝑟𝑒 𝑜𝑛 𝑏𝑢𝑖𝑙𝑑𝑖𝑛𝑔 𝑝𝑟𝑜𝑑𝑢𝑐𝑡𝑖𝑜𝑛 𝑎𝑔𝑒𝑛𝑡𝑖𝑐 𝑠𝑦𝑠𝑡𝑒𝑚𝑠 𝑡ℎ𝑎𝑡 𝑠𝑐𝑎𝑙𝑒 𝑤𝑖𝑡ℎ𝑜𝑢𝑡 𝑏𝑟𝑒𝑎𝑘𝑖𝑛𝑔. #AICompliance #AuditTrail #EUAIAct #AgenticAI #MLOps #Regulatory #ControlPlane

𝐅𝐚𝐮𝐥𝐭 𝐈𝐬𝐨𝐥𝐚𝐭𝐢𝐨𝐧 𝐚𝐧𝐝 𝐂𝐢𝐫𝐜𝐮𝐢𝐭 𝐁𝐫𝐞𝐚𝐤𝐢𝐧𝐠: 𝐒𝐭𝐨𝐩 𝐑𝐞𝐭𝐫𝐲𝐢𝐧𝐠 𝐋𝐋𝐌 𝐂𝐚𝐥𝐥𝐬 𝐋𝐢𝐤𝐞 𝐌𝐢𝐜𝐫𝐨𝐬𝐞𝐫𝐯𝐢𝐜𝐞𝐬 You're applying exponential backoff and circuit breakers to LLM calls exactly as written in the distributed systems playbook. It works great for stateless RPCs. It turns a three-minute provider blip into a thirty-two-minute outage when the failure model is wrong. The microservice resilience pattern assumes failures are transient, independent across clients, cheap to retry, and hitting idempotent operations. LLM calls violate all four. A 429 or 529 is correlated across your entire fleet. A retry costs real money and seconds of wall-clock time, not milliseconds. A retried generation that already streamed three thousand tokens re-bills the whole thing. When you wrap exponential backoff around an SDK that already retries twice, a single logical call becomes a dozen real ones - and when the provider recovers, your synchronized retry wave re-saturates it instantly, sustaining the outage long after the provider is healthy. This gets worse in agent DAGs. When an orchestrator dispatches eight specialist agents and all hit the provider's rate limit at once, eight independent retry loops now hammer the same recovering endpoint in lockstep. One agent stuck in a six-attempt backoff loop with 32-second waits holds the entire pipeline hostage while the other seven wait. The Bronson et al. metastable failures study found retry-induced load amplification was the sustaining effect in more than half of real-world incidents they analyzed. The fix is not better tuning. It is classification. Rate-limit errors (429, 529) need fast fail and backpressure signaling to the orchestrator. Terminal errors (400, safety refusals, context length) need to fail once and stop. Transient network errors need bounded, jittered retries with explicit retry-after header respect. One retry policy for everything guarantees you'll handle most failures wrong. Read the full breakdown - where the pattern breaks, why DAG pipelines amplify the damage, and the specific code patterns that don't leak tokens into the void: ranjankumar.in/fault-isolatio… Follow for more on building production AI systems that don't crater under load. #AIEngineering #AgenticAI #CircuitBreaker #ResilienceEngineering #LLMReliability #SystemsDesign #ProductionAI

𝐒𝐤𝐢𝐥𝐥𝐬 𝐯𝐬 𝐇𝐨𝐨𝐤𝐬 𝐢𝐧 𝐂𝐥𝐚𝐮𝐝𝐞 𝐂𝐨𝐝𝐞: 𝐄𝐧𝐟𝐨𝐫𝐜𝐞𝐚𝐛𝐢𝐥𝐢𝐭𝐲 𝐈𝐬 𝐭𝐡𝐞 𝐃𝐞𝐬𝐢𝐠𝐧 𝐕𝐚𝐫𝐢𝐚𝐛𝐥𝐞 (𝑷𝒂𝒓𝒕 9 𝒐𝒇 𝑻𝒉𝒆 𝑪𝒍𝒂𝒖𝒅𝒆 𝑪𝒐𝒅𝒆 𝑬𝒏𝒈𝒊𝒏𝒆𝒆𝒓𝒊𝒏𝒈 𝑷𝒍𝒂𝒚𝒃𝒐𝒐𝒌) 𝐴 𝑠𝑘𝑖𝑙𝑙 𝑖𝑠 𝑎 𝑠𝑢𝑔𝑔𝑒𝑠𝑡𝑖𝑜𝑛 𝑡ℎ𝑒 𝑚𝑜𝑑𝑒𝑙 𝑚𝑎𝑦 𝑓𝑜𝑙𝑙𝑜𝑤. 𝐴 ℎ𝑜𝑜𝑘 𝑖𝑠 𝑎 𝑔𝑎𝑡𝑒 𝑖𝑡 𝑐𝑎𝑛𝑛𝑜𝑡 𝑠𝑒𝑒 𝑎𝑛𝑑 𝑐𝑎𝑛𝑛𝑜𝑡 𝑎𝑟𝑔𝑢𝑒 𝑤𝑖𝑡ℎ. 𝑀𝑜𝑠𝑡 𝑝𝑟𝑜𝑑𝑢𝑐𝑡𝑖𝑜𝑛 𝑎𝑔𝑒𝑛𝑡 𝑓𝑎𝑖𝑙𝑢𝑟𝑒𝑠 𝑐𝑜𝑚𝑒 𝑓𝑟𝑜𝑚 𝑐𝑜𝑛𝑓𝑢𝑠𝑖𝑛𝑔 𝑡ℎ𝑒 𝑡𝑤𝑜. A skill is a suggestion your agent may follow. A hook is a gate it cannot see and cannot argue with. Most "𝑠𝑘𝑖𝑙𝑙𝑠 𝑎𝑟𝑒 𝑢𝑛𝑟𝑒𝑙𝑖𝑎𝑏𝑙𝑒" complaints are category errors - a skill deployed where the job needed a gate. The design variable nobody names is enforceability: 𝑎𝑑𝑣𝑖𝑠𝑜𝑟𝑦 or 𝑒𝑛𝑓𝑜𝑟𝑐𝑒𝑑. A working PreToolUse scope gate, the Write Funnel pattern, and a decision test that fits on an index card. Read the detailed article: ranjankumar.in/claude-code-en… Follow for production agent engineering. #ClaudeCode #AIEngineering #AgenticAI #LLMOps #AIAgents #PlatformEngineering #DevTools

𝐄𝐩𝐢𝐬𝐭𝐞𝐦𝐢𝐜 𝐑𝐞𝐬𝐭𝐫𝐚𝐢𝐧𝐭 𝐛𝐲 𝐃𝐞𝐬𝐢𝐠𝐧: 𝐁𝐨𝐮𝐧𝐝𝐚𝐫𝐲-𝐀𝐰𝐚𝐫𝐞 𝐀𝐈 𝐒𝐲𝐬𝐭𝐞𝐦𝐬 (𝐏𝐨𝐬𝐭 + 𝐏𝐚𝐩𝐞𝐫) You cannot train your way out of hallucination at platform scale. The missing layer is an explicit support boundary, not a bigger model. A deployed assistant confidently tells a user that a drug interaction is safe when it is not. A multi-agent pipeline summarizes a contract clause that does not exist. A coding agent cites an API method that was never shipped. None of these is exotic - they are expected behavior from a system optimized to produce fluent text under uncertainty, wired into a pipeline with no representation of what it is allowed to assert. The field treats hallucination as a model problem: reach for a bigger checkpoint, more retrieval, stricter prompts. Those help. They miss where production damage actually originates. At platform scale, hallucination is not only a model failure - it is an architecture failure. The missing layer is an explicit, auditable support boundary. A more accurate model still presents weakly supported content in the same confident register as a grounded fact. Without system-level controls, you have no way to know which claims were ground and which were invented three hops back. RAG is widely treated as the hallucination fix. But it improves accuracy on in-scope answers while doing almost nothing to stop out-of-scope ones. Retrieval that returns five irrelevant chunks and retrieval that nails it produce identical outputs - because there is no gate that can say "not this one." RAG raises the ceiling on what you should answer. It does not install a floor under what you should not. The fix separates what systems usually conflate: the model's parametric knowledge boundary and the deployment's support boundary. Encode the boundary before you generate. Implement a Knowledge Gating Layer that sits in front of generation - a policy-aware predicate that decides whether a request is in-boundary, out-of-boundary, or unresolved. The single most critical rule: never treat unresolved as permission to answer. At hundreds of millions of users, a residual fraction-of-a-percent hallucination rate becomes hundreds of thousands of ungrounded outputs per day. The real trade is between coverage and trust. Most pipelines make it implicitly and by accident. Epistemic Restraint by Design makes it explicit and tunable. Read the full article: ranjankumar.in/epistemic-rest… Follow for more practitioner-focused AI engineering insights. #EpistemicRestraint #AIEngineering #LLMSafety #RAG #AgenticAI #AIArchitecture #PractitionerAI

𝐖𝐡𝐲 𝐘𝐨𝐮𝐫 𝐀𝐈 𝐀𝐠𝐞𝐧𝐭 𝐅𝐢𝐧𝐢𝐬𝐡𝐞𝐬 𝐓𝐚𝐬𝐤𝐬 𝐁𝐮𝐭 𝐅𝐚𝐢𝐥𝐬 𝐭𝐡𝐞 𝐆𝐨𝐚𝐥 Your agent completes every task. The execution log is clean. But the outcome is wrong. This happens when you treat the task list as static config - defined upfront, never revised, regardless of what the agent actually discovers mid-execution. The plan becomes the goal, and mid-course signals get ignored because they weren't on the original list. The real decision you never consciously made: Does the next task depend only on whether the previous one completed, or on what it actually found? That distinction maps to three patterns. Execution Contract (fixed plan, deterministic). Discovery Hypothesis (evolving plan, learning-driven). Hybrid Boundary (designed handoff between them). Most teams default to the first because it's simple. It works fine until the problem requires adaptive reasoning - then it fails silently. A task list isn't just a workflow artifact. It's how you externalize the reasoning structure that lives inside an LLM's ephemeral forward pass into persistent, inspectable state. Get this wrong and your agent optimizes for task completion, not goal achievement. Read the full breakdown on the tradeoffs and how to choose the right pattern for your system: ranjankumar.in/why-your-ai-ag… Follow for more practitioner-focused insights on building agents that actually work. #AIAgents #LLMEngineering #MultiStepReasoning #ProductionAI #AgentArchitecture #SystemDesign

𝟓 𝐏𝐫𝐢𝐧𝐜𝐢𝐩𝐥𝐞𝐬 𝐟𝐨𝐫 𝐁𝐮𝐢𝐥𝐝𝐢𝐧𝐠 𝐏𝐫𝐨𝐝𝐮𝐜𝐭𝐢𝐨𝐧-𝐆𝐫𝐚𝐝𝐞 𝐀𝐠𝐞𝐧𝐭𝐢𝐜 𝐀𝐈 𝐒𝐲𝐬𝐭𝐞𝐦𝐬 Your agent demo looks flawless. Smooth tool calls. Correct outputs. Clean reasoning traces. Then it hits production. Three weeks later: silent failures on edge cases. Timeouts cascade. State corrupts between runs. A tool call errors at step 4 of 6, and the agent hallucinates the rest. Downstream systems ingest corrupted data before anyone notices. This isn't hypothetical. Replit's AI assistant deleted a production database despite explicit safeguards. IBM's customer service agent started approving refunds outside policy after reading positive feedback. MIT found only 5% of enterprise GenAI systems actually reach production. Gartner predicts 40% of agentic projects will be cancelled by 2027. The problem isn't model quality. It's systems architecture. Most teams design an agent, not a system. They optimize for the happy path and ship a sophisticated demo wearing production clothes. The gap between demo and production isn't about tuning parameters-it's about five foundational architectural dimensions that separate resilient systems from fragile prototypes. After building production agent systems with LangGraph across support, document processing, and data pipelines, the same five gaps appear consistently. Get these right and you have a system. Miss one and you'll learn about the failure in production. Read the full breakdown: ranjankumar.in/5-principles-f… Follow for more practical AI systems engineering. #AgenticAI #LLMSystems #AIArchitecture #ProductionAI #SystemsDesign #AIEngineering

𝐖𝐡𝐢𝐜𝐡 𝐂𝐥𝐚𝐮𝐝𝐞 𝐂𝐨𝐝𝐞 𝐋𝐚𝐲𝐞𝐫 𝐒𝐨𝐥𝐯𝐞𝐬 𝐘𝐨𝐮𝐫 𝐏𝐫𝐨𝐛𝐥𝐞𝐦? 𝐀 𝐃𝐢𝐚𝐠𝐧𝐨𝐬𝐭𝐢𝐜 𝐆𝐮𝐢𝐝𝐞 𝐟𝐨𝐫 𝐀𝐈 𝐄𝐧𝐠𝐢𝐧𝐞𝐞𝐫𝐬 You add a subagent to fix Claude's tool choices. Now you have a subagent managing which code tool to use, and Claude still defaults wrong half the time because the subagent only fires when invoked, not on every session. You needed one line in CLAUDE.md. 𝑇ℎ𝑖𝑠 𝑖𝑠 𝑡ℎ𝑒 𝑐𝑜𝑟𝑒 𝑓𝑎𝑖𝑙𝑢𝑟𝑒 𝑚𝑜𝑑𝑒: reaching for the wrong layer. Claude Code has five extensibility mechanisms - CLAUDE.md, MCP servers, Skills, Subagents, and Hooks. Each solves a categorically different problem. Using the wrong one doesn't fail gracefully. It adds complexity, consumes context, and creates maintenance burden for a configuration that shouldn't exist. The diagnostic principle is simple: layer selection is not a capability problem - it's a diagnosis problem. - 𝐂𝐋𝐀𝐔𝐃𝐄.𝐦𝐝 - static facts the agent must always know - 𝐌𝐂𝐏 - live access to external systems - 𝐒𝐤𝐢𝐥𝐥𝐬 - procedural expertise for matching tasks - 𝐒𝐮𝐛𝐚𝐠𝐞𝐧𝐭𝐬 - context isolation for heavy work - 𝐇𝐨𝐨𝐤𝐬 - deterministic enforcement rules that can't be probabilistic Miss the diagnosis, and no amount of configuration quality fixes the mismatch. The article walks through precise layer definitions, a diagnostic table that maps symptoms to solutions, and five real scenarios showing wrong reaches vs correct diagnosis. The pattern-matching instinct matters more than memorizing rules. 𝐑𝐞𝐚𝐝 𝐭𝐡𝐞 𝐟𝐮𝐥𝐥 𝐠𝐮𝐢𝐝𝐞: ranjankumar.in/claude-code-la… 𝐹𝑜𝑙𝑙𝑜𝑤 𝑓𝑜𝑟 𝑚𝑜𝑟𝑒 𝑝𝑟𝑎𝑐𝑡𝑖𝑡𝑖𝑜𝑛𝑒𝑟-𝑓𝑜𝑐𝑢𝑠𝑒𝑑 𝐴𝐼 𝑒𝑛𝑔𝑖𝑛𝑒𝑒𝑟𝑖𝑛𝑔 𝑖𝑛𝑠𝑖𝑔ℎ𝑡𝑠. #ClaudeCode #AIEngineering #LLMProduction #AgentArchitecture #ContextEngineering #SystemDesign #MLOps

𝐅𝐨𝐮𝐫 𝐇𝐚𝐛𝐢𝐭𝐬 𝐟𝐫𝐨𝐦 𝐭𝐡𝐞 𝐂𝐫𝐞𝐚𝐭𝐨𝐫 𝐨𝐟 𝐂𝐥𝐚𝐮𝐝𝐞 𝐂𝐨𝐝𝐞 𝐓𝐡𝐚𝐭 𝐖𝐢𝐥𝐥 𝐂𝐡𝐚𝐧𝐠𝐞 𝐇𝐨𝐰 𝐘𝐨𝐮 𝐒𝐡𝐢𝐩 Most developers using Claude Code treat it like a pair programmer. Boris Cherny treats it like an engineer you delegate to. That difference in operating model is why he ships 20-30 PRs a day while running 10-15 parallel sessions. It is not the configuration. It is the four habits. His first PR at Anthropic got rejected for being hand-written. At the world's leading AI lab, surrounded by engineers who expected code from AI, he had typed it himself. That moment catalyzed a complete rethinking of how to work with an AI coding agent at scale. The four habits are simple. Treat context like a resource you manage, not a recording of everything. Brief Claude the way you brief an engineer - clear goal, constraints, success criteria. Run five worktrees in parallel. Automate the repetitive parts. Each habit addresses a specific failure mode. Together they form a complete operating model. ranjankumar.in/boris-cherny-f… Read the full breakdown and start shipping faster this week. 𝐹𝑜𝑙𝑙𝑜𝑤 𝑓𝑜𝑟 𝑚𝑜𝑟𝑒 𝑝𝑟𝑎𝑐𝑡𝑖𝑡𝑖𝑜𝑛𝑒𝑟-𝑓𝑜𝑐𝑢𝑠𝑒𝑑 𝐴𝐼 𝑒𝑛𝑔𝑖𝑛𝑒𝑒𝑟𝑖𝑛𝑔 𝑝𝑎𝑡𝑡𝑒𝑟𝑛𝑠. #ClaudeCode #AIEngineering #ProductivityHacks #DeveloperWorkflow #Automation #AgenticAI #CodingPatterns

📖 𝐀𝐧𝐧𝐨𝐮𝐧𝐜𝐢𝐧𝐠 𝐦𝐲 𝐧𝐞𝐰 𝐛𝐨𝐨𝐤: 𝐓𝐡𝐞 𝐂𝐡𝐚𝐭 𝐓𝐞𝐦𝐩𝐥𝐚𝐭𝐞𝐬 𝐇𝐚𝐧𝐝𝐛𝐨𝐨𝐤 Your model passes every benchmark. Then it quietly gets worse in production — and your logs show nothing. Nine times out of ten, the culprit is the same invisible layer: the chat template. The code that turns your message list into the exact tokens the model was trained on. Get it wrong, and the model doesn't error - it just answers worse, with nothing to chase. I wrote this book because that layer has quietly become the most overlooked part of every LLM stack. Every instruct model on Hugging Face ships a Jinja chat template. apply_chat_template() sits underneath LangChain, vLLM, SGLang, llama.cpp, Ollama — all of it. And as models picked up tool-calling, reasoning, and vision, that template grew from ten lines into a hundred-line program that breaks in new ways, and renders differently across engines. This book is for AI/backend engineers shipping LLM features, ML engineers who fine-tuned a model and now own its template, and platform teams serving open models across multiple engines. 𝐈𝐧𝐬𝐢𝐝𝐞: reading and writing Jinja templates correctly, handling tool-calling/reasoning/multimodal templates, debugging drift with golden-token tests in CI, fixing cross-engine differences, and defending against a real, documented template-injection attack surface. Every chapter ships runnable code from Template Studio, the open-source toolkit built alongside the book. 🔗 amazon.com/dp/B0H6STBYWT #LLM #MachineLearning #AIEngineering #MLOps

📗 𝐓𝐡𝐞 𝐂𝐡𝐚𝐭𝐌𝐋 𝐇𝐚𝐧𝐝𝐛𝐨𝐨𝐤 — 𝐒𝐞𝐜𝐨𝐧𝐝 𝐄𝐝𝐢𝐭𝐢𝐨𝐧 𝐢𝐬 𝐡𝐞𝐫𝐞 A question I get a lot: "Isn't ChatML just an old GPT formatting trick?" No - and that's the core argument of my book, now in its 𝐬𝐞𝐜𝐨𝐧𝐝 𝐞𝐝𝐢𝐭𝐢𝐨𝐧. ChatML was never about special tokens. It was about a contract: 𝐬𝐲𝐬𝐭𝐞𝐦 / 𝐮𝐬𝐞𝐫 / 𝐚𝐬𝐬𝐢𝐬𝐭𝐚𝐧𝐭 / 𝐭𝐨𝐨𝐥. That role-based model won. It's the universal vocabulary every major LLM API speaks today - OpenAI, Anthropic, and the open-model ecosystem alike. It's also the layer hiding under your frameworks. LangChain, LlamaIndex, Ollama - none of them concatenate strings. They pass structured, role-tagged messages. That's ChatML's model, just unnamed. And on Hugging Face, every model ships a Jinja chat template. apply_chat_template() is just ChatML's concept rendered into a model-specific format - ChatML markers for some, [INST] or start_of_turn tags for others. 𝐋𝐞𝐚𝐫𝐧 𝐭𝐡𝐞 𝐬𝐭𝐫𝐮𝐜𝐭𝐮𝐫𝐞 𝐨𝐧𝐜𝐞. 𝐓𝐚𝐫𝐠𝐞𝐭 𝐚𝐧𝐲 𝐦𝐨𝐝𝐞𝐥, 𝐚𝐧𝐲 𝐟𝐫𝐚𝐦𝐞𝐰𝐨𝐫𝐤, 𝐚𝐧𝐲 𝐲𝐞𝐚𝐫. 𝐖𝐡𝐚𝐭'𝐬 𝐧𝐞𝐰 𝐢𝐧 𝐭𝐡𝐢𝐬 𝐞𝐝𝐢𝐭𝐢𝐨𝐧: → An expanded, end-to-end Support Bot project (Part III) - built on FastAPI + Ollama (Qwen 1.5) → New chapters on tool execution and memory persistence → Clarified mapping between ChatML and Jinja chat templates across providers and open models → A unified reference appendix and improved template-rendering examples This isn't another "prompting tips" book. It's a framework for treating conversations as software interfaces - between human intent and machine reasoning - covering structured pipelines, versioned Jinja2 templates (no more fragile string concat), and memory-aware, tool-augmented, multi-agent chat design. Built for AI engineers shipping production conversational systems, researchers working on orchestration, and platform teams wiring LLMs into real products. 📖 Get the Kindle / Paperback edition: amazon.com/dp/B0G2GM44FD If you read it, I'd genuinely appreciate a review - it helps the book reach more engineers wrestling with the same "my prompts work until they don't" problem. #AIEngineering #LLM #ChatML #AgenticAI #PromptEngineering

𝐂𝐥𝐚𝐮𝐝𝐞 𝐂𝐨𝐝𝐞 𝐎𝐛𝐬𝐞𝐫𝐯𝐚𝐛𝐢𝐥𝐢𝐭𝐲: 𝐖𝐡𝐞𝐧 𝐘𝐨𝐮𝐫 𝐀𝐈 𝐀𝐠𝐞𝐧𝐭 𝐆𝐨𝐞𝐬 𝐒𝐢𝐥𝐞𝐧𝐭 ̲(̲𝐏̲𝐚̲𝐫̲𝐭̲ ̲𝟕̲ ̲𝐨̲𝐟̲ ̲𝐒̲𝐞̲𝐫̲𝐢̲𝐞̲𝐬̲ ̲𝐓̲𝐡̲𝐞̲ ̲𝐂̲𝐥̲𝐚̲𝐮̲𝐝̲𝐞̲ ̲𝐂̲𝐨̲𝐝̲𝐞̲ ̲𝐄̲𝐧̲𝐠̲𝐢̲𝐧̲𝐞̲𝐞̲𝐫̲𝐢̲𝐧̲𝐠̲ ̲𝐏̲𝐥̲𝐚̲𝐲̲𝐛̲𝐨̲𝐨̲𝐤̲ ̲)̲ You've deployed an agentic system using Claude, it's working in dev, and then production hits you with cryptic errors and silent failures. You can't see what Claude is thinking, what it's doing mid-task, or where it actually broke. You're flying blind. This isn't a Claude problem - it's an observability problem. Most teams treat AI agents like black boxes, logging inputs and outputs. That leaves huge gaps. Here's what actually matters: - Token usage patterns reveal inefficiency and cost bleed before they spiral - Intermediate reasoning steps show you where the model actually went wrong - not just that it failed - Tool call chains expose logic errors that look like model hallucinations but aren't - Latency breakdowns tell you if delays are API calls, tool execution, or token processing 𝐓𝐡𝐞 𝐫𝐞𝐚𝐥 𝐜𝐡𝐚𝐥𝐥𝐞𝐧𝐠𝐞: you need observability that's lightweight enough to run in production but detailed enough to debug agentic behavior at the reasoning level. Standard application monitoring wasn't built for this. 𝑅𝑒𝑎𝑑 𝑡ℎ𝑒 𝑓𝑢𝑙𝑙 𝑏𝑟𝑒𝑎𝑘𝑑𝑜𝑤𝑛 𝑜𝑛 𝑝𝑟𝑎𝑐𝑡𝑖𝑐𝑎𝑙 𝑜𝑏𝑠𝑒𝑟𝑣𝑎𝑏𝑖𝑙𝑖𝑡𝑦 𝑠𝑡𝑟𝑎𝑡𝑒𝑔𝑖𝑒𝑠 𝑓𝑜𝑟 𝐶𝑙𝑎𝑢𝑑𝑒-𝑏𝑎𝑠𝑒𝑑 𝑠𝑦𝑠𝑡𝑒𝑚𝑠: ranjankumar.in/claude-code-ob… 𝐹𝑜𝑙𝑙𝑜𝑤 𝑓𝑜𝑟 𝑚𝑜𝑟𝑒 𝑝𝑟𝑎𝑐𝑡𝑖𝑡𝑖𝑜𝑛𝑒𝑟-𝑓𝑜𝑐𝑢𝑠𝑒𝑑 𝐴𝐼 𝑒𝑛𝑔𝑖𝑛𝑒𝑒𝑟𝑖𝑛𝑔 𝑝𝑎𝑡𝑡𝑒𝑟𝑛𝑠 𝑡ℎ𝑎𝑡 𝑎𝑐𝑡𝑢𝑎𝑙𝑙𝑦 𝑠𝑐𝑎𝑙𝑒. #AgenticAI #AIEngineering #Claude #Observability #Debugging #ProductionAI #MLOps

𝐇𝐮𝐦𝐚𝐧-𝐢𝐧-𝐭𝐡𝐞-𝐋𝐨𝐨𝐩 𝐚𝐭 𝐏𝐫𝐨𝐝𝐮𝐜𝐭𝐢𝐨𝐧 𝐒𝐜𝐚𝐥𝐞: 𝐓𝐡𝐞 𝐂𝐡𝐞𝐜𝐤𝐩𝐨𝐢𝐧𝐭 𝐌𝐞𝐦𝐛𝐫𝐚𝐧𝐞 Your approval gate works fine until it doesn't. Three weeks in, your reviewer is clicking Approve on nine of ten requests without reading them. One traffic spike later, the entire agent fleet is blocked waiting for human decisions that aren't coming fast enough. This is not a staffing problem. It is a design problem. A synchronous approval gate on every action feels like safety. In practice, it trades one risk (unsafe autonomy) for two worse ones: throughput collapse and rubber-stamping under fatigue. Anthropic measured its own users approving 93% of permission prompts. That is not oversight - that is a click tax that manufactures the appearance of judgment while delivering none of it. The fix is not more reviewers. It is to stop treating human oversight as a wall every action must climb, and start building a selectively permeable checkpoint. Route only the genuinely risky, irreversible actions to humans. Everything else gets a defined default - approve or deny based on risk scoring, confidence thresholds, and reversibility. When no human answers in time, the system does not block. It executes the safe default. Two forces break the naive gate. First: queueing math. A human reviewer has a finite service rate. Once request volume exceeds that rate, queue length grows without bound - your fleet stalls. Second: human factors. Parasuraman and Manzey showed automation complacency appears under load, afflicts experts as readily as novices, and cannot be trained away. Volume drives approval rates up, oversight down. That is not laziness. That is how attention works. The article walks you through the right architecture: risk-stratified checkpoints with defined defaults, LangGraph implementation patterns, and how to set the rubber-stamp threshold before it sets you. Read the full breakdown here and rethink what your approval gate is actually buying you. ranjankumar.in/human-in-the-l… Follow for more on agentic systems design and production AI patterns. #AIEngineering #AgenticAI #HumanInTheLoop #LangGraph #ProductionAI #SystemsDesign #ApprovalFatigue

Agent passed every staging test. Cost $4,000/day in prod 3 weeks later. They upgraded the model. Bill went up, wrong answers stayed. They strengthened the prompt. Worked in testing, failed in prod - the instruction was 14K tokens back by the time it mattered. 5 structural failure modes, no model fixes any of them: 🔧 Tool explosion: 98%→61% accuracy as tools go 3→30 🌍 State drift: agent acts on stale world state 📉 Context collapse: early instructions decay out of attention ⏱️ Latency cascade: sequential hops compound 💸 Cost runaway: tokens grow super-linearly with context A better model shifts the curve's level. Never its slope. Full taxonomy + working LangGraph build + diagnostic checklist 🧵👇 ranjankumar.in/single-agent-f…