28 июля 2026 7 min read Гайды

AGENTS.md на практике: 3 готовых примера под Node.js, Python и Go

Этот пост — практическое дополнение к прошлой статье про AGENTS.md. Там был стандарт, концепция, антипаттерны. Здесь — конкретные файлы, которые можно скопировать в свой репозиторий и адаптировать за полчаса.

Ниже три примера: Node.js TypeScript (фронт/бэк на TS), Python FastAPI (бэкенд на ML/DATA), Go (микросервис). К каждому — короткая инструкция «как пользоваться»: что менять под себя, что оставлять как есть, на что смотреть.

Прежде чем копировать: убедитесь, что у вас уже прочитан (и согласован с тем, что вам реально нужно) первый пост. Эти файлы — продолжение того материала, а не замена ему.

Стек 1: Node.js + TypeScript

Подходит для: фронтенд на React/Vue, бэкенд на Express/NestJS, монорепозитории на pnpm/turbo. Самый частый случай, поэтому пример самый развёрнутый.

Корневой файл `AGENTS.md`

# AGENTS.md

## Обзор
TypeScript-монорепозиторий интернет-магазина. Используется pnpm + turbo для оркестрации пакетов.

## Стек
- pnpm 9.x (НЕ npm, НЕ yarn)
- TypeScript 5.4+
- Node.js 20 LTS (НЕ 22, ещё не стабилизировали нативные тесты)
- React 18 для веба, NestJS 10 для API

## Команды
- Установка: `pnpm install --frozen-lockfile`
- Сборка: `pnpm --filter @app/web build` или `pnpm --filter @app/api build`
- Тесты: `pnpm --filter <pkg> test <file-pattern>`
- Линтер: `pnpm -r lint`
- Полная проверка: `pnpm -r exec tsc --noEmit && pnpm -r test`

## Структура
- `packages/web/` — фронтенд на React
- `packages/api/` — бэкенд на NestJS
- `packages/shared/` — общие типы и утилиты
- `docs/conventions/` — узкие правила (см. ниже)

## Границы
- ЗАПРЕЩЕНО: редактировать `**/generated/**` (код генерируется из схем)
- ЗАПРЕЩЕНО: добавлять зависимости в `package.json` без согласования с тимлидом
- ЗАПРЕЩЕНО: удалять или комментировать упавшие тесты — исправлять причину
- ТРЕБУЕТ ПОДТВЕРЖДЕНИЯ: переименование типов в `packages/shared/`
- ТРЕБУЕТ ПОДТВЕРЖДЕНИЯ: миграция БД (`prisma migrate`)

## Дополнительные руководства
- Стиль TypeScript и именование: `docs/conventions/typescript.md`
- Паттерны тестирования: `docs/conventions/testing.md`
- Работа с API и схемами: `docs/conventions/api.md`

Что здесь важно и почему

«НЕ npm, НЕ yarn» — короткая фраза экономит часы. Агент по умолчанию предложит npm install, потому что в обучающих данных это самый частый случай. Жёсткий запрет останавливает эту привычку.
«НЕ 22» — конкретный запрет версии Node. Если в команде ещё не перешли на 22, это надо сказать явно. Иначе агент поставит свежий LTS и сломает половину тестов.
Конкретные команды с флагами — --frozen-lockfile для pnpm обязателен (блокирует обновление зависимостей без явного апдейта). Без этого флага агент может предложить pnpm install, который молча обновит lockfile.
Трёхуровневая модель — ЗАПРЕЩЕНО / ТРЕБУЕТ ПОДТВЕРЖДЕНИЯ / ОБЯЗАТЕЛЬНО нигде не спрятана. Каждое правило имеет тег, и агент видит его с первого взгляда.
Семантика директорий вместо путей — в описании «packages/web/ — фронтенд», а не «открой packages/web/src/components/Header.tsx». При рефакторинге файлы переедут, AGENTS.md останется.

