Helping AI make fewer mistakes: prompts, rules files, and checkpoints

When AI makes mistakes, it's usually because it didn't have enough info, the agreements got lost, or nobody checked the changes. The things below prevent most of the rework.

Be clear about this task: prompts

The more specific your Prompt, the closer the result gets to what you expect. Don't say "make a nice-looking list." Name the layout and components directly: "use a data table with a filter bar on top."

• Few-shot Prompting: give the AI a model to copy, like "build ProductList the same way as UserList.tsx," and it'll reuse the same structure and naming.
• Multimodal: models can see images, so you can send screenshots or designs directly (Screenshot to Code), then add text for the interactions the image can't show.
• Iterative Prompting: don't expect to say everything at once. Get a first version, then change only one or two things per round.

Write down long-term agreements: rules files

A System Prompt is the underlying instruction the tool sets for the model ahead of time. A Rules File is something you put in your project, like AGENTS.md or CLAUDE.md, and it's given to the AI automatically in every conversation. Good things to include: the tech stack, component library, folder conventions, things not to do, and the check commands to run after changes. When you notice the AI making the same mistake again and again, write the correction in.

This project uses React + TypeScript. Use shadcn/ui for all components and Tailwind only for styling, and don't add any new UI library. Put new components in src/components, and don't modify the src/api folder. After making changes, run pnpm lint and pnpm build, and only report back once they pass.

Watch out for forgetting and making things up

• Context Window: there's a limit to how much the model can see at once, measured in Tokens. When a conversation gets too long, earlier agreements get pushed out. Use one conversation per task. For long tasks, have the AI write a summary first, then continue in a new conversation.
• Hallucination: AI makes up props, API fields, and package names that don't exist. Give it real material (the exact error text, API samples, related files), and when it's not sure, have it say so.
• For medium to large features, use Spec-Driven Development: have the AI write the requirements, design, and task list first, then build item by item after you approve.

Leave a way back at every step

An AI Agent reads files, edits code, and runs commands on its own, and its changes may reach further than you think.

• Check the Diff: red is deleted, green is added. Make sure only the right things changed.
• Checkpoint: if something breaks, roll back to before this round. It doesn't replace Git, so commit each time you reach a working stage.
• Do Refactoring and new features separately, so problems are easier to track down.
• Put your API Key in an Environment Variable. Don't paste it into code or commit it to the repo.