{"slug": "how-to-stop-cursor-and-claude-code-breaking-your-project-a-free-agents-md", "title": "How to stop Cursor and Claude Code breaking your project: a free AGENTS.md starter", "summary": "A developer published a free, MIT-licensed starter repo, vibe-coding-rules-starter, that gives AI coding agents like Cursor, Claude Code, Copilot and Windsurf a shared AGENTS.md rule file, with CLAUDE.md and .cursor/rules files pointing back to it. The template sets an explicit rule-priority order that puts security guardrails above user requests, and adds concrete prohibitions on destructive commands, dependency installs and scope creep, plus a two-attempt limit on debugging before the agent stops and summarizes options.", "body_md": "If you build with Cursor, Claude Code, Copilot or Windsurf, you've probably had at least one of these happen:\n\n`NEXT_PUBLIC_` prefix where every visitor can read it.\nNone of this is the model being stupid. It's the model doing exactly what it was asked, with no idea what *you* consider off-limits. The fix is cheap: give it a short, clear set of house rules it reads at the start of every session.\n\nMost AI coding tools now read a plain Markdown instructions file from your project:\n\n| Tool | File it reads | \n|---|---|\n| Cursor, Copilot, Windsurf, Codex, Zed, Amp and others | `AGENTS.md` | \n| Cursor (project rules) | `.cursor/rules/*.mdc` | \n| Claude Code | `CLAUDE.md` | \n\n`AGENTS.md` is the closest thing to a shared standard, so it makes sense to put the real rules there and have the other files point at it. That's the setup I'll walk through below. All the files are in a free, MIT-licensed repo: **[vibe-coding-rules-starter](https://github.com/theodorecreatesco/vibe-coding-rules-starter)**.\n\nThe most useful thing you can tell an agent is what to do when instructions clash. Without that, \"just make it work\" quietly beats \"don't commit secrets\". The starter opens with this:\n\n```\n## Rule priority\n\nWhen rules clash, follow the higher one and say which you followed:\n\n1. **Security guardrails** (next section): never broken, even if I ask.\n   Explain the risk in one line and do the safe version.\n2. **The task I asked for**: it's my OK for the changes it clearly needs,\n   within the guardrails. List them under \"Needs your OK\".\n3. **Stack conventions** (the conventions already used in this repo).\n4. **Working style.**\n```\n\n\"Say which you followed\" matters. It turns a silent decision into one you can see in the reply.\n\n\"Write secure code\" does nothing. Rules the agent can act on look like this:\n\n```\n- Public prefixes (`NEXT_PUBLIC_`, `VITE_`, `EXPO_PUBLIC_`, `PUBLIC_`) ship values\n  to every user: never put a secret behind one. Work that needs a secret moves\n  to a server or edge function.\n- Anything touching private data checks the caller (401 if unknown) and that they\n  may touch this record (404 if missing or not theirs; 403 if they lack the role).\n  Hiding a button isn't security.\n- Admin features need sign-in plus a role stored in the database and checked on\n  the server, never a client flag or hard-coded emails or IDs.\n```\n\nThe second rule is the one that prevents the most common hole in AI-built apps: an endpoint that checks you're logged in but not that the record is *yours*. Change the ID in the URL and you're reading someone else's data.\n\nIt also helps to list the things the agent must never do on its own:\n\n```\nNever, in any mode, unless I ask for that exact action\n- Destructive commands (`rm -rf`, `git reset --hard`, `git push --force`, dropping\n  tables, database resets), changing a remote or production database, or disabling,\n  skipping or loosening tests, lint rules or type checks to get a pass.\n- Installing new dependencies without my OK. Check a package's exact name before\n  installing (typo-squats are common).\n```\n\nMost \"the AI broke my project\" stories are scope problems, not security ones. These lines do most of the work:\n\n```\n- Stay in scope: don't rename, reformat or tidy unrelated code.\n- Make the smallest change; never rewrite a working file wholesale.\n- Never invent APIs, packages or file paths. Check the installed version's docs.\n- Debugging: reproduce, read the full error, state the likely cause, make the\n  smallest fix. After two failed attempts, stop and summarise the next two options.\n```\n\nThe two-attempt limit is what stops the debugging spiral. Instead of a sixth guess, you get a summary and a choice.\n\nFor anything bigger than two files, the agent writes a short plan first and waits for your OK. If it's running as a background agent and can't ask, it puts the plan at the top of its summary instead of stalling.\n\nFinally, tell the agent what \"done\" looks like:\n\n```\nReply with: 1) what changed, 2) the files changed, 3) the commands you ran and\ntheir results, 4) how I can test it, 5) \"Needs your OK\": anything I should\nconfirm, plus anything risky or unfinished.\n```\n\nPoint 3 is the important one. \"I ran `npm test`, 41 passed, lint couldn't run because…\" is something you can trust. \"Everything should work now\" isn't.\n\n**Cursor.** `AGENTS.md` is picked up automatically, but a project rule with `alwaysApply: true` makes sure the security section is in every chat, even if `AGENTS.md` gets cut short:\n\n```\n---\ndescription: Rule priority and security guardrails that apply to every task\nalwaysApply: true\n---\n```\n\n**Claude Code.** `CLAUDE.md` can import another file with `@`, so it stays short and repeats only the security essentials as a backup:\n\n```\n@AGENTS.md\n\nAGENTS.md (imported above) holds the full project rules. This file repeats the\nessentials so they still apply if AGENTS.md is missing or cut short; if they\never differ, the security rules here win.\n```\n\nFrom the root of your project:\n\n```\ngit clone --depth 1 https://github.com/theodorecreatesco/vibe-coding-rules-starter.git /tmp/vcrs\ncp /tmp/vcrs/AGENTS.md /tmp/vcrs/CLAUDE.md .\nmkdir -p .cursor/rules && cp /tmp/vcrs/.cursor/rules/security.mdc .cursor/rules/\n```\n\nAlready have an `AGENTS.md` or `CLAUDE.md`? Don't overwrite it. Paste the block between the `BEGIN` and `END` markers at the top of yours.\n\n**Check it worked:** start a new chat and ask *\"What are the top rules in this project?\"* It should mention the rule priority and the security guardrails. If it doesn't, the file isn't being loaded. Check it's in the project root, and for Cursor, that the `.cursor` folder (hidden by default) was copied.\n\nRules reduce mistakes, they don't guarantee anything. The repo also includes a 10-point checklist to run before you share a link. A few of the checks:\n\n```\n- [ ] `.env` and `.env.*` are listed in `.gitignore` (and `.env.example` holds names only).\n      Check: `git check-ignore -q .env.local` should exit with code 0.\n- [ ] Every API route, server action and edge function checks the user is logged in\n- [ ] Every one also checks the user owns (or may access) the record\n- [ ] Spending limits or alerts are set on paid APIs (OpenAI, Anthropic, etc.) and hosting\n```\n\nThere's also a copy-paste \"secret scan\" prompt that gets your agent to check the repo (and git history, if it can) for keys, without printing the values.\n\nYou don't need a huge rules file. A clear priority order, specific security rules, a scope limit and a \"show me what you ran\" report fix most of the damage AI coding tools do. Grab the files from **[vibe-coding-rules-starter](https://github.com/theodorecreatesco/vibe-coding-rules-starter)**, and if you improve on them, issues and PRs are welcome.\n\nIf you want versions tuned for a specific stack (Next.js + Supabase, Lovable, Bolt, FastAPI, Expo and others) with a one-command installer, I also sell a [full Vibe Coding Rules Kit](https://www.etsy.com/uk/listing/4601953941). The free starter works fine on its own.\n\n*Whatever rules you use, review AI-written code, especially anything touching auth, payments or personal data.*", "url": "https://wpnews.pro/news/how-to-stop-cursor-and-claude-code-breaking-your-project-a-free-agents-md", "canonical_source": "https://dev.to/theodorecreatesco/how-to-stop-cursor-and-claude-code-breaking-your-project-a-free-agentsmd-starter-2273", "published_at": "2026-10-31 18:49:50+00:00", "updated_at": "2026-10-31 18:52:19.367944+00:00", "lang": "en", "topics": ["ai-tools", "ai-agents", "developer-tools", "ai-products"], "entities": ["Cursor", "Claude Code", "GitHub Copilot", "Windsurf", "vibe-coding-rules-starter"], "also_reported_by": [], "alternates": {"html": "https://wpnews.pro/news/how-to-stop-cursor-and-claude-code-breaking-your-project-a-free-agents-md", "markdown": "https://wpnews.pro/news/how-to-stop-cursor-and-claude-code-breaking-your-project-a-free-agents-md.md", "text": "https://wpnews.pro/news/how-to-stop-cursor-and-claude-code-breaking-your-project-a-free-agents-md.txt", "jsonld": "https://wpnews.pro/news/how-to-stop-cursor-and-claude-code-breaking-your-project-a-free-agents-md.jsonld"}}