Пример дочернего `packages/api/AGENTS.md`

В монорепо корневой файл задаёт общий контекст, а локальные — правила конкретного пакета. Вот что лежит в packages/api/AGENTS.md:

# API Service Guide

## Назначение
HTTP API на NestJS. Все ручки объявлены декораторами в `*/controllers/`.

## Стек пакета
- NestJS 10
- Prisma 5 для БД (PostgreSQL)
- class-validator для валидации DTO
- Jest + supertest для интеграционных тестов

## Правила валидации
- Каждый DTO должен иметь class-validator декораторы
- Никогда не использовать `any` в DTO — генерируется тип из Prisma
- Возвращать 4xx с `{ error: { code, message } }`, не со строкой
- Логировать через встроенный NestJS Logger, не console.log

## Тестирование
- Юнит-тесты: `*.spec.ts` рядом с исходником
- Интеграционные: `test/integration/*.e2e-spec.ts`
- НЕ мокать PrismaClient в интеграционных тестах — используется test DB
- Для новых эндпоинтов — обязательно покрытие: happy path + 3 негативных

## Границы
- ЗАПРЕЩЕНО: трогать `prisma/schema.prisma` без согласования с data-командой
- ЗАПРЕЩЕНО: добавлять новые ручки без OpenAPI-схемы в `docs/api-spec.yaml`

Заметьте: правила этого файла перекрывают корневой AGENTS.md. Если в корне написано «все тесты через vitest», а здесь «Jest» — побеждает локальный. Это по спецификации.

Стек 2: Python + FastAPI

Подходит для: ML-сервисов, data-пайплайнов, REST API на FastAPI. Здесь главная специфика — uv вместо pip, и pytest с фикстурами.

Корневой файл `AGENTS.md`

# AGENTS.md

## Обзор
Python-бэкенд для ML-инференса. Используется uv для управления зависимостями и Ruff для линтинга.

## Стек
- Python 3.11+ (НЕ 3.12, есть несовместимости с pytorch на arm64)
- uv 0.4+ (НЕ pip, НЕ poetry)
- FastAPI 0.110+
- SQLAlchemy 2.0 + Alembic
- pytest 8 с фикстурами

## Команды
- Установка: `uv sync --frozen`
- Запуск dev: `uv run fastapi dev app/main.py`
- Тесты: `uv run pytest tests/unit -v` или `uv run pytest tests/integration -v`
- Линтер: `uv run ruff check . && uv run ruff format --check .`
- Миграции: `uv run alembic upgrade head`

## Структура
- `app/api/` — FastAPI роуты
- `app/models/` — SQLAlchemy-модели
- `app/schemas/` — Pydantic-схемы (НЕ модели, только DTO)
- `app/services/` — бизнес-логика
- `tests/unit/` — изолированные тесты
- `tests/integration/` — тесты с реальной БД (testcontainers)

## Границы
- ЗАПРЕЩЕНО: импорт моделей SQLAlchemy в схемах Pydantic (использовать отдельные DTO)
- ЗАПРЕЩЕНО: коммит `.env`, секретных ключей, credentials JSON
- ЗАПРЕЩЕНО: добавление зависимостей без обновления `pyproject.toml` через uv add
- ТРЕБУЕТ ПОДТВЕРЖДЕНИЯ: миграция схемы БД
- ТРЕБУЕТ ПОДТВЕРЖДЕНИЯ: изменение Docker-конфигурации

## Дополнительные руководства
- Стиль Python (PEP 8 + наши отклонения): `docs/conventions/python.md`
- Паттерны тестов и фикстуры: `docs/conventions/testing.md`
- Работа с моделями ML: `docs/conventions/ml.md`

Что здесь важно

