Context
Rules
Persistent, version-controlled instructions that steer every AI request — your conventions, encoded once and applied to every prompt.
Why rules
Models don’t remember your house style between sessions. Rules fix that: a short, reusable block of guidance that’s prepended to agent and chat requests so the AI follows your conventions without being told every time.
The three levels
- Project rules — a
.goatfiedrulesfile (orAGENTS.md) in the repo root. Checked into git and shared with everyone on the project. This is the right home for anything specific to the codebase. - User rules — your personal, global preferences, set in Settings → Rules. They follow you across every project on your machine (for example, “explain your reasoning before large changes”).
- Team rules — pushed from platform.goatfied.com and applied across every repo in the org, so standards are consistent without copy-pasting a file into each project.
Project rule files
Project rules live as .mdc files under .goatfied/rules/ (an existing .cursor/rules/ directory is read too, so rules carry over unchanged). Each file is a Markdown body with optional YAML frontmatter that controls when the rule applies:
--- description: API route conventions for this service globs: src/app/api/**/*.ts alwaysApply: false --- - Validate every request body with zod at the boundary. - Return NextResponse.json — never a bare Response. - Auth check first; 401 before any DB access.
The filename is the rule’s name: a file at .goatfied/rules/api.mdc can be pulled into any prompt on demand with @api.
Application modes
A rule’s frontmatter determines how it’s applied. There are four modes:
| Mode | Frontmatter | When it’s included |
|---|---|---|
| Always | alwaysApply: true | In context on every request. |
| Auto Attached | globs: set | When a file matching the globs is open or @-mentioned. |
| Agent Requested | description: only | Pulled in when the prompt is relevant to the description. |
| Manual | none of the above | Only when invoked explicitly with @rule-name. |
Globs
globs is a comma-separated list of path patterns. They use standard glob syntax:
| Pattern | Matches |
|---|---|
*.ts | any TypeScript file (by name) |
src/**/*.tsx | every .tsx under src, at any depth |
src/{lib,utils}/*.ts | files directly in src/lib or src/utils |
**/*.test.ts | test files anywhere in the repo |
Manual invocation
Any rule — whatever its mode — can be forced into a single prompt by referencing it with @rule-name (the filename without .mdc). Handy for a one-off: @migrations write the up/down for this change.
Precedence
When more than one rule applies, they layer in this order, with later levels refining earlier ones:
Team rules → org-wide baseline (platform.goatfied.com) Project rules → repo conventions (.goatfied/rules/*.mdc, .goatfiedrules, AGENTS.md) User rules → your personal preferences (Settings → Rules)
Nothing is silently overwritten — the model sees all applicable rules and treats the more specific level as the tie-breaker.
AGENTS.md
Goatfied reads the open AGENTS.md standard, so a single file documents your project for Goatfied and other agent tools alike. If both .goatfiedrules and AGENTS.md are present, both are applied.
What makes a good rule
- Be specific and actionable. “Use
async/await, never.then()” beats “write clean code.” - State the version you target. “Next.js 15 App Router, React 19, Tailwind 4.”
- Call out what to avoid. Forbidden imports, deprecated APIs, files the agent shouldn’t touch.
- Keep it tight. A focused page of rules steers better than a sprawling style guide — long rules dilute attention.
- Point to examples. Reference a canonical file ( “match the structure of
src/lib/api.ts”) rather than re-describing it.
Coming from another editor
Goatfied also reads an existing .cursorrules file, so rules carry over with no changes. See Migrating.