Your AI Coding Assistant Needs Rules (And How to Write Them)

I spent last Tuesday doing something deeply stupid. I asked an AI to refactor a React component, spent 20 minutes reviewing its output, approved it, and then spent the next three hours fixing the bugs it introduced.

The component was supposed to be simple — a file uploader with drag-and-drop, progress tracking, and error handling. What I got back was a mess: unnecessary abstractions, wrong import paths, and a custom hook that solved a problem I didn't have. The AI had decided my straightforward component needed a state machine, three context providers, and a utility file referencing packages I wasn't even using.

This kept happening. Every single day. I'd prompt, review, catch some mistakes, miss others, and pay for it later. Some days I genuinely wondered if AI coding assistants were making me less productive.

Then I realized something: the problem wasn't the AI. It was me. I wasn't giving it guardrails.

What's an AGENTS.md (and Why Should You Care)?

If you've used Cursor, Claude Code, or GitHub Copilot lately, you've probably noticed a new file cropping up in projects — AGENTS.md, CLAUDE.md, .cursorrules, or COPILOT_INSTRUCTIONS.md. Different names, same idea: a plain-text file that tells your AI coding assistant how to behave in your project.

Think of it as a README for your machine co-worker. Except instead of explaining the project to humans, it spells out conventions, patterns, and hard constraints for the thing generating your code.

The concept isn't new — early adopters were writing custom system prompts for Copilot back in 2023. But in 2026, almost every major AI coding tool supports some form of project-level rules. And the difference between a project with good rules and one without is night and day.

I've been running an experiment for the past month: every new feature and refactor goes through my rules-guided AI. The result? My code review time dropped by about 60%, and the "oops, that's wrong" fixes went from multiple per session to maybe one or two a week.

The 4 Things Every Rules File Needs

After a month of trial, error, and way too many deleted files, I've landed on a structure that works. Here are the four sections I include in every rules file:

1. Identity and Hard Constraints

Tell the AI who it is and what it's not allowed to do. This sounds basic, but you'd be amazed how much garbage you can prevent with a single line like "You are a senior React engineer. Do not add dependencies unless explicitly instructed."

My opening block looks like this:

You are an experienced developer working on this project.
- Do NOT add new dependencies without asking first
- Do NOT create files outside the specified directories
- Do NOT rewrite existing working code "just because"
- Always check existing patterns before writing new code
- If something feels off, say so instead of silently fixing it

That last one is critical. You want the AI to flag concerns, not hide them behind "improved" code that breaks something else.

2. Tech Stack and Conventions

Be painfully specific. "We use React" isn't enough — the AI needs to know which React. Hooks or classes? App Router or Pages Router? Tailwind or CSS modules?

Here's what I include:

Tech Stack:
- React 18 with TypeScript (strict mode)
- Next.js 14 (App Router, NOT Pages Router)
- Tailwind CSS for styling (no CSS modules, no styled-components)
- Zustand for state management (no Redux, no Context for global state)
- Vitest for testing (not Jest, not Mocha)

Notice the negative constraints. "NOT Pages Router." "no Redux." The AI needs to know what not to reach for, not just what to use. Without these, it'll default to whatever was most common in its training data — which might be years out of date for your stack.

3. Patterns and Anti-Patterns

Every project has unwritten rules — how you structure files, name components, handle errors, write tests. Put them in writing or the AI will invent its own.

File Structure:
- Reusable components → /components/ui/
- Page-specific components → /components/feature/
- Hooks → /hooks/, one file per hook
- Types → /types/, grouped by domain (auth.types.ts, billing.types.ts)

Naming:
- React components: PascalCase, descriptive (UserProfile, not Profile)
- Hooks: camelCase, prefixed with "use" (useAuth, not AuthHook)
- Event handlers: handle{Action} (handleSubmit, not onSubmit)

Error Handling:
- Use the shared ErrorBoundary component for all route segments
- Log errors to Sentry, not console.error
- Show user-friendly toast messages, not raw error objects

4. Communication Style

This one surprised me. Telling the AI how to talk to me dramatically improved output quality.

- For simple changes: just show the code, skip the explanation
- For complex changes: explain your approach first, then show the code
- If you spot a potential bug: flag it with "⚠️ Concern:" prefix
- When refactoring: show the diff and explain what changed and why