«НЕ 3.12» — конкретная версия Python с обоснованием. uv по умолчанию может поставить свежий релиз. Без явного запрета агент выберет «самое новое».
uv вместо pip/poetry — это выбор команды, и он радикально меняет команды. Если не зафиксировать, агент всегда предложит pip install.
Разделение моделей и схем — это инвариант проекта. SQLAlchemy-модели для работы с БД, Pydantic-схемы для API. Нарушение этой границы ломает сериализацию и приводит к утечкам паролей через ответы API.
testcontainers для интеграционных тестов — критическая часть. Без неё «интеграционные тесты» превращаются в моки, которые ничего не проверяют.

Стек 3: Go

Подходит для: микросервисов, CLI-утилит, высоконагруженных бэкендов. В Go многое «дефолт правильно», поэтому AGENTS.md тут короче и сосредоточен на исключениях.

Корневой файл `AGENTS.md`

# AGENTS.md

## Обзор
Go-микросервис для очереди задач. Используется стандартная библиотека go-kit и sqlx для БД.

## Стек
- Go 1.22+ (используется новый range-over-int)
- go-kit v0.13
- sqlx для Postgres
- testify для тестов
- golangci-lint как единый линтер

## Команды
- Сборка: `make build` (см. Makefile) или `go build ./cmd/service`
- Тесты: `go test ./... -race` (обязательно с -race для конкурентного кода)
- Линтер: `make lint` или `golangci-lint run ./...`
- Генерация моков: `go generate ./...`

## Структура
- `cmd/service/main.go` — точка входа
- `internal/service/` — бизнес-логика (НЕ экспортируется наружу)
- `internal/transport/` — HTTP/gRPC обработчики
- `pkg/` — публичное API для других сервисов
- `migrations/` — SQL-миграции (выполняются отдельным CI-шагом)

## Стиль
- Следовать Effective Go, плюс:
- ЗАПРЕЩЕНО: использовать `log.Fatal` в продакшен-коде, только `log.Error` + возврат ошибки
- ЗАПРЕЩЕНО: паника в боевом коде (паника только в инициализации при фатальной ошибке конфига)
- Каждая экспортируемая функция — с docstring в стиле godoc
- Ошибки оборачиваются через `fmt.Errorf("...: %w", err)`, не теряется контекст

## Тестирование
- Юнит-тесты рядом с файлом: `foo.go` → `foo_test.go`
- Использовать `testify/require` для критичных проверок, `testify/assert` для остального
- Конкурентный код ОБЯЗАТЕЛЬНО покрывать тестом с `go test -race`
- НЕ мокать БД в интеграционных тестах

## Границы
- ЗАПРЕЩЕНО: импорт из `internal/` за пределами родительского дерева
- ЗАПРЕЩЕНО: коммит бинарников, скомпилированных proto-файлов
- ТРЕБУЕТ ПОДТВЕРЖДЕНИЯ: изменение API в `pkg/`
- ТРЕБУЕТ ПОДТВЕРЖДЕНИЯ: добавление новых внешних зависимостей

Что здесь важно

Короткий по сравнению с Python — в Go изначально многое делается правильно. AGENTS.md фиксирует только отклонения, а не повторяет Effective Go.
Запрет log.Fatal в продакшен-коде — это специфика проекта. Без запрета агент по привычке добавит log.Fatal, и сервис упадёт при первом сетевом сбое.
go test -race обязательно — в Go конкурентность везде, и без race detector баги ловятся только на проде.
Структура internal/ vs pkg/ — это инвариант, нарушение которого ломает инкапсуляцию. Агент по умолчанию не знает, где у нас граница.

Что нужно поправить под себя

Скопированные файлы — стартовая точка, не готовый продукт. Вот минимальный чек-лист перед коммитом:

