Claude Code agent risks and how guardrails prevent unseen damage

For three months, developer Rabih Jabr used Anthropic’s Claude Code as his primary coding assistant, relying on its ability to write Ansible playbooks faster than he could. The tool’s efficiency was undeniable, but it also revealed a critical flaw: agents can make decisions that are technically sound in isolation but disastrous in context. One such moment came when Claude suggested a force-push to the main branch to resolve a stuck rebase. The reasoning was flawless, until Jabr realized the command would overwrite shared history, a risk no one reviewing the diff would catch because the diff itself looked correct. This incident highlighted a fundamental problem with AI-driven development: agents see the command but not the blast radius of its consequences.

Jabr’s initial response was exhaustive manual review, but he quickly recognized the unsustainable nature of this approach. Reviewing every command and diff scales linearly with the agent’s output, which is only increasing. Instead, he pivoted to a different strategy: defining explicit boundaries for what the agent must never do. The revelation was that this list could be remarkably short, so short it could fit on a napkin. Each guardrail wasn’t about the agent being reckless; it was about the agent lacking the context to see the broader impact of its actions. For example, blocking the agent from reading sensitive files like .env prevents credentials from being exposed in transcripts, even if the file itself remains unchanged in the repository.

The solution took shape in the form of a lightweight plugin called claude-guardrails, which integrates directly with Claude Code’s PreToolUse hook. This hook fires before any tool call, allowing the plugin to evaluate the command’s intent and either permit or block it. What surprised Jabr was how the agent responded to rejections. When blocked, the agent didn’t argue; it adapted. If told "blocked," it would retry with slightly different syntax. If given a constructive alternative like "change the manifest and run pnpm add," it would execute the corrected command without hesitation. This turned denials into high-signal teaching moments, as the agent learns precisely when and why it was wrong.

The plugin’s design prioritizes precision over recall. Every guardrail must answer two questions: what’s wrong with the command, and what should the agent do instead. For instance, one guardrail prevents the agent from staging sensitive files like .env by checking what a blanket `git add -A` would actually pick up. In a correctly configured repository, ignored files never appear in the output, making the guardrail silent and unobtrusive. This "invisible" property is intentional, guardrails that don’t interfere with workflows are less likely to be removed. Another guardrail addresses the ambiguity of commands like `kubectl delete pod api-7f9d` by refusing execution until the agent clarifies the context with `--context`, ensuring the transcript records what was changed.

Safety is paramount, so the plugin is designed to fail open. If a guardrail crashes, it defaults to allowing the command rather than blocking it, preventing a single bug from halting the entire workflow. This approach ensures the plugin remains installed even if a contributor introduces a faulty rule. The unit of contribution is a single file, making it easy for others to add new guardrails. Each guard must define what it prevents and include executable examples of false positives, such as `--force-with-lease` versus `--force` or `.env.example` versus `.env`. These examples double as test cases, ensuring the guardrail doesn’t inadvertently block legitimate work.

Jabr’s plugin currently includes thirteen guardrails, each addressing a specific risk he has personally encountered. Examples include preventing `terraform apply` without a plan file, blocking `docker system prune -a` on a build cache, stopping `chmod -R 777` debugging steps, and avoiding `ALTER TABLE` commands that lock large datasets. The plugin is written in Node.js, leveraging the fact that Claude Code already ships with Node, making it accessible even to developers who don’t use Unix shells. With zero dependencies, the plugin is lightweight and easy to maintain, though it does include a lockfile guard, a humorous touch given the project’s minimalist design.

The guardrail system isn’t meant to be exhaustive. Jabr emphasizes that guardrails should only be written for commands where the developer has direct experience with the consequences. If a rule is based on a guess rather than a real incident, it risks becoming a false positive that gets the plugin uninstalled. The philosophy is clear: if you’ve got the scar, write the guard. This ensures the plugin remains a practical, actionable tool rather than a theoretical exercise in risk prevention.