Project Rules and AGENTS.md
Rules turn one-off prompt instructions into defaults every session inherits.
Where Rules Live
| Location | Tool | Scope |
|---|---|---|
.cursor/rules/*.mdc | Cursor | Project-wide or path-specific |
AGENTS.md | Cursor, Claude Code, others | Repo root instructions |
.github/copilot-instructions.md | GitHub Copilot | Copilot Chat in repo |
| User rules in settings | Cursor | All projects (avoid stack-specific details) |
.cursor/skills/*/SKILL.md | Cursor, Claude Code | Task-specific workflows (see Agent Skills) |
Keep project rules in the repo so the team shares the same constraints. Use Agent Skills for repeatable procedures that do not belong in every session's context.
AGENTS.md Template
# Project instructions for AI agents
## Stack
- Next.js 15 App Router, React 19, TypeScript 5.7
- Tailwind CSS 4, Markdoc for content pages
- Static export; trailingSlash: true
## Commands
- npm run lint
- npm test
- npm run build
## Conventions
- Match existing file structure under src/pages/
- Use Markdoc tags from markdoc/tags.js; do not add MDX
- Minimal diffs; do not refactor unrelated code
## Do not modify
- package-lock.json unless adding a dependency I requested
- next.config.js unless the task requires it
- .env files
## Verification
After code changes, run npm run lint and npm test.
Path-Specific Rules (Cursor)
Use frontmatter in .cursor/rules/markdoc.mdc:
---
description: Rules for Markdoc content pages
globs: src/pages/**/*.md
---
- Use YAML frontmatter: title, pageTitle, description, date
- Prefer Markdoc callout and quick-links tags over raw HTML
- Internal links use trailing slashes: /ai/common-mistakes/
What Belongs in Rules vs Prompts
| Rules (persistent) | Prompts (per task) |
|---|---|
| Stack versions | Specific bug or feature |
| Lint/test commands | Files allowed for this edit |
| Naming conventions | Acceptance criteria |
| Protected paths | Deadline or priority |
Team Conventions
For teams using AI heavily:
- PR label —
ai-assistedfor human review prioritization - Required checks — CI must pass; no bypassing for "AI said so"
- Shared mistakes reference — link Common AI Coding Mistakes in CONTRIBUTING.md
- Quarterly rule review — update versions when you upgrade frameworks
Team Rollout
Rolling out shared rules across repos:
Central rules repository
| Approach | Pros | Cons |
|---|---|---|
| Copy AGENTS.md per repo | Simple; repo-specific tweaks | Drift between teams |
| Shared npm package or git submodule | Single source of truth | Update propagation overhead |
| Org template repo | New projects start correct | Legacy repos lag |
Start with a template repo; migrate high-traffic services first.
CODEOWNERS for rules files
# .github/CODEOWNERS
AGENTS.md @platform-team
.cursor/rules/ @platform-team
.github/copilot-instructions.md @platform-team
Rules changes affect every AI session — treat them like CI config.
Review cadence
| Trigger | Action |
|---|---|
| Framework upgrade | Update stack versions in AGENTS.md same PR |
| Repeated AI mistake | Add one line to rules; link to Common Mistakes |
| Quarterly calendar | Platform team reviews all rules repos |
| New hire onboarding | Point to rules + Team AI Policy |
Rollout checklist
- [ ] Publish AGENTS.md template in org docs
- [ ] Add CODEOWNERS on rules paths
- [ ] Enable
ai-assistedPR label org-wide - [ ] Link Verifying AI Output in CONTRIBUTING.md
- [ ] Track rules PRs in platform team standup
References: GitHub CODEOWNERS, Cursor Rules.