Without this, the AI either over-explains every line (wasting your time) or silently changes things you didn't ask for (wasting even more time later).

What My Full Rules File Looks Like

Here's the complete AGENTS.md I use for the Next.js project I'm building right now. About 60 lines, committed to the repo root:

# Project Rules

You are a senior TypeScript engineer working on a Next.js SaaS app.

## Constraints
- Do NOT add new dependencies unless explicitly asked
- Do NOT modify files outside the scope of the task
- Do NOT refactor working code "while you're at it"
- Flag concerns with "⚠️" prefix

## Stack
- Next.js 14 (App Router) + React 18 + TypeScript strict
- Tailwind CSS (no CSS modules, no styled-components)
- Zustand for global state (no Redux, no Context for state)
- Prisma + PostgreSQL (no raw SQL in components)
- Vitest + Testing Library (no Jest)

## Patterns
- Server Components by default; client-side interactivity via "use client"
- Route handlers in /app/api/ with proper error boundaries
- One Service file per domain (auth.service.ts, billing.service.ts)
- Validation with Zod, never trust raw request data

## Style
- Named exports only (no default exports)
- Async/await, no raw promises or callbacks
- Early returns, avoid deep nesting
- Descriptive variable names, no abbreviations

## Output
- Simple changes → code only, no commentary
- Complex changes → explain approach, then show code
- Diffs should be minimal — if you're changing 50 lines, explain why

That's it. The AI reads this file automatically at the start of every session — most tools pick up AGENTS.md or CLAUDE.md from the working directory without any special configuration.

The 3 Mistakes I Made

Let me save you some pain. Here's what went wrong so you don't have to repeat it:

Mistake 1: Being Too Vague

"Write clean code" is worse than useless. The AI genuinely believes its code is always clean. You have to tell it specifically what "clean" means in your project — named exports, single responsibility, no unused imports. Concrete over abstract, every time.

Mistake 2: Writing a Novel

My first rules file was over 200 lines. The AI ignored most of it. Keep it under 80 lines. Prioritize rules that actually prevent mistakes — your tech stack, file structure, and naming conventions. Everything else is noise that dilutes the signal.

Mistake 3: Treating It as Set-and-Forget

Your rules file is a living document. When the AI generates something wrong in a new way, add a rule for it. The first week I was editing mine daily. Now it changes maybe once a week. That's not failure — that's the system working.

Keep Your Rules in a Snippet Library

Here's the thing about these rules files — they're portable. I have different flavors for different project types. A React/Next.js SaaS gets one set of rules. A Node.js API server gets another. A fresh side project uses a stripped-down version.

This is where Snippet Ark becomes part of my AI workflow. I keep all my rules templates there — each project type has its own snippet with the base rules, tech stack boilerplate, and conventions. When I spin up a new project, I grab the template, customize it, and drop it in the root. Takes about 90 seconds.

Before Snippet Ark, I had these scattered across random text files in some "templates" folder I could never find when I needed them. Now they're organized by project type, searchable, and synced across my machines. And since Snippet Ark is local-first, my rules stay private — no cloud dependency for something as sensitive as my development workflow.

I also store useful prompt patterns there. When I discover a phrasing that works particularly well for getting the AI to generate good tests or handle edge cases correctly, it goes into Snippet Ark. Over time I've built a small library of "prompt recipes" that save me tons of time.

Start Today, Keep It Simple

AI coding assistants are incredible tools. But they're not mind readers. Without rules, they default to whatever their training data says is "most likely" — which is often wrong for your specific project, your specific stack, your specific conventions.

A 60-line rules file turned my AI coding experience from "fix more than I write" to "review less than I generate." That's a trade I'll take every single time.

Start simple. Write down the five things your AI keeps getting wrong, and turn those into rules. Add the non-negotiable constraints. Commit the file. Then iterate as you find new pain points.

Your future self — the one who won't spend three hours debugging a file uploader the AI over-engineered — will thank you.

What's the first rule you'd put in your AGENTS.md? I'm genuinely curious. And if you want a place to keep all your rules organized, give Snippet Ark a try — it might change how you work with AI too.