{"slug": "write-a-project-rules-file-your-ai-agent-will-actually-follow", "title": "Write a Project Rules File Your AI Agent Will Actually Follow", "summary": "A developer has published a guide and template for writing a project-specific rules file, AGENTS.project.md, that AI coding agents will follow, covering commands, architecture, protected files, approval gates, and testing expectations. The template defines ten sections and establishes a priority order in which universal agent rules yield to project rules, except for safety rules that only an explicit user instruction can override.", "body_md": "A universal rules file tells an agent *how to behave*. It can't tell it *how your project works*: which command runs the tests, where shared helpers live, or which folder it must never touch.\n\nThat's what a project rules file is for. In [UNIVERSAL-AGENTS.md](https://github.com/NTDevLops/UNIVERSAL-AGENTS.md) it's called `AGENTS.project.md`, and this post shows how to write a good one.\n\nSection 23 of the universal rules sets the priority when instructions conflict:\n\n`AGENTS.md`\nSection 34.1 names `AGENTS.project.md` as the home for project rules. So the split is clean:\n\n`AGENTS.project.md` holds everything specific to One exception: the safety rules (Sections 27, 28, 29, and 33) can't be loosened by project rules. Only an explicit instruction from the user can override them.\n\n```\ncp templates/AGENTS.project.template.md AGENTS.project.md\n```\n\nThe template has ten sections. You don't need all of them. Delete what doesn't apply and keep the file short, because agents load it into their context window and every line costs something.\n\nHere is a fictional project, an invoicing API in TypeScript. Adapt it to your stack.\n\n```\n# Project Rules (AGENTS.project.md)\n\n## 1. Project overview\n\n- **Name:** invoice-api\n- **Purpose:** REST API for creating and sending invoices.\n- **Languages / frameworks / runtimes:** TypeScript 5, Node 20, Fastify\n- **Package manager:** pnpm\n- **Repository type:** single project\n\n## 2. Commands\n\n| Task | Command |\n|------|---------|\n| Install dependencies | `pnpm install` |\n| Build | `pnpm build` |\n| Run locally | `pnpm dev` |\n| Run all tests | `pnpm test` |\n| Run a single test | `pnpm vitest run path/to/file.test.ts` |\n| Lint | `pnpm lint` |\n| Type-check | `pnpm tsc --noEmit` |\n\n## 3. Architecture and layout\n\n- **Entry points:** `src/server.ts`\n- **Key directories:** `src/routes` (HTTP only), `src/services` (business logic), `src/db` (queries)\n- **Layering rules:** routes never query the database directly.\n- **Shared utilities live in:** `src/lib`. Search here before writing new helpers.\n\n## 4. Conventions\n\n- **Code style:** enforced by `eslint.config.js`.\n- **Error handling:** throw `AppError` from `src/lib/errors.ts`; never throw plain strings.\n- **Commit message format:** Conventional Commits.\n\n## 5. Protected areas\n\nDo not modify without explicit approval:\n\n- `migrations/`: applied migrations must never be edited.\n\nGenerated files (never edit by hand):\n\n- `src/db/types.generated.ts`: generated by `pnpm db:codegen`.\n\n## 6. Approval required\n\nAsk the user before:\n\n- adding or upgrading dependencies\n- creating or changing a database migration\n- changing anything in `.github/workflows/`\n\n## 7. Documentation to keep in sync\n\n| When this changes | Update this |\n|-------------------|-------------|\n| A route's request or response | `docs/api.md` |\n| An environment variable | `README.md` (Configuration section) |\n\n## 8. Testing expectations\n\n- **Required for:** every bug fix needs a regression test.\n- **Test locations and naming:** next to the source, `*.test.ts`.\n- **Do not run against:** any database other than the local Docker one.\n\n## 9. Environment and secrets\n\n- **Local config:** `.env`, based on `.env.example`.\n- **Never log or print:** API keys, customer emails, card data.\n\n## 10. Known pitfalls\n\n- `pnpm test` is slow on a cold start; run a single test while iterating.\n```\n\n**Commands.** This is the highest-value section. Without it, an agent guesses `npm test` in a pnpm project, or runs the whole suite when one file would do. Exact commands also make the agent's verification report (Section 21) trustworthy.\n\n**Architecture and layering.** Section 5 already tells the agent to reuse existing code before writing new code. Pointing it at `src/lib` tells it *where to look*, so it doesn't write a fourth date-formatting helper.\n\n**Protected areas.** Section 8 says agents must not touch things outside the request. Naming `migrations/` and generated files turns a general principle into a hard boundary.\n\n**Approval required.** Dependencies, migrations, and CI changes are the changes people most regret not reviewing. Listing them means the agent asks first.\n\n**Documentation to keep in sync.** Section 9 requires docs to match the code. A table of \"when X changes, update Y\" lets the agent do it reliably.\n\n**Testing expectations.** This sharpens Section 19, which says to add tests only when asked or when project conventions require them. If your convention is \"every bug fix gets a regression test\", say so here and the agent will follow it.\n\n**Known pitfalls.** One or two lines here can save a lot of wasted runs.\n\nSection 34.2 covers this: the `AGENTS.md` closest to the file being changed takes precedence for that subtree, and any rules it doesn't mention still apply from the universal file. Put a small `AGENTS.md` in each package with its own commands and layout.\n\nIf your tool doesn't read `AGENTS.md` natively, copy the matching file from `adapters/` (Claude Code, Gemini CLI, GitHub Copilot, Cursor). The adapters already tell the tool to read `AGENTS.project.md` as well. Check your tool's docs to confirm the file format it expects.\n\n👉 **[https://github.com/NTDevLops/UNIVERSAL-AGENTS.md](https://github.com/NTDevLops/UNIVERSAL-AGENTS.md)** (MIT licensed)\n\n*What's the one line in your project that you wish every new contributor, human or AI, read first? Share it in the comments.*", "url": "https://wpnews.pro/news/write-a-project-rules-file-your-ai-agent-will-actually-follow", "canonical_source": "https://dev.to/codenamew/write-a-project-rules-file-your-ai-agent-will-actually-follow-4opd", "published_at": "2026-10-07 23:09:10+00:00", "updated_at": "2026-10-07 23:17:00.630259+00:00", "lang": "en", "topics": ["ai-agents", "ai-tools", "developer-tools", "agent-protocols"], "entities": ["TypeScript", "Node", "Fastify", "pnpm", "Vitest"], "also_reported_by": [], "alternates": {"html": "https://wpnews.pro/news/write-a-project-rules-file-your-ai-agent-will-actually-follow", "markdown": "https://wpnews.pro/news/write-a-project-rules-file-your-ai-agent-will-actually-follow.md", "text": "https://wpnews.pro/news/write-a-project-rules-file-your-ai-agent-will-actually-follow.txt", "jsonld": "https://wpnews.pro/news/write-a-project-rules-file-your-ai-agent-will-actually-follow.jsonld"}}