Проверьте версии. В моих примерах React 18, TypeScript 5.4+, Go 1.22+ — в вашем проекте могут быть другие. Замените актуальные.
Проверьте команды. Убедитесь, что каждая команда реально работает в вашем проекте. Если используете turbo или nx — добавьте их.
Удалите лишнее. Если в проекте нет монорепо, не нужен блок про pnpm --filter. Минимум — лучше максимума.
Добавьте свои «НЕ». Главная ценность AGENTS.md — локальные запреты. Если у вас в команде «не пишем комментарии» или «не используем lodash» — добавьте явно.
Добавьте свои «ТРЕБУЕТ ПОДТВЕРЖДЕНИЯ». Что в вашем проекте требует созвона с тимлидом? Миграция БД? Деплой? Изменение API? Всё, что дорого откатить — туда.
Сделайте ссылки на docs/ реальными. Файлы docs/conventions/typescript.md и подобные пока пусты — создайте их и перенесите туда узкие правила. Иначе это будут ссылки в никуда, которые подорвут доверие агента к файлу.

Чего в этих примерах нет, но стоит добавить

Когда устаканится базовый AGENTS.md, обычно нужно дополнить его:

Раздел про CI/CD

Какие шаги в pipeline, какие тесты запускаются, как проверить status перед коммитом. Пример:

## CI/CD
- На каждый PR запускаются: lint, typecheck, unit tests
- Интеграционные тесты — только на merge в main
- Деплой на staging автоматический, на prod — ручной

Раздел про работу с фича-флагами

Если у вас есть фича-флаги (feature flags — механизм включения/выключения функциональности без релиза), пропишите правила:

## Фича-флаги
- Все флаги через сервис ConfigCat, НЕ env-переменные
- Каждый флаг имеет TTL (время жизни, после которого удаляется)
- Устаревшие флаги удаляются в течение 30 дней после 100% rollout

Раздел про секреты и чувствительные данные

Если проект работает с пользовательскими данными или финансами — это критично:

## Безопасность
- ЗАПРЕЩЕНО: логирование токенов, паролей, номеров карт
- ЗАПРЕЩЕНО: запись чувствительных данных в файлы вне `data/secrets/`
- Все эндпоинты с финансами — за audit-log через middleware
- Секреты берутся из Vault, не из env

Как ввести AGENTS.md в команду

Файл не работает, если команда его игнорирует или он конфликтует с реальностью. Порядок внедрения, который мы видели у команд, прошедших это без боли:

Начните с малого. Корневой AGENTS.md на 50–70 строк — это достаточно для старта. Расширяйте по мере появления вопросов.
Согласуйте с командой. Особенно блок границ — там, где раньше решения принимал тимлид лично. Команда должна согласиться, что ИИ-агент может это решать.
Синхронизируйте с ужесточением линтера. Если в проекте включается новое правило ESLint/Ruff/golangci-lint — дублируйте его в AGENTS.md. Агент видит оба источника и следует.
Рефакторьте каждый квартал. Устаревшие правила вредят. Раз в 3 месяца пересмотр: что не нужно, что забыли, что появилось нового.
Измеряйте эффект. До AGENTS.md и через 1–2 месяца после. Метрики: время на задачу (откуда PR открыт до merge), процент ревью-итераций (сколько раз правят код по комментариям ревьюера), число инцидентов после релиза.

Главное, что стоит запомнить

AGENTS.md — это не документация для людей. Это инструкция для агента, которую люди тоже могут прочитать и убедиться, что она верная. Разница в том, что человек может простить файл с неточностями, а модель — нет: она начнёт следовать ложным правилам буквально.

Поэтому главный критерий качества — соответствие реальности. Если в проекте перестали использовать какой-то паттерн — удалите его из AGENTS.md. Если команда решила ввести новое правило — добавьте немедленно. Если правило устарело — лучше удалить и опираться на линтер.

Лучший AGENTS.md — это тот, в котором всё написанное используется и ничто забытое не осталось. Не больше, не меньше.

Если у вас уже есть свой AGENTS.md и вы хотите получить ревью — присылайте в комментарии, могу дать обратную связь что улучшить. Без воды, по чек-листу.