Claude Agent Patterns for Security and Compliance Code

Once you have connected Claude to a single security tool, the next problem is not capability — it is consistency. The fifth integration should look like the first, your prompts should not be copy-pasted snowflakes, and a new engineer should be able to read your code and know exactly where the safety lives. That is what patterns are for. This post collects the reusable, code-level patterns I reach for when building Claude agents against security and compliance systems, with an emphasis on structure over cleverness.

None of these are exotic. They are the boring, load-bearing decisions that separate an agent you trust in production from a demo that works until it doesn't. I will frame each as a pattern you can lift directly into your own codebase.

Pattern 1: Tools as a typed contract, not a grab bag

The single highest-leverage pattern is treating every tool as a strict, typed contract. Each tool has a precise input schema with validated fields, a documented output type, and a one-line description written for the model that states what it does and — just as important — what it does not do. Resist the temptation to add a flexible "do_action(query)" escape hatch; that flexibility is exactly what makes an agent unauditable and unsafe.

Concretely, prefer suppress_finding(id, reason) over update_finding(id, fields). The narrow tool encodes intent, validates the one thing it touches, and produces a clean audit line. The broad tool invites the model to do anything to a finding and forces you to reason about every field. In security code, narrowness is a feature. A good rule: if you cannot write the audit-log sentence for a tool in advance, the tool is too broad.

Pattern 2: The propose-gate-execute triad

Every action-taking path in a security agent should follow the same three-phase shape. Claude proposes a tool call. A deterministic gate evaluates it against policy and decides allow, deny, or require-approval. Then, and only then, the tool executes and records the result. Bake this into a shared wrapper so individual tools cannot bypass it; an engineer adding a new tool should get the gate for free.

flowchart TD
  A["Claude proposes tool call"] --> B["Shared wrapper"]
  B --> C["Validate input schema"]
  C --> D{"Gate decision"}
  D -->|Deny| E["Return refusal + log"]
  D -->|Need approval| F["Return approval request + log"]
  D -->|Allow| G["Execute tool"]
  G --> H["Write result + audit record"]
  H --> I["Return typed result to Claude"]

The reason to centralize this is uniformity under change. When you tighten policy — say, you decide all suppressions now need approval — you edit the gate once and every tool inherits the new rule. When the triad is scattered across individual tools, that same change becomes a risky multi-file edit where one missed spot is a hole. Centralization is how you keep the safety surface small enough to actually review.

Pattern 3: Context as a curated briefing, not a dump

A common failure mode is shoveling everything into context — full finding payloads, entire asset inventories, raw policy documents — and hoping the model sorts it out. For security work this is doubly bad: it bloats cost and latency, and it leaks sensitive detail the model does not need to reason. The pattern is to treat context as a briefing you would hand a sharp analyst: the specific finding, the asset's owner and exposure, the relevant policy excerpt, and a pointer to fetch more if needed.

In practice, that means your tools return summaries with IDs rather than firehoses, and the agent fetches detail on demand. It means you put stable procedure in skills and keep the per-request context focused on the case at hand. A lean, intentional context is not just cheaper; it produces sharper reasoning because the model is not distracted by noise. The discipline of asking "does the model actually need this to act correctly" before every field pays off in both bills and behavior.

Pattern 4: Idempotency keys on every write

Agents retry. Networks hiccup, a step times out, a multi-step plan re-runs. In a read-only world that is harmless; in a security world it can mean two tickets, two suppressions, or two remediation triggers. The pattern is to give every write tool an idempotency key derived from the action's meaningful identity — for instance, a hash of finding id plus action type plus the day. The MCP server checks the key before executing and returns the prior result if it has seen it.

This turns dangerous double-actions into safe no-ops without any cleverness in the prompt. It also makes your audit log honest: a retried action shows up once as executed and once as deduplicated, rather than as two real events. Idempotency is the unglamorous pattern that lets you stop worrying about exactly-once delivery and focus on getting the policy right.

Pattern 5: Prompts that state the boundary, not just the goal

The system prompt for a security agent should do more than describe the task; it should explicitly state the boundaries the model operates within. Good security prompts name the tools available, state that destructive actions require approval, and instruct the model to refuse and explain rather than improvise when a request falls outside its tools. They tell the model to cite the finding id and audit reference in its summaries, which makes its output traceable.

The pattern here is to write the prompt as an honest description of the real constraints, so the model's behavior aligns with the deterministic gates rather than fighting them. When the prompt says "you cannot delete findings" and there is genuinely no delete tool, the model stops trying and instead does something useful within bounds. Alignment between what the prompt claims and what the architecture enforces is what produces a calm, predictable agent instead of one that keeps proposing things the gate rejects.

Pattern 6: Test the agent like a security control

Finally, treat the whole agent as something that must pass tests, including adversarial ones. Write cases that assert the gate denies an unapproved remediation, that an over-broad query is capped, that a retried write deduplicates, and that every executed action produced an audit record. Run these as part of your pipeline so a refactor that quietly weakens a control fails loudly.

This is the pattern that keeps the others honest over time. Patterns one through five define how the code should look today; a test suite defines what must remain true tomorrow as people change things. For a security agent, your tests are not just quality assurance — they are a continuous attestation that the controls you documented to your auditors still hold.

Frequently asked questions

How granular should security tools be?

As granular as the distinct intents you want to permit. One tool per meaningful action — suppress, ticket, remediate, enrich — beats a single configurable tool, because each narrow tool validates exactly what it touches and produces a clean audit line. Granularity costs a little boilerplate and buys a lot of safety and reviewability.

Where does idempotency belong — in Claude or the server?

In the server, always. The model cannot be relied on to perfectly avoid retries, and the prompt is not an enforcement mechanism. The MCP server computes or accepts an idempotency key and refuses to execute the same meaningful action twice. Keeping it server-side means the guarantee holds regardless of how the model behaves.

Can I reuse one prompt across multiple security tools?

You can share a common security-agent system prompt that states the universal boundaries — approvals, refusals, citation of audit references — and then let skills supply tool-specific procedure. That split keeps your prompts DRY without making them generic. The shared prompt encodes the safety posture; the skills encode the domain detail.

How do I keep context lean without losing accuracy?

Return summaries with identifiers and let the agent fetch detail on demand, put stable procedure in skills, and ask of every context field whether the model needs it to act correctly. Lean context usually improves accuracy because the model reasons over signal rather than noise. When accuracy does drop, add the one missing fact deliberately rather than widening the dump.

Bringing agentic AI to your phone lines

CallSphere builds on these same patterns — typed tools, propose-gate-execute, idempotent writes, lean context — to run voice and chat agents that answer every call and message, act through your systems, and book work around the clock. See the patterns at work at callsphere.ai.

Source & attribution: This is an independent, original explainer inspired by Anthropic's coverage on the Claude blog. Claude, Claude Code, Claude Cowork, Claude Opus, and the Model Context Protocol are products and trademarks of Anthropic. CallSphere is not affiliated with or endorsed by Anthropic.