Agents, Rules & Instructions

AI only works well if it understands your project.

These files tell your AI helpers how this repo is supposed to work:

• AGENTS.md (and similar agent instruction files)
• CLAUDE.md (Claude Code)
• .cursorrules (Cursor)
• copilot-instructions.md (GitHub Copilot)

If you skip these, you will get:

• Inconsistent architecture
• Random coding styles
• Repeated security mistakes

1. Why these files matter

AI is not a mind reader. It will happily:

• Mix patterns (e.g. Repository + Active Record)
• Ignore your naming or folder structure
• Skip tests and security checks

These files are where you set the rules once per repo instead of writing huge prompts every time.

Core idea:

• Put your architecture, patterns and “non‑negotiables” into these files.
• Then ask the AI: “Do X, follow the existing rules.”

2. Generic guidance for agent / rules files

Treat all of these as instruction manuals for AI collaborators.

Audience:

• Any AI assistant that can read files from the repository.

Goal:

• Make it easy for the AI to “do the right thing by default” without walls of prompt text.

Scope (for all of them):

• What the project does
• Tech stack
• Architecture and patterns to follow / avoid
• Code style and naming
• Security and privacy rules
• Testing expectations

What works well across all files:

• Start with short context, then list clear rules.
• Use bullets instead of long prose.
• Avoid duplication – define common rules once and link to them.
• Keep them up to date when architecture, tooling or standards change.
• If the AI keeps doing something wrong, add a rule that says what to do instead.

3. AGENTS.md – general agent instructions

AGENTS.md is the entry point. Most tools will look for it first.

What it should contain

• A short description of:
  • What the project is and what it does
  • How AI agents should behave (tone, priorities, constraints)
  • Where to find more detailed instructions (.cursorrules, copilot-instructions.md, docs)
• It can also be used by tools that look for names like AGENTS.md, CLAUDE.md, GEMINI.md.5

Suggested structure

# Project: <Name>

## Purpose
- Short, non-marketing description of the system.

## Tech Stack
- Languages
- Frameworks and main libraries
- Testing tools

## Expectations for AI Agents
- Follow the project’s architecture and patterns (see docs).
- Prefer small, reviewable changes.
- Never add dependencies without explicit confirmation.
- Treat security and privacy requirements as hard rules.

## Pointers
- Cursor rules: see .cursorrules
- Copilot: see .github/copilot-instructions.md
- Additional context: see docs/en/

Best practices

• Keep AGENTS.md short – overview only, not a full spec.
• Use it mainly to link out to more detailed rule files instead of duplicating content.
• Review and adjust it frequently – whenever you change architecture, standards, or workflows, update AGENTS.md in the same PR.
• Capture recurring AI mistakes – if the AI keeps making the same kind of error, add a specific “do / don’t” bullet here to fix it for next time.

4. .cursorrules – project rules for Cursor

.cursorrules tells Cursor how to behave in this repo.

What it does

• Cursor reads it to understand:
  • Tech stack and architecture
  • Naming and formatting rules
  • Security and testing requirements
• These rules are used in:
  • Chat
  • Inline edits
  • Multi‑file agents and refactors

Recommended content (short and to the point)14

• Project summary – 5–10 lines max
• Tech stack – languages, frameworks, database, testing stack
• Architecture patterns – e.g. “Clean Architecture”, “Repository pattern, no Active Record”
• Code style – linting/formatting, type checking, naming schemes
• Security requirements – validation, auth, secrets, GDPR hints
• Testing rules – minimum coverage, when to add tests, preferred style
• Examples – 1–2 short code snippets that show “good” style for this project

5. copilot-instructions.md – GitHub Copilot configuration

GitHub Copilot uses a copilot-instructions.md file in the .github/ directory for repository‑wide rules.2

Key points from GitHub’s docs and blog:236

• Use short, imperative bullets, not essays.
• Include:
  • Project overview
  • Tech stack and frameworks
  • Coding standards and patterns to prefer / avoid
  • Security constraints (e.g. “never log PII or secrets”)
• Keep the file well under a few thousand characters so it is reliably read (Copilot code review only processes roughly the first 4k characters of any instruction file).3
• If you need path‑ or language‑specific behaviour, add extra *.instructions.md files.

Minimal example

# Copilot instructions for this repository

- Prefer pytest for tests and follow the style already used in tests/.
- Use type hints consistently in Python code.
- Follow the existing service/repository layering in src/.
- Do not introduce new frameworks or major dependencies without an explicit comment explaining why.
- Treat documented security and privacy rules as hard constraints, not suggestions.

6. How these files work together

In a typical repo, they play different roles:

• AGENTS.md – high‑level onboarding for any AI agent.
• CLAUDE.md – project rules for Claude Code (CLI and IDE integrations).
• .cursorrules – detailed rules for Cursor (multi‑file edits, refactors, agents).
• .github/copilot-instructions.md – focused guidance for GitHub Copilot in editors and PR reviews.