Insights

Ten best practices for agentic AI development with Claude

Decision contracts, tool design, context engineering, Agent Skills, Claude Code hooks, idempotency, and evals

Adnan Masood, PhD.
Chief AI architect, UST.

An agent is a system in which an artificial intelligence (AI) model chooses its next step while it works, such as which document to read or which tool to call. Anthropic distinguishes agents from workflows, whose paths are fixed in code. That freedom makes agents useful, and it turns their errors into actions: a refund, an outbound email, a payment retried after it already succeeded.

We build agents around three principles: bound the work before adding autonomy, enforce authority outside the model, and evaluate the completed outcome. The practices below apply them to Claude, Claude Code, and the Model Context Protocol (MCP), the open standard for connecting models to tools. The examples and numbers are illustrative.

DIVIDER

1. Write the decision contract before the prompt

A decision contract names the trigger, permitted responsibility, required evidence, completion condition, and exception path."Fix customer escalations" is a wish. "When a support employee opens an unresolved case, retrieve the policy, propose a disposition, and escalate when evidence is missing" is buildable. Keep drafts, recommendations, and refunds as separate outputs, because each crosses a different line of authority. Scope errors surface late: a pilot can report 89% first-response acceptance while specialists overturn its recommendations on criteria the assistant never saw.

DIVIDER

2. Start with a workflow and make autonomy earn its place

Anthropic advises the simplest solution that works, adding agentic complexity when task performance justifies the latency and cost. Ticket classification is a workflow. Investigating why a covered claim was rejected is agentic, because each step depends on the last. Build the hybrid: deterministic code around a bounded investigation with an explicit budget (six reads, one retry, a wall-clock limit) and a distinct status for each way it stops. Tax math and reconciliation stay in tested code.

DIVIDER

3. Give Claude fewer, sharper tools

Anthropic recommends consolidating overlapping tools, namespacing related ones under a shared prefix, writing descriptions that say when to use each, and returning token-efficient results. (A token is the word fragment models read and bill by.) A tool named list_missing_claim_documents states one narrow, read-only purpose; process_claim could mean anything from a lookup to a payment. When a 34-tool assistant starts choosing badly, repair the overlapping descriptions before adding a routing model. Adding a router to a confused toolset gives the confusion a manager.

DIVIDER

4. Treat the context window as a budget

Anthropic's context-engineering guidance asks for the smallest possible set of high-signal tokens. Put stable tools and instructions first, because prompt caching reuses an unchanged prefix built in the order tools, system, then messages; a timestamp at the top of the system prompt defeats the cache. Put long documents before the question. Hand focused investigations to Claude Code subagents, which run in separate context windows with their own prompts and tool allowlists and return summaries. Retrieved text is untrusted evidence, whatever it claims to be.

DIVIDER

5. Package procedures as Agent Skills and keep authority out of them

A procedure reused in three workflows should exist once, with an owner and a version. Agent Skills package instructions, resources, and scripts that Claude loads through progressive disclosure: a short description first, the full contents when a task needs them. Stable repository conventions belong in CLAUDE.md. Log the Skill version on every run so a regression traces to a release. A Skill grants no permission, and its scripts face the same execution controls as any other code.

DIVIDER

6. Enforce permissions in code the model cannot talk past

A system prompt that says "never refund more than $500" is a suggestion. The Open Worldwide Application Security Project (OWASP) calls the failure mode excessive agency and recommends minimal tool functionality, least privilege, and downstream authorization. In Claude Code, enforce with permission rules and PreToolUse hooks, which run before a tool executes and can deny it, deployed through managed settings for anything nonnegotiable. As of October 2026, a command hook that crashes or times out lets the call proceed unless onFailure is block, and subagents inherit the parent's permission mode, bypassPermissions included. Give payment status a read-only identity.

DIVIDER

7. Assume prompt injection and cut the exfiltration path

An assistant that reads internal documents and makes arbitrary outbound Hypertext Transfer Protocol (HTTP) calls holds both halves of a data leak. Prompt injection, a malicious instruction hidden in content the model reads, connects them. Replace "fetch any web address" with narrow operations, allowlist destinations, validate redirects, and block private-network addresses, per MCP's guidance on server-side request forgery. Resolve email recipients in the backend so Claude never supplies one. Test with planted instructions and direct tool calls; the evidence you want is a blocked call in the runtime log.

DIVIDER

8. Keep state in the application and make every side effect idempotent

Conversation history makes a poor ledger. Keep evidence references, procedure version, proposed action, approval, and execution status in an application-owned record, the discipline Anthropic recommends for structured notes kept outside the context window. Bind each approval to the exact account, amount, destination, and proposal version. Give every external call a persisted idempotency key, an identifier that lets the receiving system treat a retry as the original request. When a payment call times out, record "outcome unknown" and reconcile before any retry.

DIVIDER

9. Evaluate the end state with graders matched to the property

An agent's report that a refund went through is a claim, and the ledger is the evidence. Anthropic's eval guidance separates the transcript from the outcome and combines code, model, and human graders. Derive cases from the decision contract, including permission denials, planted instructions, and tool failures. A correct refusal passes; an over-refusal of a permitted request fails. Check state with code, calibrate model graders against specialist labels, keep a held-out set, and rerun the suite when a prompt, tool description, Skill, or model changes.

DIVIDER

10. Measure cost per accepted resolution, including the humans

Token cost is a component metric. The business metric is cost per accepted resolution: inference (running the model), retrieval, retries, review, and rework, divided by resolutions that meet acceptance criteria. In Table 1, review time decides the answer.

Table 1. Hypothetical cost per 1,000 cases ($3 per review)

The design built on the model that costs four times as much per call runs 59% cheaper. Size review queues the same way: 1,000 cases a day at a 20% review rate and five minutes each is about 16.7 reviewer-hours, so define a degraded mode for the day those hours run out.

DIVIDER

What to require before granting more autonomy

The strongest objection is that better models will retire this scaffolding. Some of it will go: tool counts, exploration budgets, and prompt layering are tuning choices to revisit at each model upgrade, with the evals deciding. The authority boundary stays, because a more capable model gets more consequential work, and prompt injection exploits the same instruction-following that makes Claude useful. Before approving more autonomy, I ask for three documents: the decision contract, an authority map showing where each consequential action is enforced outside the model, and the pilot's cost per accepted resolution, review hours included. If one is missing, the expansion waits.