Настройка AGENTS.md и project rules в 2026

Короткая версия

Лучший practical setup на 21 марта 2026 обычно такой:

1. AGENTS.md в корне repo - общий contract для современных coding agents.
2. CLAUDE.md - если команда использует Claude Code.
3. .cursor/rules/* - если нужны path-specific правила для Cursor.
4. .github/copilot-instructions.md, .github/instructions/* и agent instructions - для GitHub Copilot.
5. Windsurf rules/memories - если часть команды работает в Windsurf.

Практическая иерархия

Какой минимальный instruction stack нужен команде, которая использует Claude Code, Cursor, Copilot и Codex?

1. Почему старый подход устарел

Раньше можно было написать статью в стиле:

• CLAUDE.md для Claude Code;
• .cursorrules для Cursor;
• copilot-instructions.md для Copilot.

Но current ecosystem уже ушла дальше:

• AGENTS.md стал общим форматом для части coding agents;
• Cursor продвигает rule files в .cursor/rules/, а .cursorrules уже воспринимается как legacy path;
• GitHub Copilot поддерживает и repository instructions, и reusable prompt files, и agent instructions;
• Codex официально читает AGENTS.md;
• Windsurf использует собственные rule/memory surfaces.

Именно поэтому в 2026 полезнее говорить не о "трёх отдельных файлах", а о layered repo instructions.

2. Что положить в shared AGENTS.md

Если команда использует несколько agent tools, лучше всего вынести общий contract в AGENTS.md.

Туда обычно стоит положить:

• tech stack;
• project structure;
• naming conventions;
• commands (dev, test, lint, build);
• testing expectations;
• forbidden patterns;
• review expectations;
• change scope discipline.

Покажи минимальный AGENTS.md для TypeScript monorepo

Минимальный skeleton

# AGENTS.md

## Stack
- TypeScript strict
- Next.js 15
- Prisma + PostgreSQL
- Vitest + Playwright

## Structure
- app/ - routes and UI
- server/ - backend logic
- lib/ - shared utilities
- tests/ - automated tests

## Commands
- pnpm dev
- pnpm test
- pnpm lint
- pnpm build

## Rules
- do not use any
- do not add dependencies unless necessary
- prefer existing patterns over new abstractions
- keep changes scoped to the task

## Verification
- run relevant tests when modifying behavior
- summarize files changed, commands run, and residual risks

3. Где всё ещё нужен CLAUDE.md

Claude Code по-прежнему официально работает с CLAUDE.md и собственной memory hierarchy.

Он особенно полезен, если команде нужны:

• Claude-specific workflows;
• local/user/project hierarchy;
• terminal-first conventions;
• более явные instructions around commands, git and repo behavior.

Практически хорошо работает такой подход:

• AGENTS.md - shared repo contract;
• CLAUDE.md - Claude-specific clarification и local hierarchy.

4. Cursor: .cursor/rules сильнее, чем legacy .cursorrules

Старая статья про .cursorrules уже неполная.

Current Cursor docs продвигают:

• AGENTS.md;
• .cursor/rules/ для scoped rules;
• более granular activation по контексту.

Это лучше старой модели "один гигантский .cursorrules файл", потому что позволяет разделить:

• frontend rules;
• backend rules;
• test rules;
• migration rules.

Полезная структура

.cursor/
  rules/
    global.mdc
    frontend.mdc
    backend.mdc
    tests.mdc

Такой setup обычно удобнее, чем один длинный prompt-file на всё сразу.

5. GitHub Copilot: instructions теперь шире одного файла

У GitHub Copilot current setup уже не сводится к одной записи про .github/copilot-instructions.md.

Сегодня practical stack может включать:

• repository custom instructions;
• .github/copilot-instructions.md;
• .github/instructions/*.instructions.md для scoped instructions;
• reusable prompt files;
• agent instructions для Copilot coding agent;
• Spaces как curated context layer, если команда уже активно живёт в GitHub-native workflow.

Это важно, потому что current Copilot now covers both:

• classic assistant surfaces;
• agent mode в IDE;
• agentic GitHub workflows через coding agent.

И значит repo setup должен помогать не только autocomplete, но и agent tasks.

Что это меняет practically

После появления отдельной статьи про GitHub Copilot в 2026 этот блок полезно читать точнее:

• copilot-instructions.md и .github/instructions/* нужны для IDE/chat/edit surfaces;
• agent instructions важны для Copilot coding agent, который работает уже не в локальном editor loop, а в GitHub-native async flow;
• AGENTS.md остаётся хорошим shared truth source, если команда одновременно использует Copilot, Cursor, Claude Code, Codex и Windsurf.

То есть current Copilot setup уже не про "один файл правил для плагина", а про layered guidance под несколько разных Copilot surfaces.

6. Windsurf: rules и memories

У Windsurf instruction surface тесно связана с Cascade и memories/rules.

Практически Windsurf полезно кормить:

• кратким repo contract;
• scoped rules по типам задач;
• устойчивыми conventions;
• examples of preferred patterns.

Логика здесь похожа на Cursor: чем точнее разделены постоянные project rules и task-specific prompts, тем стабильнее agent behavior.

7. Codex и AGENTS.md

Для Codex current official docs уже делают AGENTS.md важной частью repo guidance.

Это ещё один аргумент за shared file: если у команды есть Codex, Cursor, Windsurf и часть GitHub/Copilot workflows, AGENTS.md становится естественным общим знаменателем.

Это особенно полезно для mixed-tool teams, где нельзя держать пять разных truth sources.

8. Что именно писать в instruction files

Лучшие repo instructions обычно содержат:

• stack and versions;
• folder layout;
• naming rules;
• testing rules;
• style constraints;
• forbidden patterns;
• dependency policy;
• commands;
• how to summarize work.

Хуже всего работают:

• слишком общие лозунги;
• длинные философские тексты;
• дублирующиеся правила в разных файлах;
• противоречащие друг другу instructions.

9. Хорошая структура instruction stack

Практический template для mixed-agent команды:

AGENTS.md
CLAUDE.md
.cursor/
  rules/
    global.mdc
    frontend.mdc
    backend.mdc
.github/
  copilot-instructions.md
  instructions/
    frontend.instructions.md
    backend.instructions.md
prompts/
  review.prompt.md
  migration.prompt.md
  debug.prompt.md

Здесь:

• AGENTS.md - общий truth source;
• tool files - только tool-specific deltas;
• prompts/ - reusable task patterns;
• personal files - не коммитятся.

10. Чего не стоит делать

1. Дублировать весь контент во все файлы

Это быстро ломается.

2. Писать 500 строк на все случаи жизни

Слишком длинные rule files хуже читаются и хуже поддерживаются.

3. Смешивать постоянные правила и разовые задачи

Разовые migration instructions не должны жить в главном repo contract.

4. Хранить секреты в project instruction files

Repo instructions должны быть безопасны для коммита.

11. Что лучше держать в prompt files

В prompt files хорошо выносить повторяемые workflow-шаблоны:

• code review;
• migration;
• bug report analysis;
• security review;
• release notes generation;
• test-writing workflow.

Это уже не repo contract, а reusable task interfaces.

Проверьте себя