AI-Assisted Development

Agents, Rules & Instructions

Workshop — Part 8: Teaching AI how your project works

7 / 12 — Agent Rules
AI-Assisted Development

AI only works well

if it understands your project.

7 / 12 — Agent Rules
AI-Assisted Development

Without Rules Files, You Get…

AI is not a mind reader. Without instructions it will happily:

  • Mix patterns — Repository and Active Record in the same codebase
  • Ignore your naming and folder structure
  • Skip tests and security checks
  • Suggest packages it vaguely remembers from training

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

7 / 12 — Agent Rules
AI-Assisted Development

The Four Files

AGENTS.md
High-level onboarding for any AI agent.
Most tools look for this first.

CLAUDE.md
Project rules for Claude Code.
CLI and IDE integrations.

.cursorrules
Detailed rules for Cursor.
Used in chat, inline edits, and agents.

.github/copilot-instructions.md
Focused guidance for GitHub Copilot.
Chat and PR review.

When these files say the same thing — all tools behave consistently.

7 / 12 — Agent Rules
AI-Assisted Development

AGENTS.md — The Entry Point

Keep it short — overview only, not a full spec.

Use it to link out to more detailed rule files.

What to include:

  • What the project does
  • How AI agents should behave
  • Pointers to .cursorrules, copilot-instructions.md

Update it in the same PR whenever you change architecture, standards, or workflows.

# Project: <Name>

## Purpose
Short description of the system.

## Tech Stack
- Languages
- Frameworks, libraries
- Testing tools

## Expectations for AI Agents
- Follow architecture & patterns.
- Prefer small, reviewable changes.
- Never add dependencies without confirmation.
- Treat security rules as hard constraints.

## Pointers
- Cursor rules: see .cursorrules
- Copilot: see .github/copilot-instructions.md
7 / 12 — Agent Rules
AI-Assisted Development

.cursorrules — Rules for Cursor

Used in: chat, inline edits, multi-file agents

What to include:

  • Project summary (5–10 lines max)
  • Tech stack with versions
  • Architecture patterns (what to use, what to avoid)
  • Code style and formatting rules
  • Security requirements
  • Testing rules

Keep it concise and specific — long stories waste context and are less likely to be followed.

# Example .cursorrules

- FastAPI 0.109+ / SQLAlchemy 2.0 / Pydantic v2
- Clean Architecture: Domain → Application → Infrastructure
- Repository Pattern (NO Active Record)
- All inputs validated via Pydantic
- pytest with 80%+ coverage
- Black formatter, MyPy strict
- Never log PII or secrets
- Parameterized queries only — no string concatenation
7 / 12 — Agent Rules
AI-Assisted Development

copilot-instructions.md — Rules for Copilot

Placed in .github/copilot-instructions.md

  • Use short, imperative bullets — not essays
  • Keep it well under a few thousand characters (Copilot code review processes ~4k chars)
  • For path- or language-specific behavior, add *.instructions.md files
# Copilot instructions

- Prefer pytest for tests; follow the style in tests/.
- Use type hints consistently in Python code.
- Follow the existing service/repository layering in src/.
- Do not introduce new frameworks without an explicit comment explaining why.
- Treat security and privacy rules as hard constraints, not suggestions.
7 / 12 — Agent Rules
AI-Assisted Development

What Goes in Every Rules File

Always include:

  • What the project does
  • Tech stack and versions
  • Architecture patterns to follow / avoid
  • Naming conventions
  • Security and privacy rules
  • Testing expectations

Best practices across all files:

  • Short context, then clear rules
  • Use bullets instead of long prose
  • Avoid duplication — define rules once
  • Update when architecture changes
  • If AI keeps making the same mistake → add a rule for it

These files are living documents.
Update them in the same PR as any architecture or standards change.

7 / 12 — Agent Rules
AI-Assisted Development

Summary

  • Rules files are your most powerful tool for consistent AI behavior
  • AGENTS.md — high-level entry point for any AI agent
  • CLAUDE.md — rules for Claude Code
  • .cursorrules — detailed rules for Cursor
  • .github/copilot-instructions.md — rules for Copilot
  • Keep them short, specific, and up to date
  • If AI keeps repeating the same mistake → fix the instruction, not the output