{"slug": "7-tips-to-make-your-ai-agent-more-predictable", "title": "7 Tips to Make Your AI Agent More Predictable", "summary": "A developer shared seven tips for making AI coding agents more predictable, based on lessons from building a link-sharing platform with Codex GPT 5.6 Sol and Figma MCP. The tips include writing clear one-sentence prompts, providing examples, and forcing step-by-step reasoning, citing an MIT study that found AI agents increase code written by 180% but shipped code by only 30%.", "body_md": "After months of building with AI coding tools, I found the difference between generated code that works and generated code that ships comes down to how you communicate with the AI. I have been sharing these lessons in a talk called \"It's Dangerous to Code Alone! Take This: Developer's AI Survival Guide\" and people keep asking me to write them down. How big is the gap? An [MIT study across 100,000+ developers](https://www.forbes.com/sites/josipamajic/2026/06/10/ai-coding-agents-write-180-more-code-but-ship-only-30-more-software/) found that AI agents boosted code *written* by ~180%, while code that actually *shipped to production* rose by only ~30%.\n\nTo demonstrate these tips, I built a link-sharing platform so my teammates can share resources without juggling multiple QR codes. I generated the frontend with Codex GPT 5.6 Sol and Figma MCP, and I am adding an AWS Blocks backend to swap out local mocks with real cloud infrastructure. You can find all the prompts in [this repository](https://github.com/salihgueler/some-useful-links).\n\nAll of these tips are applicable to greenfield projects as well. I can't promise you it is going to have the 42 effect :)\n\nEach model reacts to prompts differently. The clearer you get, the faster you achieve your goal.\n\nYou also need to remember that now we don't only have models, we also have effort levels. If you are not mindful about which model you are running with which effort level, you will have a hard time getting the results you want.\n\nHere are some general rules I follow (you can check the `BUILD_PROMPT.md`\n\nand the AWS Blocks skill in the repo for the full picture):\n\nDescribe what you want. Works for simple, well-defined tasks.\n\nHere is my frontend build prompt. One sentence, clear outcome:\n\n```\nBuild \"Some Useful Links\" — a LinkTree-style web application using\nNext.js with SSR enabled. The complete visual design specification\nis in `DESIGN_SPEC.md` and reference screenshots are in the\n`design-previews/` folder. Implement the design pixel-perfectly.\n```\n\nAnd for the backend migration to AWS Blocks:\n\n```\nReplace the local JSON mock services in src/lib/services/local/ with\nAWS Blocks implementations. The service registry (index.ts) is the\nonly file that should change in the existing codebase. Frontend must\nnot be modified.\n```\n\nBoth are zero-shot: one clear task, no ambiguity.\n\nShow examples. Input, output. Input, output. The model picks up the shape. Research shows the format matters more than whether the examples are perfectly correct.\n\nIn my `BUILD_PROMPT.md`\n\n, I use this for the service registry pattern. I show the AI what an implementation swap looks like:\n\n``` js\n// src/lib/services/index.ts\nimport { LocalAnalyticsStore } from './local/analytics-store.local';\nimport { LocalLinkStore } from './local/link-store.local';\nimport { LocalVisitTracker } from './local/visit-tracker.local';\n\n// SWAP POINT: Replace these with cloud implementations\nexport const analyticsStore = new LocalAnalyticsStore();\nexport const linkStore = new LocalLinkStore();\nexport const visitTracker = new LocalVisitTracker();\n```\n\nWhen I ask the AI to build the AWS Blocks backend, it sees this pattern and knows the target: create a `BlocksAnalyticsStore`\n\n, `BlocksLinkStore`\n\n, and `BlocksVisitTracker`\n\nthat implement the same interfaces, then swap them in `index.ts`\n\n. I do not need to explain the concept of dependency injection. The example IS the explanation.\n\nForce the model to reason step by step before acting. For debugging, architecture decisions, or anything multi-step, this cuts logical errors significantly.\n\nI use this when asking the AI to plan the AWS Blocks migration:\n\n```\nBefore writing any code, analyze the existing service interfaces in\nsrc/lib/services/interfaces/. For each interface method, determine:\n1. Which AWS Blocks building block maps to it (DistributedTable, KVStore, FileBucket, etc.)\n2. What the key schema should be to support the query patterns\n3. Whether the method needs authentication (check if the frontend\n   calls it from an admin route or a public route)\n\nWrite your analysis as a numbered plan. I will review it before you\nstart implementing.\n```\n\nThe AI produces a plan I can review before it writes a single line of code. Without this step, it would just start building and often pick the wrong storage pattern for a given query.\n\nUse words like **MUST**, **NEVER**, **ALWAYS**, and **STRICTLY FORBIDDEN**. Avoid weak phrasing like \"Please try to,\" \"It is preferred,\" or \"Usually we do.\"\n\nHere is a comparison from my project. The frontend `BUILD_PROMPT.md`\n\nsets boundaries like this:\n\n```\nAll backend infrastructure must be local mocks — no cloud dependencies.\nThe mocks must be documented clearly enough that another AI agent or\ndeveloper can swap them for any cloud provider without restructuring.\n```\n\nAnd the AWS Blocks skill sets boundaries for the backend side:\n\n```\nBackend lives in `aws-blocks/index.ts`. Frontend imports from\n'aws-blocks' (workspace package). The `client.js` is auto-generated\n— never edit it.\n```\n\nBoth are direct, absolute, and leave no room for interpretation.\n\nTelling the AI what NOT to do is often more effective than listing everything it should do.\n\n**Frontend ( AGENTS.md):**\n\n```\n- Do not add cloud SDKs, deployment configuration, external persistence,\n  or source-controlled credentials unless the task explicitly requires them.\n- Import services from `@/lib/services`; components and route handlers\n  must not import `src/lib/services/local/*` directly.\n- Keep unrelated refactors and generated-file churn out of focused changes.\n```\n\n**Backend (AWS Blocks skill):**\n\n```\n- Adding to an existing project? Scaffold into a temp dir, copy only\n  `aws-blocks/` folder, then manually merge workspace config, scripts,\n  and dependencies. The scaffolder overwrites root package.json,\n  tsconfig.json, vite.config.ts, .gitignore.\n- Never edit index.cdk.ts, index.handler.ts, or client.js — these are\n  auto-generated.\n```\n\nYou need to steer the agent in the correct direction. AI tools have dedicated files for this purpose:\n\n`AGENTS.md`\n\n`CLAUDE.md`\n\n`.kiro/steering/`\n\n)`.kiro/skills/`\n\n)Some of these are loaded every session (steering files), giving the AI persistent rules. Others are loaded on demand (skills), giving the AI specialized knowledge only when it needs it. Both keep your context window lean.\n\nFor the frontend, I have an `AGENTS.md`\n\nat the root that covers the full Next.js application:\n\n```\n# AGENTS.md\n\n## Project Overview\nSome Useful Links is a local-first, multi-page link-sharing application\nbuilt with Next.js App Router, React, strict TypeScript, and Tailwind CSS.\n\n## Commands\nnpm install\nnpm run dev\nnpm run validate:links\nnpm run lint\nnpm run build\n\n## Architecture\n- src/app: App Router pages, layouts, route handlers\n- src/components: UI grouped by admin, analytics, layout, links, share\n- src/lib/services/interfaces: Backend-neutral service contracts\n- src/lib/services/local: Local JSON-backed implementations\n- src/lib/services/index.ts: The only provider registration and swap point\n```\n\nI also have two Kiro steering files that enforce cross-cutting rules regardless of the task:\n\n**TypeScript rules** (`.kiro/steering/typescript.md`\n\n) — enforces strict typing and build validation:\n\n```\n# TypeScript Project Instructions\n\n## Workflows & Validation\n- Pre-completion Check: Before completing any task or reporting success,\n  you MUST run `npm run build` in the terminal.\n- Do not consider a task finished if the build command returns errors. Fix\n  the errors first.\n\n## Coding Conventions\n- Strict typing is enforced. You are strictly forbidden from using the\n  `any` type.\n- Always define and apply the exact, correct types and interfaces for all\n  variables, function parameters, and return values.\n- You are STRICTLY FORBIDDEN from using @ts-ignore.\n  If unavoidable, use @ts-expect-error with a detailed comment.\n```\n\n**Agent behavior rules** (`.kiro/steering/agent.md`\n\n) — controls what the AI can and cannot do on its own:\n\n```\n# Agent Behavior Rules\n\n## File and Folder Boundaries\n- DO NOT create any new Markdown files unless explicitly instructed by\n  the user.\n- STRICTLY FORBIDDEN to auto-generate changelogs or documentation.\n- You MUST update the existing README.md if your changes alter the\n  project's public API or architecture.\n\n## Technology Boundaries\n- You MUST ALWAYS use the Strands Agents library with TypeScript for any\n  agent development.\n- You are STRICTLY REQUIRED to use Claude Haiku 4.5 from Amazon Bedrock\n  for all agent models.\n- You MUST ALWAYS use React and Vite with TypeScript for web development.\n- NEVER write or generate unit tests unless the user explicitly commands\n  it.\n\n## Security Boundaries\n- NEVER commit or hardcode sensitive information (client secrets, API\n  keys, client IDs, resource IDs).\n\n## Git Boundaries\n- Commits MUST stay under 150 lines of source code.\n- Every commit: single-sentence summary, blank line, detailed explanation\n  (max 20 lines).\n- You MUST append `(Kiro)` to the author name using:\n  git commit --author=\"[Git Username] (Kiro) <[User Email]>\"\n```\n\nThese prevent the common annoyances: AI generating unwanted test files, committing giant diffs, sneaking `any`\n\ntypes past the compiler, or littering the repo with markdown files nobody asked for.\n\nSteering files are always loaded. But what about capabilities that are only needed sometimes? You do not want to load everything upfront because that wastes context.\n\nA **Skill** is a reusable, discoverable capability. The AI loads it only when it becomes relevant to the current task. The most important part of a Skill is the name and description. That is how the AI decides whether to use it.\n\nMy AWS Blocks skill activates with this frontmatter:\n\n```\n---\nname: building-aws-blocks-apps\ndescription: \"Builds fullstack TypeScript applications on AWS using\"\n  @aws-blocks/blocks. Use when working with any Building Block\n  (KVStore, DistributedTable, Agent, AuthBasic...), ApiNamespace,\n  BlocksStack, or the create-blocks-app CLI.\n---\n```\n\nThe main `SKILL.md`\n\nis the overview: decision guides, project structure, quick start. Detailed reference lives in separate files:\n\n```\n.kiro/skills/aws-blocks-development/\n├── SKILL.md                    # Overview + decision guide (under 200 lines)\n├── CORE-ARCHITECTURE.md        # Scope, ApiNamespace, JSON-RPC, CORS\n├── TROUBLESHOOTING.md          # Common errors and fixes\n└── blocks/\n    ├── auth-basic.md           # AuthBasic patterns\n    ├── distributed-table.md    # DistributedTable patterns\n    ├── api-namespace.md        # ApiNamespace deep dive\n    └── ... (20+ block files)\n```\n\nWhen the AI needs to implement authentication, it loads `blocks/auth-basic.md`\n\n. When it needs to set up a database, it loads `blocks/distributed-table.md`\n\n. It does not carry all 122 KB of reference material in every conversation.\n\nKeep the root file **under 200 lines**. My `AGENTS.md`\n\nis 127 lines. The AWS Blocks `SKILL.md`\n\nis the overview (under 200 lines), with detailed reference files loaded on demand.\n\nUse the \"Router Pattern\": a root file that points to detailed references when needed. The AWS Blocks skill does exactly this with its block reference table.\n\n**Project Context** tells the AI where it is:\n\n\"This is a Next.js 14 App Router project using Tailwind CSS.\"\n\n**Actionable Rules** tell the AI what to do:\n\n\"Import services from\n\n`@/lib/services`\n\n; components must not import`src/lib/services/local/*`\n\ndirectly.\"\n\nKeep these separate. Context helps the AI orient itself. Rules constrain its behavior.\n\nYour AI sees everything in a stack:\n\n**Performance degrades at 25% capacity, not 100%.** You do not have the full context window available. The degradation starts much earlier than you think.\n\nLong sessions lead to the model \"forgetting\" earlier decisions, fixing one thing and breaking two others. Hallucinations increase as context fills up and your original constraints stop being followed.\n\nI have seen this firsthand. On the frontend side, I asked my AI to follow the service registry pattern from my `AGENTS.md`\n\n. After 15 turns of unrelated work, it started importing directly from `src/lib/services/local/`\n\n, exactly what I told it not to do.\n\nOn the backend side, I had a session where I was building multiple API methods with AWS Blocks. After building the analytics endpoints, I asked it to add authentication. It generated a whole custom auth system instead of using the `AuthBasic`\n\nblock that was in the skill file. The context was too full for it to reference back.\n\nVibe coding skips everything we know about building software: planning, analysis, design, testing, maintenance. All of it gone.\n\nVibe coding works for prototyping and tiny fixes. But for anything beyond that, you need structure.\n\n**Spec-Driven Development (SDD)** is a methodology where detailed, unambiguous requirements are written and agreed upon before any actual coding begins. The spec is the contract between you and your AI.\n\n`BUILD_PROMPT.md`\n\n)\n\n```\n<task>\nBuild \"Some Useful Links\" — a LinkTree-style web application using Next.js\nwith SSR enabled. The complete visual design specification is in\n`DESIGN_SPEC.md` and reference screenshots are in the `design-previews/`\nfolder.\n\nAll backend infrastructure must be local mocks — no cloud dependencies. The\nmocks must be documented clearly enough that another AI agent or developer\ncan swap them for any cloud provider without restructuring.\n</task>\n\n<architecture>\n1. Framework: Next.js (App Router) with Server-Side Rendering enabled\n2. Styling: Tailwind CSS with a custom theme from the design spec\n3. Backend: Local mocks only — no cloud services, no external APIs\n</architecture>\n```\n\n`MIGRATING_TO_CLOUD_PROMPT.md`\n\n)\n\n```\n<task>\nReplace the local JSON mock services in `src/lib/services/local/` with AWS\nBlocks implementations. The existing service interfaces in\n`src/lib/services/interfaces/` are the contract. The service registry\n(`src/lib/services/index.ts`) is the only file that should change in the\nexisting codebase.\n\nThe frontend, routing, components, and design must remain untouched.\n</task>\n\n<architecture>\n1. Backend runtime: AWS Blocks (`aws-blocks/index.ts`)\n2. API layer: ApiNamespace with methods that mirror the existing service\n   interface contracts\n3. Auth: AuthBasic for admin routes (analytics dashboard, page management)\n4. Data — Link pages: DistributedTable (stores page configurations and\n   link entries)\n5. Data — Analytics: DistributedTable (stores daily aggregate snapshots\n   per page slug and date)\n6. Data — Visit events: DistributedTable (stores raw page-view, link-click,\n   and share events)\n7. Hosting: Blocks Hosting for the Next.js frontend\n</architecture>\n\n<acceptance_criteria>\n- [ ] All existing frontend functionality works unchanged\n- [ ] `npm run dev` starts both frontend and AWS Blocks local server on\n      port 3000\n- [ ] Admin routes require AuthBasic login\n- [ ] Click tracking persists events to DistributedTable\n- [ ] `npm run build` completes without TypeScript errors\n- [ ] `npm run deploy` deploys the full stack to AWS\n</acceptance_criteria>\n```\n\nThe AI knows exactly what to build, what the constraints are, and what \"done\" looks like. No ambiguity on either side.\n\nModel Context Protocol (MCP) is an open standard for connecting AI to the outside world. With MCP, your AI can:\n\nRight now there is an MCP server for almost everything: GitHub, Slack, databases, documentation, cloud services.\n\nIn my project, I used this in two places:\n\n**Frontend**: I connected Figma MCP so the AI could reference my actual design system when generating components. Instead of describing colors and spacing in text, it pulled the tokens directly from the Figma file.\n\n**Backend**: AWS Blocks is a new framework. The AI does not know its API surface from training data. Instead of pasting documentation into the chat (wasting context), I added an MCP server that gives the AI access to the AWS Blocks docs and API references on demand. It queries what it needs, when it needs it.\n\nThe result: zero hallucinated API calls. The AI uses `new ApiNamespace(scope, 'api', (context) => ({...}))`\n\nbecause it can look up the actual signature, instead of guessing something like `createApi(...)`\n\n.\n\nSome tasks deserve a spec. Others work fine as a quick conversation with the AI. Knowing which approach to use is what saves you time.\n\nIn my project, I vibe coded the initial design exploration with Figma MCP. But the moment I started building the actual app and the backend migration, I switched to specs. The frontend `BUILD_PROMPT.md`\n\nand the backend AWS Blocks skill together gave the AI everything it needed to produce consistent, predictable results.\n\nI am currently finishing the AWS Blocks backend for the link-sharing project and deploying it. I will write up that process in the next post.\n\nYou can find the full project, including the `BUILD_PROMPT.md`\n\n, `AGENTS.md`\n\n, `MIGRATING_TO_CLOUD_PROMPT.md`\n\n, and the AWS Blocks skill files in [this repository](https://github.com/salihgueler/some-useful-links).", "url": "https://wpnews.pro/news/7-tips-to-make-your-ai-agent-more-predictable", "canonical_source": "https://dev.to/aws/7-tips-to-make-your-ai-agent-more-predictable-1ga4", "published_at": "2026-08-11 10:20:35+00:00", "updated_at": "2026-08-11 10:47:04.293687+00:00", "lang": "en", "topics": ["artificial-intelligence", "ai-agents", "developer-tools", "large-language-models"], "entities": ["Codex GPT 5.6 Sol", "Figma MCP", "AWS Blocks", "MIT"], "alternates": {"html": "https://wpnews.pro/news/7-tips-to-make-your-ai-agent-more-predictable", "markdown": "https://wpnews.pro/news/7-tips-to-make-your-ai-agent-more-predictable.md", "text": "https://wpnews.pro/news/7-tips-to-make-your-ai-agent-more-predictable.txt", "jsonld": "https://wpnews.pro/news/7-tips-to-make-your-ai-agent-more-predictable.jsonld"}}