[{"data":1,"prerenderedAt":4},["ShallowReactive",2],{"post-content-ai-coding-assistant-rules-guide":3},"\u003Cp>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 \u003Cem>three hours\u003C\u002Fem> fixing the bugs it introduced.\u003C\u002Fp>\n\n\u003Cp>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.\u003C\u002Fp>\n\n\u003Cp>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 \u003Cem>less\u003C\u002Fem> productive.\u003C\u002Fp>\n\n\u003Cp>Then I realized something: the problem wasn't the AI. It was me. I wasn't giving it guardrails.\u003C\u002Fp>\n\n\u003Ch2>What's an AGENTS.md (and Why Should You Care)?\u003C\u002Fh2>\n\n\u003Cp>If you've used Cursor, Claude Code, or GitHub Copilot lately, you've probably noticed a new file cropping up in projects — \u003Ccode>AGENTS.md\u003C\u002Fcode>, \u003Ccode>CLAUDE.md\u003C\u002Fcode>, \u003Ccode>.cursorrules\u003C\u002Fcode>, or \u003Ccode>COPILOT_INSTRUCTIONS.md\u003C\u002Fcode>. Different names, same idea: a plain-text file that tells your AI coding assistant how to behave in your project.\u003C\u002Fp>\n\n\u003Cp>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.\u003C\u002Fp>\n\n\u003Cp>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.\u003C\u002Fp>\n\n\u003Cp>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.\u003C\u002Fp>\n\n\u003Ch2>The 4 Things Every Rules File Needs\u003C\u002Fh2>\n\n\u003Cp>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:\u003C\u002Fp>\n\n\u003Ch3>1. Identity and Hard Constraints\u003C\u002Fh3>\n\n\u003Cp>Tell the AI who it is and what it's \u003Cem>not\u003C\u002Fem> 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.\"\u003C\u002Fp>\n\n\u003Cp>My opening block looks like this:\u003C\u002Fp>\n\n\u003Cpre>\u003Ccode class=\"language-plaintext\">You are an experienced developer working on this project.\n- Do NOT add new dependencies without asking first\n- Do NOT create files outside the specified directories\n- Do NOT rewrite existing working code \"just because\"\n- Always check existing patterns before writing new code\n- If something feels off, say so instead of silently fixing it\u003C\u002Fcode>\u003C\u002Fpre>\n\n\u003Cp>That last one is critical. You want the AI to flag concerns, not hide them behind \"improved\" code that breaks something else.\u003C\u002Fp>\n\n\u003Ch3>2. Tech Stack and Conventions\u003C\u002Fh3>\n\n\u003Cp>Be painfully specific. \"We use React\" isn't enough — the AI needs to know \u003Cem>which\u003C\u002Fem> React. Hooks or classes? App Router or Pages Router? Tailwind or CSS modules?\u003C\u002Fp>\n\n\u003Cp>Here's what I include:\u003C\u002Fp>\n\n\u003Cpre>\u003Ccode class=\"language-plaintext\">Tech Stack:\n- React 18 with TypeScript (strict mode)\n- Next.js 14 (App Router, NOT Pages Router)\n- Tailwind CSS for styling (no CSS modules, no styled-components)\n- Zustand for state management (no Redux, no Context for global state)\n- Vitest for testing (not Jest, not Mocha)\u003C\u002Fcode>\u003C\u002Fpre>\n\n\u003Cp>Notice the negative constraints. \"NOT Pages Router.\" \"no Redux.\" The AI needs to know what \u003Cem>not\u003C\u002Fem> 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.\u003C\u002Fp>\n\n\u003Ch3>3. Patterns and Anti-Patterns\u003C\u002Fh3>\n\n\u003Cp>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.\u003C\u002Fp>\n\n\u003Cpre>\u003Ccode class=\"language-plaintext\">File Structure:\n- Reusable components → \u002Fcomponents\u002Fui\u002F\n- Page-specific components → \u002Fcomponents\u002Ffeature\u002F\n- Hooks → \u002Fhooks\u002F, one file per hook\n- Types → \u002Ftypes\u002F, grouped by domain (auth.types.ts, billing.types.ts)\n\nNaming:\n- React components: PascalCase, descriptive (UserProfile, not Profile)\n- Hooks: camelCase, prefixed with \"use\" (useAuth, not AuthHook)\n- Event handlers: handle{Action} (handleSubmit, not onSubmit)\n\nError Handling:\n- Use the shared ErrorBoundary component for all route segments\n- Log errors to Sentry, not console.error\n- Show user-friendly toast messages, not raw error objects\u003C\u002Fcode>\u003C\u002Fpre>\n\n\u003Ch3>4. Communication Style\u003C\u002Fh3>\n\n\u003Cp>This one surprised me. Telling the AI \u003Cem>how\u003C\u002Fem> to talk to me dramatically improved output quality.\u003C\u002Fp>\n\n\u003Cpre>\u003Ccode class=\"language-plaintext\">- For simple changes: just show the code, skip the explanation\n- For complex changes: explain your approach first, then show the code\n- If you spot a potential bug: flag it with \"⚠️ Concern:\" prefix\n- When refactoring: show the diff and explain what changed and why\u003C\u002Fcode>\u003C\u002Fpre>\n\n\u003Cp>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).\u003C\u002Fp>\n\n\u003Ch2>What My Full Rules File Looks Like\u003C\u002Fh2>\n\n\u003Cp>Here's the complete \u003Ccode>AGENTS.md\u003C\u002Fcode> I use for the Next.js project I'm building right now. About 60 lines, committed to the repo root:\u003C\u002Fp>\n\n\u003Cpre>\u003Ccode class=\"language-plaintext\"># Project Rules\n\nYou are a senior TypeScript engineer working on a Next.js SaaS app.\n\n## Constraints\n- Do NOT add new dependencies unless explicitly asked\n- Do NOT modify files outside the scope of the task\n- Do NOT refactor working code \"while you're at it\"\n- Flag concerns with \"⚠️\" prefix\n\n## Stack\n- Next.js 14 (App Router) + React 18 + TypeScript strict\n- Tailwind CSS (no CSS modules, no styled-components)\n- Zustand for global state (no Redux, no Context for state)\n- Prisma + PostgreSQL (no raw SQL in components)\n- Vitest + Testing Library (no Jest)\n\n## Patterns\n- Server Components by default; client-side interactivity via \"use client\"\n- Route handlers in \u002Fapp\u002Fapi\u002F with proper error boundaries\n- One Service file per domain (auth.service.ts, billing.service.ts)\n- Validation with Zod, never trust raw request data\n\n## Style\n- Named exports only (no default exports)\n- Async\u002Fawait, no raw promises or callbacks\n- Early returns, avoid deep nesting\n- Descriptive variable names, no abbreviations\n\n## Output\n- Simple changes → code only, no commentary\n- Complex changes → explain approach, then show code\n- Diffs should be minimal — if you're changing 50 lines, explain why\u003C\u002Fcode>\u003C\u002Fpre>\n\n\u003Cp>That's it. The AI reads this file automatically at the start of every session — most tools pick up \u003Ccode>AGENTS.md\u003C\u002Fcode> or \u003Ccode>CLAUDE.md\u003C\u002Fcode> from the working directory without any special configuration.\u003C\u002Fp>\n\n\u003Ch2>The 3 Mistakes I Made\u003C\u002Fh2>\n\n\u003Cp>Let me save you some pain. Here's what went wrong so you don't have to repeat it:\u003C\u002Fp>\n\n\u003Ch3>Mistake 1: Being Too Vague\u003C\u002Fh3>\n\u003Cp>\"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 \u003Cem>your\u003C\u002Fem> project — named exports, single responsibility, no unused imports. Concrete over abstract, every time.\u003C\u002Fp>\n\n\u003Ch3>Mistake 2: Writing a Novel\u003C\u002Fh3>\n\u003Cp>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.\u003C\u002Fp>\n\n\u003Ch3>Mistake 3: Treating It as Set-and-Forget\u003C\u002Fh3>\n\u003Cp>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.\u003C\u002Fp>\n\n\u003Ch2>Keep Your Rules in a Snippet Library\u003C\u002Fh2>\n\n\u003Cp>Here's the thing about these rules files — they're portable. I have different flavors for different project types. A React\u002FNext.js SaaS gets one set of rules. A Node.js API server gets another. A fresh side project uses a stripped-down version.\u003C\u002Fp>\n\n\u003Cp>This is where \u003Ca href=\"https:\u002F\u002Fdevspera.com\u002Fsnippetark\u002F\">Snippet Ark\u003C\u002Fa> 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.\u003C\u002Fp>\n\n\u003Cp>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.\u003C\u002Fp>\n\n\u003Cp>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.\u003C\u002Fp>\n\n\u003Ch2>Start Today, Keep It Simple\u003C\u002Fh2>\n\n\u003Cp>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 \u003Cem>your\u003C\u002Fem> specific project, your specific stack, your specific conventions.\u003C\u002Fp>\n\n\u003Cp>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.\u003C\u002Fp>\n\n\u003Cp>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.\u003C\u002Fp>\n\n\u003Cp>Your future self — the one who won't spend three hours debugging a file uploader the AI over-engineered — will thank you.\u003C\u002Fp>\n\n\u003Cp>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, \u003Ca href=\"https:\u002F\u002Fdevspera.com\u002Fsnippetark\u002F\">give Snippet Ark a try\u003C\u002Fa> — it might change how you work with AI too.\u003C\u002Fp>\n",1789366677488]