This put up first appeared on Addy Osmani’s Elevate Substack publication and is being republished right here with the writer’s permission.
TL;DR: Intention for a transparent spec masking simply sufficient nuance (this will embrace construction, type, testing, boundaries. . .) to information the AI with out overwhelming it. Break massive duties into smaller ones versus protecting all the things in a single massive immediate. Plan first in read-only mode, then execute and iterate repeatedly.
“I’ve heard loads about writing good specs for AI brokers, however haven’t discovered a stable framework but. I may write a spec that rivals an RFC, however in some unspecified time in the future the context is simply too massive and the mannequin breaks down.”
Many builders share this frustration. Merely throwing an enormous spec at an AI agent doesn’t work—context window limits and the mannequin’s “consideration funds” get in the best way. The hot button is to put in writing sensible specs: paperwork that information the agent clearly, keep inside sensible context sizes, and evolve with the venture. This information distills greatest practices from my use of coding brokers together with Claude Code and Gemini CLI right into a framework for spec-writing that retains your AI brokers targeted and productive.
We’ll cowl 5 ideas for excellent AI agent specs, every beginning with a bolded takeaway.
1. Begin with a Excessive-Degree Imaginative and prescient and Let the AI Draft the Particulars
Kick off your venture with a concise high-level spec, then have the AI increase it into an in depth plan.
As an alternative of overengineering upfront, start with a transparent objective assertion and some core necessities. Deal with this as a “product transient” and let the agent generate a extra elaborate spec from it. This leverages the AI’s power in elaboration when you preserve management of the course. This works properly until you already really feel you might have very particular technical necessities that have to be met from the beginning.
Why this works: LLM-based brokers excel at fleshing out particulars when given a stable high-level directive, however they want a transparent mission to keep away from drifting astray. By offering a brief define or goal description and asking the AI to provide a full specification (e.g., a spec.md), you create a persistent reference for the agent. Planning prematurely issues much more with an agent: You may iterate on the plan first, then hand it off to the agent to put in writing the code. The spec turns into the primary artifact you and the AI construct collectively.
Sensible method: Begin a brand new coding session by prompting
You're an AI software program engineer. Draft an in depth specification for
[project X] masking targets, options, constraints, and a step-by-step plan.
Maintain your preliminary immediate high-level: e.g., “Construct an online app the place customers can
monitor duties (to-do checklist), with consumer accounts, a database, and a easy UI.”
The agent would possibly reply with a structured draft spec: an outline, characteristic checklist, tech stack recommendations, information mannequin, and so forth. This spec then turns into the “supply of fact” that each you and the agent can refer again to. GitHub’s AI group promotes spec-driven growth the place “specs turn into the shared supply of fact…residing, executable artifacts that evolve with the venture.” Earlier than writing any code, overview and refine the AI’s spec. Make sure that it aligns together with your imaginative and prescient and proper any hallucinations or off-target particulars.
Use Plan Mode to implement planning-first: Instruments like Claude Code supply a Plan Mode that restricts the agent to read-only operations—it could possibly analyze your codebase and create detailed plans however received’t write any code till you’re prepared. That is excellent for the planning section: Begin in Plan Mode (Shift+Tab in Claude Code), describe what you wish to construct, and let the agent draft a spec whereas exploring your present code. Ask it to make clear ambiguities by questioning you concerning the plan. Have it overview the plan for structure, greatest practices, safety dangers, and testing technique. The objective is to refine the plan till there’s no room for misinterpretation. Solely then do you exit Plan Mode and let the agent execute. This workflow prevents the widespread lure of leaping straight into code technology earlier than the spec is stable.
Use the spec as context: As soon as permitted, save this spec (e.g., as SPEC.md) and feed related sections into the agent as wanted. Many builders utilizing a robust mannequin do precisely this. The spec file persists between periods, anchoring the AI each time work resumes on the venture. This mitigates the forgetfulness that may occur when the dialog historical past will get too lengthy or when you need to restart an agent. It’s akin to how one would use a product necessities doc (PRD) in a group: a reference that everybody (human or AI) can seek the advice of to remain on monitor. Skilled people usually “write good documentation first and the mannequin could possibly construct the matching implementation from that enter alone” as one engineer noticed. The spec is that documentation.
Maintain it objective oriented: A high-level spec for an AI agent ought to give attention to what and why greater than the nitty-gritty how (at the least initially). Consider it just like the consumer story and acceptance standards: Who’s the consumer? What do they want? What does success seem like? (For instance, “Consumer can add, edit, full duties; information is saved persistently; the app is responsive and safe.”) This retains the AI’s detailed spec grounded in consumer wants and final result, not simply technical to-dos. Because the GitHub Spec Equipment docs put it, present a high-level description of what you’re constructing and why, and let the coding agent generate an in depth specification specializing in consumer expertise and success standards. Beginning with this big-picture imaginative and prescient prevents the agent from dropping sight of the forest for the bushes when it later will get into coding.
2. Construction the Spec Like a Skilled PRD (or SRS)
Deal with your AI spec as a structured doc (PRD) with clear sections, not a unfastened pile of notes.
Many builders deal with specs for brokers very similar to conventional product requirement paperwork (PRDs) or system design docs: complete, well-organized, and straightforward for a “literal-minded” AI to parse. This formal method offers the agent a blueprint to observe and reduces ambiguity.
The six core areas
GitHub’s evaluation of over 2,500 agent configuration information revealed a transparent sample: The simplest specs cowl six areas. Use this as a guidelines for completeness:
- Instructions: Put executable instructions early—not simply device names however full instructions with flags:
npm check,pytest -v,npm run construct. The agent will reference these continually. - Testing: Methods to run checks, what framework you employ, the place check information dwell, and what protection expectations exist.
- Undertaking construction: The place supply code lives, the place checks go, the place docs belong. Be express: “
src/for utility code,checks/for unit checks,docs/for documentation.” - Code type: One actual code snippet displaying your type beats three paragraphs describing it. Embrace naming conventions, formatting guidelines, and examples of fine output.
- Git workflow: Department naming, commit message format, PR necessities. The agent can observe these if you happen to spell them out.
- Boundaries: What the agent ought to by no means contact—secrets and techniques, vendor directories, manufacturing configs, particular folders. “By no means commit secrets and techniques” was the one most typical useful constraint within the GitHub examine.
Be particular about your stack: Say “React 18 with TypeScript, Vite, and Tailwind CSS,” not “React venture.” Embrace variations and key dependencies. Imprecise specs produce obscure code.
Use a constant format: Readability is king. Many devs use Markdown headings and even XML-like tags within the spec to delineate sections as a result of AI fashions deal with well-structured textual content higher than free-form prose. For instance, you would possibly construction the spec as:
# Undertaking Spec: My group's duties app
## Goal
- Construct an online app for small groups to handle duties...
## Tech Stack
- React 18+, TypeScript, Vite, Tailwind CSS
- Node.js/Specific backend, PostgreSQL, Prisma ORM
## Instructions
- Construct: `npm run construct` (compiles TypeScript, outputs to dist/)
- Take a look at: `npm check` (runs Jest, should cross earlier than commits)
- Lint: `npm run lint --fix` (auto-fixes ESLint errors)
## Undertaking Construction
- `src/` – Utility supply code
- `checks/` – Unit and integration checks
- `docs/` – Documentation
## Boundaries
- ✅ At all times: Run checks earlier than commits, observe naming conventions
- ⚠️ Ask first: Database schema adjustments, including dependencies
- 🚫 By no means: Commit secrets and techniques, edit node_modules/, modify CI configThis degree of group not solely helps you assume clearly but in addition helps the AI discover data. Anthropic engineers advocate organizing prompts into distinct sections (like
Combine specs into your toolchain: Deal with specs as “executable artifacts” tied to model management and CI/CD. The GitHub Spec Equipment makes use of a four-phase gated workflow that makes your specification the middle of your engineering course of. As an alternative of writing a spec and setting it apart, the spec drives the implementation, checklists, and activity breakdowns. Your major function is to steer; the coding agent does the majority of the writing. Every section has a particular job, and also you don’t transfer to the following one till the present activity is totally validated:
1. Specify: You present a high-level description of what you’re constructing and why, and the coding agent generates an in depth specification. This isn’t about technical stacks or app design—it’s about consumer journeys, experiences, and what success appears to be like like. Who will use this? What drawback does it resolve? How will they work together with it? Consider it as mapping the consumer expertise you wish to create, and letting the coding agent flesh out the main points. This turns into a residing artifact that evolves as you study extra.
2. Plan: Now you get technical. You present your required stack, structure, and constraints, and the coding agent generates a complete technical plan. If your organization standardizes on sure applied sciences, that is the place you say so. In case you’re integrating with legacy programs or have compliance necessities, all of that goes right here. You may ask for a number of plan variations to match approaches. In case you make inside docs obtainable, the agent can combine your architectural patterns straight into the plan.
3. Duties: The coding agent takes the spec and plan and breaks them into precise work—small, reviewable chunks that every resolve a particular piece of the puzzle. Every activity needs to be one thing you possibly can implement and check in isolation, nearly like test-driven growth on your AI agent. As an alternative of “construct authentication,” you get concrete duties like “create a consumer registration endpoint that validates electronic mail format.”
4. Implement: Your coding agent tackles duties one after the other (or in parallel). As an alternative of reviewing thousand-line code dumps, you overview targeted adjustments that resolve particular issues. The agent is aware of what to construct (specification), the right way to construct it (plan), and what to work on (activity). Crucially, your function is to confirm at every section: Does the spec seize what you need? Does the plan account for constraints? Are there edge circumstances the AI missed? The method builds in checkpoints so that you can critique, spot gaps, and course-correct earlier than shifting ahead.
This gated workflow prevents what Willison calls “home of playing cards code”: fragile AI outputs that collapse beneath scrutiny. Anthropic’s Abilities system provides an analogous sample, letting you outline reusable Markdown-based behaviors that brokers invoke. By embedding your spec in these workflows, you make sure the agent can’t proceed till the spec is validated, and adjustments propagate robotically to activity breakdowns and checks.
Think about brokers.md for specialised personas: For instruments like GitHub Copilot, you possibly can create brokers.md information that outline specialised agent personas—a @docs-agent for technical writing, a @test-agent for QA, a @security-agent for code overview. Every file acts as a targeted spec for that persona’s conduct, instructions, and bounds. That is significantly helpful if you need completely different brokers for various duties fairly than one general-purpose assistant.
Design for agent expertise (AX): Simply as we design APIs for developer expertise (DX), take into account designing specs for “agent expertise.” This implies clear, parseable codecs: OpenAPI schemas for any APIs the agent will devour, llms.txt information that summarize documentation for LLM consumption, and express kind definitions. The Agentic AI Basis (AAIF) is standardizing protocols like MCP (Mannequin Context Protocol) for device integration. Specs that observe these patterns are simpler for brokers to devour and act on reliably.
PRD versus SRS mindset: It helps to borrow from established documentation practices. For AI agent specs, you’ll usually mix these into one doc (as illustrated above), however masking each angles serves you properly. Writing it like a PRD ensures you embrace user-centric context (“the why behind every characteristic”) so the AI doesn’t optimize for the fallacious factor. Increasing it like an SRS ensures you nail down the specifics the AI might want to really generate right code (like what database or API to make use of). Builders have discovered that this additional upfront effort pays off by drastically lowering miscommunications with the agent later.
Make the spec a “residing doc”: Don’t write it and neglect it. Replace the spec as you and the agent make selections or uncover new information. If the AI needed to change the info mannequin otherwise you determined to chop a characteristic, replicate that within the spec so it stays the bottom fact. Consider it as version-controlled documentation. In spec-driven workflows, the spec drives implementation, checks, and activity breakdowns, and also you don’t transfer to coding till the spec is validated. This behavior retains the venture coherent, particularly if you happen to or the agent step away and are available again later. Bear in mind, the spec isn’t only for the AI—it helps you because the developer preserve oversight and make sure the AI’s work meets the actual necessities.
3. Break Duties into Modular Prompts and Context, Not One Huge Immediate
Divide and conquer: Give the AI one targeted activity at a time fairly than a monolithic immediate with all the things directly.
Skilled AI engineers have discovered that attempting to stuff your entire venture (all necessities, all code, all directions) right into a single immediate or agent message is a recipe for confusion. Not solely do you danger hitting token limits; you additionally danger the mannequin dropping focus because of the “curse of directions”—too many directives inflicting it to observe none of them properly. The answer is to design your spec and workflow in a modular approach, tackling one piece at a time and pulling in solely the context wanted for that piece.
The curse of an excessive amount of context/directions: Analysis has confirmed what many devs anecdotally noticed: as you pile on extra directions or information into the immediate, the mannequin’s efficiency in adhering to every one drops considerably. One examine dubbed this the “curse of directions”, displaying that even GPT-4 and Claude wrestle when requested to fulfill many necessities concurrently. In sensible phrases, if you happen to current 10 bullet factors of detailed guidelines, the AI would possibly obey the primary few and begin overlooking others. The higher technique is iterative focus. Tips from business recommend decomposing complicated necessities into sequential, easy directions as a greatest apply. Focus the AI on one subproblem at a time, get that carried out, then transfer on. This retains the standard excessive and errors manageable.
Divide the spec into phases or parts: In case your spec doc could be very lengthy or covers a whole lot of floor, take into account splitting it into components (both bodily separate information or clearly separate sections). For instance, you might need a piece for “backend API spec” and one other for “frontend UI spec.” You don’t have to all the time feed the frontend spec to the AI when it’s engaged on the backend, and vice versa. Many devs utilizing multi-agent setups even create separate brokers or subprocesses for every half (e.g., one agent works on database/schema, one other on API logic, one other on frontend—every with the related slice of the spec). Even if you happen to use a single agent, you possibly can emulate this by copying solely the related spec part into the immediate for that activity. Keep away from context overload: Don’t combine authentication duties with database schema adjustments in a single go, because the DigitalOcean AI information warns. Maintain every immediate tightly scoped to the present objective.
Prolonged TOC/summaries for giant specs: One intelligent approach is to have the agent construct an prolonged desk of contents with summaries for the spec. That is primarily a “spec abstract” that condenses every part into just a few key factors or key phrases, and references the place particulars will be discovered. For instance, in case your full spec has a piece on safety necessities spanning 500 phrases, you might need the agent summarize it to: “Safety: Use HTTPS, shield API keys, implement enter validation (see full spec §4.2).” By making a hierarchical abstract within the planning section, you get a hen’s-eye view that may keep within the immediate, whereas the tremendous particulars stay offloaded until wanted. This prolonged TOC acts as an index: The agent can seek the advice of it and say, “Aha, there’s a safety part I ought to take a look at,” and you’ll then present that part on demand. It’s much like how a human developer skims an overview after which flips to the related web page of a spec doc when engaged on a particular half.
To implement this, you possibly can immediate the agent after writing the spec: “Summarize the spec above into a really concise define with every part’s key factors and a reference tag.” The outcome could be an inventory of sections with one or two sentence summaries. That abstract will be stored within the system or assistant message to information the agent’s focus with out consuming up too many tokens. This hierarchical summarization method is understood to assist LLMs preserve long-term context by specializing in the high-level construction. The agent carries a “psychological map” of the spec.
Make the most of subagents or “abilities” for various spec components: One other superior method is utilizing a number of specialised brokers (what Anthropic calls subagents or what you would possibly name “abilities”). Every subagent is configured for a particular space of experience and given the portion of the spec related to that space. As an example, you might need a database designer subagent that solely is aware of concerning the information mannequin part of the spec, and an API coder subagent that is aware of the API endpoints spec. The primary agent (or an orchestrator) can route duties to the suitable subagent robotically.
The profit is every agent has a smaller context window to take care of and a extra targeted function, which might increase accuracy and permit parallel work on impartial duties. Anthropic’s Claude Code helps this by letting you outline subagents with their very own system prompts and instruments. “Every subagent has a particular function and experience space, makes use of its personal context window separate from the primary dialog, and has a customized system immediate guiding its conduct,” as their docs describe. When a activity comes up that matches a subagent’s area, Claude can delegate that activity to it, with the subagent returning outcomes independently.
Parallel brokers for throughput: Operating a number of brokers concurrently is rising as “the following huge factor” for developer productiveness. Fairly than ready for one agent to complete earlier than beginning one other activity, you possibly can spin up parallel brokers for non-overlapping work. Willison describes this as “embracing parallel coding brokers” and notes it’s “surprisingly efficient, if mentally exhausting.” The hot button is scoping duties so brokers don’t step on one another: One agent codes a characteristic whereas one other writes checks, or separate parts get constructed concurrently. Orchestration frameworks like LangGraph or OpenAI Swarm may also help coordinate these brokers, and shared reminiscence through vector databases (like Chroma) lets them entry widespread context with out redundant prompting.
Single versus multi-agent: When to make use of every
| Single agent parallel | Multi-agent | |
| Strengths | Easier setup; decrease overhead; simpler to debug and observe | Increased throughput; handles complicated interdependencies; specialists per area |
| Challenges | Context overload on huge tasks; slower iteration; single level of failure | Coordination overhead; potential conflicts; wants shared reminiscence (e.g., vector DBs) |
| Greatest for | Remoted modules; small-to-medium tasks; early prototyping | Giant codebases; one codes + one checks + one opinions; impartial options |
| Suggestions | Use spec summaries; refresh context per activity; begin contemporary periods usually | Restrict to 2–3 brokers initially; use MCP for device sharing; outline clear boundaries |
In apply, utilizing subagents or skill-specific prompts would possibly seem like: You preserve a number of spec information (or immediate templates)—e.g., SPEC_backend.md, SPEC_frontend.md—and also you inform the AI, “For backend duties, discuss with SPEC_backend; for frontend duties discuss with SPEC_frontend.” Or in a device like Cursor/Claude, you really spin up a subagent for every. That is actually extra complicated to arrange than a single-agent loop, however it mimics what human builders do: We mentally compartmentalize a big spec into related chunks. (You don’t hold the entire 50-page spec in your head directly; you recall the half you want for the duty at hand, and have a common sense of the general structure.) The problem, as famous, is managing interdependencies: The subagents should nonetheless coordinate. (The frontend must know the API contract from the backend spec, and many others.) A central overview (or an “architect” agent) may also help by referencing the subspecs and making certain consistency.
Focus every immediate on one activity/part: Even with out fancy multi-agent setups, you possibly can manually implement modularity. For instance, after the spec is written, your subsequent transfer could be: “Step 1: Implement the database schema.” You feed the agent the database part of the spec solely, plus any international constraints from the spec (like tech stack). The agent works on that. Then for Step 2, “Now implement the authentication characteristic”, you present the auth part of the spec and perhaps the related components of the schema if wanted. By refreshing the context for every main activity, you make sure the mannequin isn’t carrying a whole lot of stale or irrelevant data that would distract it. As one information suggests: “Begin contemporary: start new periods to clear context when switching between main options.” You may all the time remind the agent of vital international guidelines (from the spec’s constraints part) every time, however don’t shove your entire spec in if it’s not all wanted.
Use in-line directives and code TODOs: One other modularity trick is to make use of your code or spec as an lively a part of the dialog. As an example, scaffold your code with // TODO feedback that describe what must be carried out, and have the agent fill them one after the other. Every TODO primarily acts as a mini-spec for a small activity. This retains the AI laser targeted (“implement this particular operate in line with this spec snippet”), and you’ll iterate in a good loop. It’s much like giving the AI a guidelines merchandise to finish fairly than the entire guidelines directly.
The underside line: Small, targeted context beats one big immediate. This improves high quality and retains the AI from getting “overwhelmed” by an excessive amount of directly. As one set of greatest practices sums up, present “One Job Focus” and “Related information solely” to the mannequin, and keep away from dumping all the things in every single place. By structuring the work into modules—and utilizing methods like spec summaries or subspec brokers—you’ll navigate round context dimension limits and the AI’s short-term reminiscence cap. Bear in mind, a well-fed AI is sort of a well-fed operate: Give it solely the inputs it wants for the job at hand.
4. Construct in Self-Checks, Constraints, and Human Experience
Make your spec not only a to-do checklist for the agent but in addition a information for high quality management—and don’t be afraid to inject your individual experience.
spec for an AI agent anticipates the place the AI would possibly go fallacious and units up guardrails. It additionally takes benefit of what you already know (area data, edge circumstances, “gotchas”) so the AI doesn’t function in a vacuum. Consider the spec as each coach and referee for the AI: It ought to encourage the proper method and name out fouls.
Use three-tier boundaries: GitHub’s evaluation of two,500+ agent information discovered that the best specs use a three-tier boundary system fairly than a easy checklist of don’ts. This provides the agent clearer steerage on when to proceed, when to pause, and when to cease:
✅ At all times do: Actions the agent ought to take with out asking. “At all times run checks earlier than commits.” “At all times observe the naming conventions within the type information.” “At all times log errors to the monitoring service.”
⚠️ Ask first: Actions that require human approval. “Ask earlier than modifying database schemas.” “Ask earlier than including new dependencies.” “Ask earlier than altering CI/CD configuration.” This tier catches high-impact adjustments that could be tremendous however warrant a human examine.
🚫 By no means do: Laborious stops. “By no means commit secrets and techniques or API keys.” “By no means edit node_modules/ or vendor/.” “By no means take away a failing check with out express approval.” “By no means commit secrets and techniques” was the one most typical useful constraint within the examine.
This three-tier method is extra nuanced than a flat checklist of guidelines. It acknowledges that some actions are all the time secure, some want oversight, and a few are categorically off-limits. The agent can proceed confidently on “At all times” objects, flag “Ask first” objects for overview, and hard-stop on “By no means” objects.
Encourage self-verification: One highly effective sample is to have the agent confirm its work towards the spec robotically. In case your tooling permits, you possibly can combine checks like unit checks or linting that the AI can run after producing code. However even on the spec/immediate degree, you possibly can instruct the AI to double-check (e.g., “After implementing, examine the outcome with the spec and make sure all necessities are met. Listing any spec objects that aren’t addressed.”). This pushes the LLM to replicate on its output relative to the spec, catching omissions. It’s a type of self-audit constructed into the method.
As an example, you would possibly append to a immediate: “(After writing the operate, overview the above necessities checklist and guarantee every is happy, marking any lacking ones).” The mannequin will then (ideally) output the code adopted by a brief guidelines indicating if it met every requirement. This reduces the possibility it forgets one thing earlier than you even run checks. It’s not foolproof, however it helps.
LLM-as-a-Decide for subjective checks: For standards which can be laborious to check robotically—code type, readability, adherence to architectural patterns—think about using “LLM-as-a-Decide.” This implies having a second agent (or a separate immediate) overview the primary agent’s output towards your spec’s high quality pointers. Anthropic and others have discovered this efficient for subjective analysis. You would possibly immediate “Evaluation this code for adherence to our type information. Flag any violations.” The decide agent returns suggestions that both will get included or triggers a revision. This provides a layer of semantic analysis past syntax checks.
Conformance testing: Willison advocates constructing conformance suites—language-independent checks (usually YAML based mostly) that any implementation should cross. These act as a contract: In case you’re constructing an API, the conformance suite specifies anticipated inputs/outputs, and the agent’s code should fulfill all circumstances. That is extra rigorous than advert hoc unit checks as a result of it’s derived straight from the spec and will be reused throughout implementations. Embrace conformance standards in your spec’s success part (e.g., “Should cross all circumstances in conformance/api-tests.yaml”).
Leverage testing within the spec: If attainable, incorporate a check plan and even precise checks in your spec and immediate circulate. In conventional growth, we use TDD or write check circumstances to make clear necessities—you are able to do the identical with AI. For instance, within the spec’s success standards, you would possibly say, “These pattern inputs ought to produce these outputs…” or “The next unit checks ought to cross.” The agent will be prompted to run by these circumstances in its head or really execute them if it has that functionality. Willison famous that having a sturdy check suite is like giving the brokers superpowers: They will validate and iterate shortly when checks fail. In an AI coding context, writing a little bit of pseudocode for checks or anticipated outcomes within the spec can information the agent’s implementation. Moreover, you should utilize a devoted “check agent” in a subagent setup that takes the spec’s standards and repeatedly verifies the “code agent’s” output.
Deliver your area data: Your spec ought to replicate insights that solely an skilled developer or somebody with context would know. For instance, if you happen to’re constructing an ecommerce agent and you already know that “merchandise” and “classes” have a many-to-many relationship, state that clearly. (Don’t assume the AI will infer it—it may not.) If a sure library is notoriously difficult, point out pitfalls to keep away from. Basically, pour your mentorship into the spec. The spec can include recommendation like “If utilizing library X, be careful for reminiscence leak situation in model Y (apply workaround Z).” This degree of element is what turns a mean AI output into a really sturdy resolution, since you’ve steered the AI away from widespread traps.
Additionally, in case you have preferences or type pointers (say, “use useful parts over class parts in React”), encode that within the spec. The AI will then emulate your type. Many engineers even embrace small examples within the spec (for example, “All API responses needs to be JSON, e.g., {“error”: “message”} for errors.”). By giving a fast instance, you anchor the AI to the precise format you need.
Minimalism for easy duties: Whereas we advocate thorough specs, a part of experience is understanding when to maintain it easy. For comparatively easy, remoted duties, an overbearing spec can really confuse greater than assist. In case you’re asking the agent to do one thing simple (like “middle a div on the web page”), you would possibly simply say, “Make sure that to maintain the answer concise and don’t add extraneous markup or kinds.” No want for a full PRD there. Conversely, for complicated duties (like “implement an OAuth circulate with token refresh and error dealing with”), that’s if you escape the detailed spec. rule of thumb: Alter spec element to activity complexity. Don’t underspec a tough drawback (the agent will flail or go off-track), however don’t overspec a trivial one (the agent would possibly get tangled or deplete context on pointless directions).
Keep the AI’s “persona” if wanted: Typically, a part of your spec is defining how the agent ought to behave or reply, particularly if the agent interacts with customers. For instance, if constructing a buyer help agent, your spec would possibly embrace pointers like “Use a pleasant {and professional} tone” and “In case you don’t know the reply, ask for clarification or supply to observe up fairly than guessing.” These sorts of guidelines (usually included in system prompts) assist hold the AI’s outputs aligned with expectations. They’re primarily spec objects for AI conduct. Maintain them constant and remind the mannequin of them if wanted in lengthy periods. (LLMs can “drift” in type over time if not stored on a leash.)
You stay the exec within the loop: The spec empowers the agent, however you stay the last word high quality filter. If the agent produces one thing that technically meets the spec however doesn’t really feel proper, belief your judgement. Both refine the spec or straight alter the output. The beauty of AI brokers is that they don’t get offended—in the event that they ship a design that’s off, you possibly can say, “Really, that’s not what I meant, let’s make clear the spec and redo it.” The spec is a residing artifact in collaboration with the AI, not a one-time contract you possibly can’t change.
Simon Willison humorously likened working with AI brokers to “a really bizarre type of administration” and even “getting good outcomes out of a coding agent feels uncomfortably near managing a human intern.” You’ll want to present clear directions (the spec), guarantee they’ve the mandatory context (the spec and related information), and provides actionable suggestions. The spec units the stage, however monitoring and suggestions throughout execution are key. If an AI was a “bizarre digital intern who will completely cheat if you happen to give them an opportunity,” the spec and constraints you write are the way you stop that dishonest and hold them on activity.
Right here’s the payoff: spec doesn’t simply inform the AI what to construct; it additionally helps it self-correct and keep inside secure boundaries. By baking in verification steps, constraints, and your hard-earned data, you drastically enhance the percentages that the agent’s output is right on the primary strive (or at the least a lot nearer to right). This reduces iterations and people “Why on Earth did it do this?” moments.
5. Take a look at, Iterate, and Evolve the Spec (and Use the Proper Instruments)
Consider spec writing and agent constructing as an iterative loop: check early, collect suggestions, refine the spec, and leverage instruments to automate checks.
The preliminary spec will not be the tip—it’s the start of a cycle. The perfect outcomes come if you frequently confirm the agent’s work towards the spec and alter accordingly. Additionally, trendy AI devs use varied instruments to help this course of (from CI pipelines to context administration utilities).
Steady testing: Don’t wait till the tip to see if the agent met the spec. After every main milestone and even every operate, run checks or at the least do fast handbook checks. If one thing fails, replace the spec or immediate earlier than continuing. For instance, if the spec stated, “Passwords have to be hashed with bcrypt” and also you see the agent’s code storing plain textual content, cease and proper it (and remind the spec or immediate concerning the rule). Automated checks shine right here: In case you supplied checks (or write them as you go), let the agent run them. In lots of coding agent setups, you possibly can have an agent run npm check or comparable after ending a activity. The outcomes (failures) can then feed again into the following immediate, successfully telling the agent “Your output didn’t meet spec on X, Y, Z—repair it.” This type of agentic loop (code > check > repair > repeat) is extraordinarily highly effective and is how instruments like Claude Code or Copilot Labs are evolving to deal with bigger duties. At all times outline what “carried out” means (through checks or standards) and examine for it.
Iterate on the spec itself: In case you uncover that the spec was incomplete or unclear (perhaps the agent misunderstood one thing otherwise you realized you missed a requirement), replace the spec doc. Then explicitly resync the agent with the brand new spec: “I’ve up to date the spec as follows… Given the up to date spec, alter the plan or refactor the code accordingly.” This manner the spec stays the one supply of fact. It’s much like how we deal with altering necessities in regular dev, however on this case you’re additionally the product supervisor on your AI agent. Maintain model historical past if attainable (even simply through commit messages or notes), so you already know what modified and why.
Make the most of context administration and reminiscence instruments: There’s a rising ecosystem of instruments to assist handle AI agent context and data. As an example, retrieval-augmented technology (RAG) is a sample the place the agent can pull in related chunks of knowledge from a data base (like a vector database) on the fly. In case your spec is big, you could possibly embed sections of it and let the agent retrieve probably the most related components when wanted, as an alternative of all the time offering the entire thing. There are additionally frameworks implementing the Mannequin Context Protocol (MCP), which automates feeding the proper context to the mannequin based mostly on the present activity. One instance is Context7 (context7.com), which might auto-fetch related context snippets from docs based mostly on what you’re engaged on. In apply, this would possibly imply the agent notices you’re engaged on “fee processing” and it pulls the funds part of your spec or documentation into the immediate. Think about leveraging such instruments or organising a rudimentary model (even a easy search in your spec doc).
Parallelize fastidiously: Some builders run a number of agent situations in parallel on completely different duties (as talked about earlier with subagents). This could pace up growth (e.g., one agent generates code whereas one other concurrently writes checks, or two options are constructed concurrently). In case you go this route, make sure the duties are really impartial or clearly separated to keep away from conflicts. (The spec ought to notice any dependencies.) For instance, don’t have two brokers writing to the identical file directly. One workflow is to have an agent generate code and one other overview it in parallel, or to have separate parts constructed that combine later. That is superior utilization and will be mentally taxing to handle. (As Willison admitted, working a number of brokers is surprisingly efficient, if mentally exhausting!) Begin with at most 2–3 brokers to maintain issues manageable.
Model management and spec locks: Use Git or your model management of alternative to trace what the agent does. Good model management habits matter much more with AI help. Commit the spec file itself to the repo. This not solely preserves historical past, however the agent may even use git diff or blame to grasp adjustments. (LLMs are fairly able to studying diffs.) Some superior agent setups let the agent question the VCS historical past to see when one thing was launched—surprisingly, fashions will be “fiercely competent at Git.” By protecting your spec within the repo, you permit each you and the AI to trace evolution. There are instruments (like GitHub Spec Equipment talked about earlier) that combine spec-driven growth into the Git workflow—for example, gating merges on up to date specs or producing checklists from spec objects. When you don’t want these instruments to succeed, the takeaway is to deal with the spec like code: Keep it diligently.
Value and pace issues: Working with massive fashions and lengthy contexts will be sluggish and costly. A sensible tip is to make use of mannequin choice and batching well. Maybe use a less expensive/sooner mannequin for preliminary drafts or repetitions, and reserve probably the most succesful (and costly) mannequin for closing outputs or complicated reasoning. Some builders use GPT-4 or Claude for planning and demanding steps, however offload easier expansions or refactors to an area mannequin or a smaller API mannequin. If utilizing a number of brokers, perhaps not all have to be high tier; a test-running agent or a linter agent might be a smaller mannequin. Additionally take into account throttling context dimension: Don’t feed 20K tokens if 5K will do. As we mentioned, extra tokens can imply diminishing returns.
Monitor and log all the things: In complicated agent workflows, logging the agent’s actions and outputs is crucial. Test the logs to see if the agent is deviating or encountering errors. Many frameworks present hint logs or permit printing the agent’s chain of thought (particularly if you happen to immediate it to assume step-by-step). Reviewing these logs can spotlight the place the spec or directions might need been misinterpreted. It’s not not like debugging a program—besides the “program” is the dialog/immediate chain. If one thing bizarre occurs, return to the spec/directions to see if there was ambiguity.
Study and enhance: Lastly, deal with every venture as a studying alternative to refine your spec-writing talent. Perhaps you’ll uncover {that a} sure phrasing persistently confuses the AI, or that organizing spec sections in a sure approach yields higher adherence. Incorporate these classes into the following spec. The sector of AI brokers is quickly evolving, so new greatest practices (and instruments) emerge continually. Keep up to date through blogs (like those by Simon Willison, Andrej Karpathy, and many others.), and don’t hesitate to experiment.
A spec for an AI agent isn’t “write as soon as, carried out.” It’s a part of a steady cycle of instructing, verifying, and refining. The payoff for this diligence is substantial: By catching points early and protecting the agent aligned, you keep away from pricey rewrites or failures later. As one AI engineer quipped, utilizing these practices can really feel like having “a military of interns” working for you, however you need to handle them properly. spec, repeatedly maintained, is your administration device.
Keep away from Widespread Pitfalls
Earlier than wrapping up, it’s price calling out antipatterns that may derail even well-intentioned spec-driven workflows. The GitHub examine of two,500+ agent information revealed a stark divide: “Most agent information fail as a result of they’re too obscure.” Listed below are the errors to keep away from:
Imprecise prompts: “Construct me one thing cool” or “Make it work higher” offers the agent nothing to anchor on. As Baptiste Studer places it: “Imprecise prompts imply fallacious outcomes.” Be particular about inputs, outputs, and constraints. “You’re a useful coding assistant” doesn’t work. “You’re a check engineer who writes checks for React parts, follows these examples, and by no means modifies supply code” does.
Overlong contexts with out summarization: Dumping 50 pages of documentation right into a immediate and hoping the mannequin figures it out not often works. Use hierarchical summaries (as mentioned in precept 3) or RAG to floor solely what’s related. Context size will not be an alternative choice to context high quality.
Skipping human overview: Willison has a private rule—“I received’t commit code I couldn’t clarify to another person.” Simply because the agent produced one thing that passes checks doesn’t imply it’s right, safe, or maintainable. At all times overview vital code paths. The “home of playing cards” metaphor applies: AI-generated code can look stable however collapse beneath edge circumstances you didn’t check.
Conflating vibe coding with manufacturing engineering: Fast prototyping with AI (“vibe coding”) is nice for exploration and throwaway tasks. However transport that code to manufacturing with out rigorous specs, checks, and overview is asking for hassle. I distinguish “vibe coding” from “AI-assisted engineering”—the latter requires the self-discipline this information describes. Know which mode you’re in.
Ignoring the “deadly trifecta”: Willison warns of three properties that make AI brokers harmful: pace (they work sooner than you possibly can overview), nondeterminism (identical enter, completely different outputs), and value (encouraging nook chopping on verification). Your spec and overview course of should account for all three. Don’t let pace outpace your skill to confirm.
Lacking the six core areas: In case your spec doesn’t cowl instructions, testing, venture construction, code type, git workflow, and bounds, you’re doubtless lacking one thing the agent wants. Use the six-area guidelines from part 2 as a sanity examine earlier than handing off to the agent.
Conclusion
Writing an efficient spec for AI coding brokers requires stable software program engineering ideas mixed with adaptation to LLM quirks. Begin with readability of function and let the AI assist increase the plan. Construction the spec like a critical design doc, masking the six core areas and integrating it into your toolchain so it turns into an executable artifact, not simply prose. Maintain the agent’s focus tight by feeding it one piece of the puzzle at a time (and take into account intelligent techniques like abstract TOCs, subagents, or parallel orchestration to deal with huge specs). Anticipate pitfalls by together with three-tier boundaries (all the time/ask first/by no means), self-checks, and conformance checks—primarily, train the AI the right way to not fail. And deal with the entire course of as iterative: use checks and suggestions to refine each the spec and the code repeatedly.
Observe these pointers and your AI agent will likely be far much less prone to “break down” beneath massive contexts or wander away into nonsense.
Blissful spec-writing!
| On March 26, be part of Addy and Tim O’Reilly at AI Codecon: Software program Craftsmanship within the Age of AI, the place an all-star lineup of consultants will go deeper into orchestration, agent coordination, and the brand new abilities builders have to construct wonderful software program that creates worth for all individuals. Join free right here. |