
Best practice working with AI coding agents
Practices for working with AI coding agents: research first, a rules file, a roadmap and risk assessment before code, notes kept in the repo, approval for anything hard to undo, and automated checks.
I often see posts and articles scrutinising AI coding abilities and claiming 'vibe coding' is rubbish. I bet their tests missed out on prompting product management guidelines, pre-live checklists and weaving in Agile Test & Learn principles...the typical methods dev teams use to refine code before shipping it.
I use these practices with AI coding agents such as v0, Cursor and Claude Code. The example prompts assume a Next.js and Sanity site like the one built in the beginner guide to a Sanity and Next.js web app, which starts from the Next.js and Sanity template in Vercel's template gallery. The prompts can be adapted to other codebases.
Since the first version of this post I've used an agent every day to build a larger web app, one with a database and paying users. Several of the prompts below come from mistakes made on that build. They apply to a small site too.
1. Research before execution
It helps to ask the AI to research (online) your project before making changes:
Before making any changes, please:
1. Research the frameworks and dependencies in this project
2. Examine the existing Sanity schema structure
3. Review the current component patterns
4. Check how similar features are already implemented
5. Identify any existing utilities or helpers that already solve this problem
Why this matters:
- Prevents reinventing the wheel
- Keeps patterns consistent
- Avoids introducing conflicting dependencies
- Maintains architectural coherence
Example prompt:
I want to add a newsletter subscription form. First, search the codebase to see if we already have form handling patterns, email service integrations, or similar components. Then review our Sanity schemas to understand how we structure content. Only after that, propose an implementation plan.
I've added 2 checks since. The first is versions. An agent's knowledge of a library can be older than the version installed, so I ask it to read the installed version number and the official docs for that version before writing code.
The second is checking that existing code does what its name suggests. I once found a setting that was handed from file to file and ignored by the last one, while the documentation implied it worked.
Before using any library, check the version installed in package.json, read the official docs for that version, and match how the codebase already uses it.
2. Put your setup in a rules file
Provide context about your specific setup, for example:
Our infrastructure:
- Next.js 16 with the App Router (not Pages Router)
- Sanity Studio v6 with Live Preview enabled
- TypeScript in strict mode
- Tailwind CSS with custom design tokens in globals.css
- Server Components by default, Client Components only where necessary
- GROQ queries using defineQuery for type generation
- Monorepo structure: /studio and /nextjs-app
- Deployed on Vercel with ISR (Incremental Static Regeneration)
- Using @portabletext/react for rich text rendering
Why this matters:
- Prevents suggestions that are incompatible with your setup
- The AI uses correct APIs and architectural patterns
- Avoids unintentional changes to rendering strategies
- Maintains performance optimisations
Most agents read a rules file at the start of every session (CLAUDE.md in Claude Code, Project Rules in Cursor and v0). The list above belongs there, with the commands to run and where things live. A long rules file tends to cause irregularities as the project grows. What works better for me is a short file that acts as an index. It points to a notes folder per topic, such as architecture or security, and the agent reads the folder for the area it's working in. The same idea applies to a public website read by an agent, which I cover in Experiential Search.
The wording of the rules matters too. Anthropic's Prompting best practices guide recommends giving the reason behind an instruction and telling the model what to do instead of what not to do. It also suggests softening commands like "CRITICAL: You MUST", which some of its models can apply too widely. Examples need the same care. The guide asks for examples that vary enough that the model doesn't pick up unintended patterns, and in my experience a sample value gets copied word for word. The examples in my rules use placeholders such as [page title].
3. Ask for a roadmap and a risk assessment before any code
Ask for approaches or planning before implementation, for example:
Don't write code yet. Instead:
1. Create a detailed implementation roadmap
2. List all files that need to be created or modified
3. Identify potential risks and breaking changes
4. Suggest testing strategies for each phase
5. Provide rollback procedures if something goes wrong
6. Estimate complexity and time required for each step
Why this matters:
- Allows you to review the approach beforehand
- Highlights potential issues early
- Helps prioritise work
- Establishes clear milestones
Example prompt:
I want to add multi-language support. Don't implement yet.
First, create a roadmap that covers:
- Schema changes required in Sanity
- GROQ query modifications
- URL structure changes
- Component updates
- Metadata and SEO implications
- Impact on existing content
- Migration strategy for current posts
Then wait for my approval before proceeding.
Once a site stores customer data or takes payments, I add a risk assessment:
For each proposed fix, tell me:
- How it could fail, and what else it touches
- Whether it fixes the cause or hides the symptom
- The order to deploy things in (database changes before the code that needs them)
- How to check it worked, and how to roll it back
The deploy-order line is there because of a week of usage data I lost. New code went live before the database change it depended on. Every save failed quietly and nothing looked broken.
4. Keep notes in the repo, including what was rejected
After each implementation, request documentation:
After completing this work, please provide:
1. Summary of changes made
2. New patterns or conventions introduced
3. Potential gotchas or edge cases
4. Performance implications
5. Accessibility considerations
6. Browser compatibility notes
7. Lessons learned for future work
Why this matters:
- Builds shared organisational knowledge
- Helps onboard new team members
- Prevents repeating mistakes
- Documents design decisions
Example format:
## Implementation Notes
**Changes Made:**
- Added `newsletter.ts` schema with email validation
- Created `NewsletterForm.tsx` client component with error handling
- Integrated ConvertKit API via route handler
**New Patterns:**
- Zod-based form validation
- API route template for third-party integrations
- Toast notifications for user feedback
**Gotchas:**
- ConvertKit API requires CORS headers
- Email validation must match client and server
- Rate limiting required to prevent spam
An agent starts each session with no memory of the last one, and notes left in a chat disappear with the chat. I ask for them as Markdown files in a docs folder in the repo.
The most useful file in mine is a decisions log. It lists every approach that was rejected or postponed, with the reason. Without it the agent proposes the same rejected idea every few weeks, and it sounds reasonable every time.
Debugging gets the same treatment. When a test rules a cause out, the result is written down in the same session. I once had to rediscover a negative result 3 days after the test that produced it.
I also ask the notes to say whether each new piece is in use or only prepared for later. Agents like to add options that nothing calls, and a note describing one as working misleads the next session.
5. Keep approval for anything hard to undo
The agent I work with doesn't commit code (save it to the project's history). It runs the checks and leaves the diff, the list of lines it changed, for me to read. Commits, database changes and deployments stay with me. Environment variables (settings such as API keys, stored outside the code) never appear in the code history, so I record each change to them in the repo with the date.
I also ask for any change to stored data to come with its reverse, an add with a remove, so undoing one is an ordinary request. Anything attached to a critical step, such as logging on a checkout, is built so that its failure can't block the step.
Don't commit, deploy or run database changes. Finish the change, run the lint, type check and tests, and leave it for me to review.
6. Ask what was verified and what was assumed
An agent reports a guess and a tested result in the same confident tone. I ask for every summary to end with 2 lists:
End every summary with 2 lists:
- Verified: tests run, docs read, output seen
- Inferred: everything else
If a step was skipped or a test failed, say so.
"The build passes" and "this should work" then read as different statements. I ask the same of any analysis. The agent describes what the evidence shows and names the check that would settle the question. The conclusion stays with me.
7. Turn checklists into automatic checks
Request quality checks before pushing to 'live', for example:
Before this feature is considered complete, create a production-readiness checklist covering:
SEO,
Core Web Vitals,
Mobile Responsiveness,
Accessibility,
Good UX,
Good UI,
Good user journey...
A checklist relies on someone remembering to run it. When the same kind of bug appears a second time, I ask the agent to write a script that catches it, and add the script to the checks that run on every push (lint, type check, tests).
For example, a service I use rejects content over a size limit and reports only the first failure, after a deploy. A small edit pushed an entry over. Fixing it uncovered a second entry over the limit further down the file. A script now measures every entry in a single run.
This is the second time this type of bug has appeared. Write a script that detects it across the whole codebase and fails with a clear message. Then tell me how to add it to the checks that run before a deploy.
The AI collaboration workflow
- Research → Understand the codebase and the installed versions
- Plan → Create a roadmap and risk assessment before coding
- Implement → Follow established patterns
- Verify → Separate what was tested from what was assumed
- Approve → Read the diff before anything is committed or deployed
- Document → Record decisions and rejected approaches in the repo
- Automate → Turn repeated mistakes into checks
- Improve → Refine the rules file for future work
Development teams already work this way, and an agent makes the habits cheaper to keep because it writes the notes and the check scripts itself.
What I can't yet tell is how much of this will still be needed as the models improve. Rules I wrote for a model version have needed softening for the next, so the rules file gets a review whenever the model changes.


