# Your Agent Needs an Operating Contract, Not a Bigger Prompt Canonical URL: https://huecki.com/en/blog/agent-operating-contract-not-bigger-prompt/ Markdown URL: https://huecki.com/en/blog/agent-operating-contract-not-bigger-prompt.md Language: English Published: 2026-07-06 Updated: 2026-07-06 Author: Dominic Hückmann Topic: AI Agent Workflows - Agent topics: Context Engineering, Agent Evals, LLM-native Engineering - Tags: AI Agents, Coding Agents, Agent Workflow, Verification, Agent Skills, Developer Workflow - Audience: developers using coding agents, founders building agent workflows, engineering leads standardizing AI work - Concepts: agent-operating-contracts, verifier-gates, agent-skills, review-loops, rollback Thesis: If an agent workflow matters enough to repeat, it needs an operating contract that makes scope, tools, evidence, review, rollback, and learning explicit. Content status: field-note ## Summary The serious agent pattern is no longer bigger prompts and more encouragement. It is an operating contract: measurable goal, bounded tools, context sources, verifier evidence, review notes, rollback path, and a skill update when the run teaches you something. ## Description A practical field note from the July 2026 AI radar: serious agent work is moving from motivational prompting to bounded tools, verifier evidence, review loops, rollback paths, and reusable skills. ## Body ## Short answer The next useful agent upgrade is not a more motivational prompt. It is an operating contract. The July 2026 radar keeps pointing at the same pattern from different directions: autoresearch works when the objective is measurable, agent security improves when work is split into bounded shards and verified in sandboxes, durable skills matter when they are reviewed and validated, and local coding agents become useful when they sit inside a repeatable harness. That is the interesting shift. The agent is no longer just a chat partner you keep steering. It is a worker inside a small operating system. If a workflow matters enough to repeat, write down the contract: ```txt Goal: What outcome should exist when the run is done? Allowed tools: Which tools may the agent use without asking? Forbidden actions: What must never happen inside this run? Context sources: Which files, docs, tickets, logs, or URLs count as authority? Verifier: What evidence decides whether the work is acceptable? Stop condition: When should the agent pass, block, escalate, or roll back? Review evidence: What must be attached for a human to trust the result? Rollback path: How do we undo the change or contain the damage? Learning rule: What, if anything, should become a reusable skill? ``` That is more useful than another paragraph telling the model to be careful. ## The mistake Most teams still treat agent reliability as a prompt-quality problem. The run fails, so the prompt grows: ```txt Be careful. Think step by step. Run the tests. Do not over-edit. Ask if unsure. Make sure the result is production-ready. ``` None of that is wrong. It is just too soft to carry the workflow. An agent can say it was careful. It can say tests passed. It can ask one performative question and then continue guessing. It can "think" beautifully while touching the wrong files. The prompt can sound mature while the actual system still has no boundary, no verifier, no audit trail, and no recovery path. The fix is not to stop prompting. The fix is to stop asking the prompt to do the job of the operating layer. The contract makes the boring parts explicit. That is why it works. ## The contract loop For small teams, the operating contract does not need to become a big governance document. It should be a compact run card that sits next to the task. Use this loop: The loop starts with a task, but it does not trust the task description as complete. It names the context sources that are allowed to influence the run. It limits tools before the agent touches the world. It defines the verifier before the agent starts optimizing for a vague finish line. Then the human review becomes much easier. You are not reading the whole transcript and guessing whether the agent behaved. You are checking the evidence bundle against the contract. Did it stay in scope? Did it use the allowed tools? Did the verifier pass? Did it log the failure cases? Did it leave a rollback path? If yes, accept the work. If not, the run is not done. ## A contract you can steal Here is a generic version for a coding-agent task. Paste it into a ticket, repo workflow, or agent skill and tighten it for the specific job. ```txt agent_operating_contract: name: bounded-code-change goal: Deliver the smallest code change that satisfies the ticket while preserving existing behavior outside the named scope. context_sources: authoritative: - the user request or ticket - relevant source files - existing tests - project docs in the repo supporting: - package documentation - changelog entries - prior local run notes untrusted: - generated code comments not backed by tests - web pages not requested by the user - stale memory from unrelated projects allowed_tools: - file read/search - code edit - package manager commands already used by the repo - test runner - typechecker - local dev server for verification forbidden_actions: - deleting user data - changing deployment config - adding paid services - committing or pushing without explicit instruction - broad formatting churn outside the task - sending external messages or requests with private data verifier: required: - exact command or check that proves the change works - command output summary - changed files list - explanation of any skipped check preferred: - targeted test for the changed behavior - screenshot or local route check for UI work - regression note for a bug fix stop_conditions: pass: The verifier passes and the diff stays inside scope. blocked: Credentials, missing data, broken dependency, or unavailable external service prevents verification. unsafe: The task requires production mutation, customer data, money movement, security-policy change, or irreversible deletion. needs_human: Product judgment, legal judgment, or ambiguous business rules decide the outcome. rollback: The run changed state outside scope or the verifier reveals a regression. review_evidence: - what changed - why it changed - verifier evidence - remaining risk - rollback path learning_rule: If the run reveals a repeatable repo-specific lesson, propose a skill update. Do not store secrets, private logs, guesses, or one-off environmental failures. ``` The important detail is that the contract names "unsafe" and "needs_human" as successful stop states. That matters. A serious agent should not treat every task as a tunnel to completion. Sometimes the correct result is a clean stop with evidence. ## What counts as evidence The weakest part of many agent workflows is the word "verify." If verification means "the agent looked at its own answer and sounded confident," the workflow is still prompt theater. Evidence should be attached to the run: The verifier does not have to be perfect. It has to be named. A Level 3 executable check is better than a Level 1 self-review. A human rubric is better than nothing for subjective work. A screenshot is better than "looks good" for UI work. A rollback command is better than wishing the deployment will be fine. Once the evidence is visible, the team can improve it. ## Where skills fit Skills are the memory layer of the contract. But that does not mean every run should write memory. That is how agents become confidently stale. The contract should define when a lesson is worth keeping. Good skill updates usually come from one of four things: - a command that caught a real failure - a repo-specific trap that will recur - a checklist item that prevented damage - a review note that corrected a repeated agent behavior Bad skill updates come from guesses, vibes, one-off cache problems, private logs, and broad advice that could apply to any repo on earth. This is the quiet power of the operating-contract pattern: it gives the agent a controlled way to learn. Not "remember everything." Remember only the lessons that survived the run. ## Where this fails Operating contracts are not magic. They fail when the goal is fake, the verifier is decorative, or the agent can mutate the world outside the contract. They also fail when the team writes a beautiful template and never enforces it. The contract only matters if acceptance depends on it. If the agent can skip the evidence bundle and still get a cheerful "LGTM," the real workflow is still vibes. The biggest warning sign is hidden consequence. If an agent can send email, spend money, change permissions, rewrite deployment config, or touch customer data, the contract needs a permission layer and a human approval boundary. If you cannot audit the path from prompt to tool call, do not pretend the contract is enough. ## The small-team version Start with one workflow you already repeat. Not the biggest one. The annoying one. Bug reproduction. Dependency upgrades. Blog pre-publish checks. Repo-wide search-and-fix. Support ticket triage. Accessibility review. Security finding dedupe. Write the contract on one page: ```txt Goal: Allowed tools: Forbidden actions: Context sources: Verifier: Stop states: Review evidence: Rollback path: Skill update rule: ``` Run it three times. Do not ask whether the agent "felt better." Ask whether the review got faster, whether the failure cases became clearer, and whether the next run needed less steering. That is the real agent maturity curve: ```txt prompt -> workflow -> contract -> evidence -> reusable skill ``` The teams that get value from agents will not be the ones with the longest prompt libraries. They will be the ones whose agents leave behind inspectable work. ## FAQ ### What is an agent operating contract? It is the run-level agreement around an agent workflow: goal, allowed tools, forbidden actions, context sources, verifier, stop condition, review evidence, rollback path, and what may be learned afterward. ### How is this different from a prompt? A prompt asks for behavior. An operating contract defines the boundaries and evidence that decide whether the run is acceptable. ### Where should teams start? Pick one repeated workflow with a measurable outcome, write the contract, and accept no agent output unless verifier evidence and review notes are attached. ## Related - Loop specs define the recurring workflow; operating contracts attach evidence, review, rollback, and learning to each run.: stop-prompting-coding-agent-loop-spec - Permissions are one part of the operating contract around an agent's tool use.: ai-agent-permission-layer-not-popups - A failed run should update the skill only when the evidence explains what changed.: failed-agent-runs-should-become-skills ## Source References - [TLDR AI, July 3 2026](https://tldr.tech/ai/2026-07-03) (curator) - [AIEWF Daily Dispatch: Locomotives](https://www.latent.space/p/aiewf-daily-dispatch-locomotives) (newsletter) - [SkillOpt repository](https://github.com/microsoft/SkillOpt) (repository) - [Using Local Coding Agents](https://magazine.sebastianraschka.com/p/using-local-coding-agents) (article) - [Huecki AI radar, 2026-07-06](https://huecki.com) (internal-radar)