gooseek/AGENTS.MD

Инструкции для AI-агента

Старт сессии

Сначала проверь CONTINUE.md в корне проекта. Если файл есть — начни с недоделок из него, затем бери новую задачу пользователя. В конце добавь что нужно доработать и что недоделал в рамках одного прохода генерации.

ВАЖНО! ДЕЛАЕМ ВСЕ ДЛЯ ПРОДАКШЕНА РАБОЧЕЕ НА ПРОДАКШЕНА!!!! НЕТ НИКАКИХ ЛОКАЛЬНЫХ ДОРАБОТОК РАЗРАБОТОК ДЕВ СРЕДЫ!!!!!!!!! И НЕ ДЕЛАЙ ДЕВ СРЕДУ!!!! ЭТО ПРОДАКШЕН!!!! ЕСЛИ В КОДЕ УВИДИШЬ ГДЕТО ДЕВ СРЕДУ ЭТО ОСТАТКИ СТАРОЙ ЛОГИКИ ПЕРЕВОДИ ЕЕ НА ПРОДАКШЕН ЕСЛИ НУЖНО УДАЛЯЙ!!!

ДЕПЛОЙ: только Docker + Kubernetes (локальный K3s на машине). Никакого npm publish, registry push, Vercel. ./deploy/k3s/deploy.sh — единственный способ деплоя.

Общий принцип

Не MVP, а production. Каждая задача выполняется полностью, как для enterprise-продукта. Никаких заглушек, TODO и «сделаем потом». ИПОЛЬЗУЙ ТОЛЬКО БЕСТ ПРАКТИКИ и сервисную архитектуру с переиспользованием компонентов.

---

1. Завершённость задач

• Перед завершением: проверь, что все части задачи сделаны. Чеклист обязателен.
• Если задача «добавить X» — значит: код, типы, обработка ошибок, edge cases.
• Контекстное окно ограничено — всё за один проход нереально. Обязательно документируй недоделки (см. раздел 7).
• После правок — пройдись по связанным файлам: импорты, экспорты, зависимости.

---

2. Качество кода

• TypeScript: строгая типизация. Не any. Явные типы для параметров и возвращаемых значений.
• Стиль: следуй существующему коду в проекте. Используй Prettier/ESLint.
• Именование: чёткие, понятные имена. handleSubmit, а не doStuff.
• Структура: логика в отдельных модулях, UI — в компонентах. Избегай «god functions».

---

3. Обработка ошибок

• Каждый API route: try/catch, понятные сообщения об ошибках.
• Внешние сервисы: таймауты, retry, fallback где уместно.
• Пользователь должен видеть понятное сообщение, не сырой stack trace.

---

4. Безопасность

• Входные данные: валидация (Zod и т.п.), никогда не доверять клиенту.
• Секреты: только переменные окружения, не в коде.
• SQL/запросы: параметризованные запросы, без конкатенации строк.

---

5. Производительность

• Компоненты: useMemo, useCallback где нужно.
• API: не тянуть лишние данные, пагинация для списков.
• БД: индексы для частых запросов, N+1 избегать.

---

6. Чеклист перед завершением

• Все новые файлы созданы и подключены
• Импорты и экспорты корректны
• Типы указаны, ошибок TypeScript нет
• Обработка ошибок добавлена
• Нет console.log, TODO, заглушек
• Проверены связанные компоненты/роуты
• Нет поломанного существующего функционала

---

7. Файл недоделок (CONTINUE.md)

Когда контекст заканчивается или задача не завершена — записывай в CONTINUE.md в корне проекта. Следующая генерация читает его первой и продолжает с этого места.

Формат файла

# Недоделки — начать отсюда

## Задача (исходный запрос)
[кратко что хотел пользователь]

## Сделано
- [список файлов и изменений]
- [что уже работает]

## Осталось сделать (в порядке приоритета)
1. [конкретное действие] — файл `src/path/file.ts`, строка ~X
2. [следующее действие] — файл `path/to/other.ts`
3. [ ] Добавить обработку ошибок в route X
4. [ ] Проверить импорты в компоненте Y

## Контекст для продолжения
- Изменённые файлы: `file1.ts`, `file2.tsx`
- Зависимости: компонент A использует B из `lib/B.ts`

Правила ведения

• Перед завершением сессии: если что-то не доделано — обнови CONTINUE.md. Не полагайся на память.
• В начале новой сессии: если есть CONTINUE.md — прочитай его и начни с «Осталось сделать». Не начинай задачу с нуля.
• Каждый пункт — конкретный, с путём к файлу. Не «доделать», а «добавить try/catch в api/chat/route.ts».
• После полного завершения — очисти или удали CONTINUE.md, чтобы не путать следующие задачи.

---

8. Запреты

• Не оставлять недоделанную реализацию без записи в CONTINUE.md
• Не использовать any без крайней необходимости
• Не коммитить закомментированный код
• Не забывать про loading и error states в UI
• Не игнорировать accessibility (a11y) для интерактивных элементов