Rules, Skills & Project Context

AI configuration is code — version it

The biggest team-level mistake: every engineer re-invents context every session. Prompts in chat history, conventions in someone's head, deployment steps in Slack. Shared AI configuration in git solves this.

Rules: always-on conventions

Cursor rules (.cursor/rules/) are markdown files injected into every agent/ask session:

.cursor/rules/ ├── coding-standards.mdc # Language conventions, lint rules ├── testing-patterns.mdc # How we write tests ├── api-design.mdc # REST conventions, error formats └── security.mdc # No secrets in prompts, input validation

AGENTS.md (repo root): high-level project context — architecture, key abstractions, gotchas. Cursor reads this automatically.

Rule type	Scope	Example
Project rules	This repo, committed to git	"Use Jest, not Mocha"
Team rules	Org-wide via Cursor dashboard	"Never commit API keys"
User rules	Individual preferences	"Prefer concise responses"

Project and team rules are the ones that matter for consistency. User rules are personal preference.

Skills: on-demand procedures

Skills (SKILL.md) are loaded when relevant — procedural knowledge too long for a rule:

.cursor/skills/ ├── deploy/SKILL.md # How to deploy this service ├── run-migrations/SKILL.md # Database migration procedure └── incident-response/SKILL.md

A skill tells the agent how to do something step by step. A rule tells it how to write code. Both belong in git, reviewed in PRs, updated when processes change.

Project context files

Beyond rules and skills, maintain:

File	Purpose	Audience
AGENTS.md	Architecture overview, key files, conventions	AI agents
llm-context.md / context.md	Deep project context (Netflix pattern)	AI + new engineers
README.md	Human onboarding	Engineers
ADRs (docs/adr/)	Decision history	AI + engineers

Don't duplicate content. AGENTS.md links to ADRs; rules reference testing patterns rather than repeating them.

Versioning and review

AI configuration changes should go through the same PR process as code:

Engineer updates rule → PR → Teammate reviews → Merge → All agents pick it up

This means:

• Rules are reviewed like code (catch wrong conventions before they spread)
• Rules are attributed (git blame shows who added "always use lodash")
• Rules are revertable (bad rule? revert the commit)
• Rules survive model upgrades (prompts in chat history don't)

What to put in rules vs skills vs context

Content	Where	Why
"Use TypeScript strict mode"	Rule	Always applies
"Run npm run deploy:staging then verify"	Skill	Procedural, on-demand
"This service uses event sourcing"	AGENTS.md	Architectural context
"We chose Redis over Memcached because..."	ADR	Decision history
"Prefer early returns over nested ifs"	Rule	Style convention

Team onboarding with AI config

New engineer + good AI config = productive day one:

1. Clone repo (rules, skills, AGENTS.md included)
2. Open in Cursor (indexing starts)
3. Ask agent "explain the architecture" (reads AGENTS.md + codebase)
4. Agent follows team conventions automatically (rules)
5. Agent knows deployment procedure (skills)

The AI config is part of onboarding documentation. Keep it current or it actively misleads.

Anti-patterns

Anti-pattern	Fix
Rules file > 200 lines	Split into focused rules
Rules contradict each other	Review and deduplicate
Stale skills (deploy steps changed)	Treat skills like runbooks — update on process change
Rules only in one engineer's head	Write them down in git
Copy-pasting rules between repos	Extract shared team rules to org level

Interview framing

"I treat AI configuration as code: rules for conventions, skills for procedures, AGENTS.md for architecture context — all in git, reviewed in PRs. This gives every engineer (and agent) consistent context that survives model upgrades and onboarding."

Senior signal: Show your repo's rule/skill structure. Explain the difference between a rule and a skill with a concrete example. Mention that AI config goes through PR review.