GIGACODE.md

GIGACODE.md — это файл конфигурации и инструкций для AI-агентов, работающих с проектом.

Он позволяет описать правила, архитектуру, соглашения и предпочтения команды, чтобы агент принимал решения в контексте конкретного репозитория, а не только на основе общих знаний модели.

Зачем нужен GIGACODE.md

Без дополнительного контекста агент знает только содержимое репозитория и свои базовые знания.

Из-за этого он может:

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

GIGACODE.md позволяет заранее объяснить агенту особенности проекта.

Как это работает

Перед выполнением задачи агент автоматически ищет файл GIGACODE.md.

Если файл найден, его содержимое добавляется в контекст работы модели.

После этого агент использует эти инструкции при:

  • анализе задачи;
  • планировании изменений;
  • написании кода;
  • рефакторинге;
  • генерации тестов;
  • обновлении документации.

Что обычно хранится

Описание проекта

Краткое описание продукта и его назначения.

Например:

  • что делает система;
  • основные компоненты;
  • стек технологий.

Архитектурные правила

Например

  • feature-Sliced Design;
  • clean Architecture;
  • hexagonal Architecture;
  • domain Driven Design;
  • monorepo conventions.

Coding Style

Например

  • стиль именования;
  • правила форматирования;
  • соглашения по React;
  • соглашения по TypeScript;
  • оформление API;
  • правила написания тестов.

Разрешенные библиотеки

Например

Использовать:

  • react Query;
  • zod;
  • tanStack Router.

Не использовать:

  • axios;
  • moment.js.

Правила разработки

Например

  • сначала писать тесты;
  • использовать существующие компоненты;
  • не создавать дублирование;
  • переиспользовать сервисы;
  • не изменять публичные API без необходимости.

Правила безопасности

Например

  • никогда не хранить секреты;
  • не логировать токены;
  • не отключать проверки авторизации;
  • использовать подготовленные SQL-запросы.

Правила работы агента

Можно описать поведение самого агента.

Например

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

Команды проекта

Можно перечислить полезные команды.

npm test
npm run lint
npm run build
npm run e2e

Структура репозитория

Можно описать назначение директорий.

apps/
packages/
libs/
shared/

Это помогает агенту быстрее ориентироваться.

Частые ошибки

Можно заранее предупредить модель.

Например

  • не использовать старый API;
  • не импортировать из внутренних модулей;
  • использовать только новый слой данных.

Где размещать

Чаще всего файл располагается в корне репозитория.

/
├── GIGACODE.md
├── package.json
├── apps/
├── packages/
└── README.md

Также некоторые агентные системы поддерживают несколько файлов GIGACODE.md в разных каталогах. В этом случае инструкции действуют только внутри соответствующей части проекта.

Например

GIGACODE.md

frontend/
    GIGACODE.md

backend/
    GIGACODE.md

mobile/
    GIGACODE.md

Так можно задавать локальные правила для отдельных модулей.

Отличие от README

README отвечает на вопрос:

Что представляет собой проект?

GIGACODE.md отвечает на вопрос:

Как AI-агент должен работать с этим проектом?

README предназначен прежде всего для людей.

GIGACODE.md — для AI-агентов.

Когда стоит использовать

Использование GIGACODE.md особенно полезно для:

  • больших монорепозиториев;
  • корпоративных проектов;
  • команд с внутренними стандартами;
  • проектов со сложной архитектурой;
  • агентской разработки (AI SDLC);
  • нескольких команд, работающих в одном репозитории.

Лучшие практики

  • делайте инструкции короткими и конкретными;
  • описывайте правила, а не очевидные вещи;
  • не дублируйте README;
  • регулярно обновляйте файл вместе с архитектурой проекта;
  • добавляйте только те ограничения, которые действительно важны для качества кода.

Итог

GIGACODE.md — это способ передать AI-агенту знания о проекте еще до начала работы.

Чем качественнее заполнен файл, тем лучше агент понимает архитектуру, стандарты команды и ожидаемый способ выполнения задач, что снижает количество ошибок, уменьшает объем ручных исправлений и делает результаты генерации более предсказуемыми.

Вид графа

Связанные страницы