1. Основные правила
Эти принципы помогут эффективно работать с ИИ-инструментами. Они реализуются через глобальные правила и запросы на протяжении всего процесса:- Используйте файлы в формате markdown для управления проектом (README.md, PLANNING.md, TASK.md).
- Держите файлы меньше 500 строк. Разбивайте на модули при необходимости.
- Начинайте новые диалоги часто. Длинные цепочки снижают качество ответов.
- Не перегружайте модель. Один запрос — одна задача.
- Тестируйте рано и часто. Каждая новая функция должна иметь unit-тесты.
- Будьте конкретны в запросах. Чем больше контекста, тем лучше. Примеры очень помогают.
- Документируйте по ходу работы. Не откладывайте написание документации.
- Настраивайте переменные окружения вручную. Не доверяйте ИИ работу с API-ключами.
2. Планирование и управление задачами
Перед написанием кода обсудите с ИИ начальный план и задачи проекта. Общий план заносится в PLANNING.md, а конкретные задачи — в TASK.md. Эти файлы должны обновляться ИИ по мере развития проекта.PLANNING.md
Назначение: Высокоуровневое видение, архитектура, ограничения, стек технологий, инструменты и т. д.
Запрос к ИИ: "Используй структуру и решения, описанные в PLANNING.md."
Поручите ИИ ссылаться на этот файл в начале каждого нового диалога.
TASK.md
Назначение: Отслеживание текущих задач, бэклога и подзадач.
Содержимое: Список активных задач, этапов и всего, что обнаружено в процессе.
Запрос к ИИ: "Обнови TASK.md, отметив XYZ как выполненное и добавив ABC как новую задачу."
ИИ может автоматически обновлять и создавать задачи (через глобальные правила).
3. Глобальные правила (для ИИ-IDE)
Глобальные (или проектные) правила — лучший способ обеспечить соблюдение основных принципов работы с ИИ.Пример правил для проекта Supabase MCP:
Осведомленность о проекте и контекст
Всегда читай PLANNING.md в начале нового диалога, чтобы понять архитектуру, цели, стиль и ограничения проекта.
Проверяй TASK.md перед началом новой задачи. Если задачи нет в списке, добавь ее с кратким описанием и сегодняшней датой.
Соблюдай соглашения по именованию, структуре файлов и архитектуре, как описано в PLANNING.md.
Структура кода и модульность
Не создавай файлы длиннее 500 строк кода. Если файл приближается к этому пределу, разбей его на модули или вспомогательные файлы.
Организуй код в четко разделенные модули, сгруппированные по функционалу или ответственности.
Используй четкие и согласованные импорты (предпочитай относительные импорты внутри пакетов).
Тестирование и надежность
Всегда создавай unit-тесты для новых функций (функций, классов, маршрутов и т. д.) с использованием Pytest.
После обновления логики проверяй, нужно ли обновлять существующие тесты. Если да, сделай это.
Тесты должны находиться в папке /tests, повторяющей структуру основного приложения.
Включай как минимум:
1 тест для ожидаемого использования,
1 граничный случай,
1 тест на ошибку.
Завершение задач
Отмечай выполненные задачи в TASK.md сразу после их завершения.
Добавляй новые подзадачи или TODO, обнаруженные в процессе работы, в TASK.md в раздел "Discovered During Work".
Стиль и соглашения
Используй Python в качестве основного языка.
Следуй PEP8, применяй type hints и форматируй код с помощью black.
Используй pydantic для валидации данных.
Используй FastAPI для API и SQLAlchemy или SQLModel для ORM, если применимо.
Пиши docstrings для каждой функции в стиле Google:
python
Copy
def example():
"""
Краткое описание.
Args:
param1 (тип): Описание.
Returns:
тип: Описание.
"""
Документация и объяснимость
Обновляй README.md при добавлении новых функций, изменении зависимостей или шагов настройки.
Комментируй неочевидный код, чтобы он был понятен разработчику среднего уровня.
Для сложной логики добавляй inline-комментарии с объяснением причины, а не только действия.
Правила поведения ИИ
Не предполагай отсутствующий контекст. Задавай вопросы, если что-то неясно.
Не выдумывай библиотеки или функции — используй только известные, проверенные пакеты Python.
Всегда проверяй пути к файлам и имена модулей, прежде чем ссылаться на них в коде или тестах.
Не удаляй и не перезаписывай существующий код, если это не указано явно или не является частью задачи из TASK.md.
4. Настройка MCP
MCP позволяет вашему ИИ-ассистенту взаимодействовать с сервисами, например:- Работать с файловой системой (чтение/запись, рефакторинг, редактирование нескольких файлов).
- Искать в интернете (полезно для документации) с помощью Brave.
- Использовать Git (ветвление, сравнение, коммиты).
- Подключать память и другие инструменты, например, Qdrant.
Как настроить MCP:
Ссылки на документацию для различных IDE:Cursor MCP: Документация
Windsurf MCP: Документация
Cline MCP: Документация
Roo Code MCP: Документация
Пример запроса с использованием Git MCP:
"Отлично, текущее состояние приложения меня устраивает. Сделай git-коммит, чтобы сохранить его."
5. Начальный запрос для старта проекта
Первый запрос для начала проекта — самый важный. Даже с PLANNING.md, TASK.md и глобальными правилами важно дать ИИ четкие инструкции и примеры.Пример запроса для создания сервера Supabase MCP на Python:
Используй @docs:model-context-protocol-docs и @docs:supabase-docs, чтобы создать MCP-сервер на Python (с FastMCP) для взаимодействия с базой данных Supabase. Сервер должен использовать транспорт Stdio и включать следующие инструменты:
- Чтение строк в таблице
- Создание записи (или нескольких) в таблице
- Обновление записи (или нескольких) в таблице
- Удаление записи (или нескольких) в таблице
Убедись, что каждый инструмент имеет подробное описание, чтобы MCP-сервер мог четко объяснить ИИ, когда и как его использовать.
Переменные окружения для этого сервера: URL проекта Supabase и ключ сервисной роли.
Прочитай этот README на GitHub, чтобы понять, как создавать MCP-серверы на Python:
https://github.com/modelcontextprotocol/python-sdk/tree/main
После создания сервера обнови README.md и TASK.md, так как у тебя теперь есть начальная реализация.
Помни: Начинай новые диалоги, когда текущий становится слишком длинным. Ты поймешь, что пора, когда ИИ начнет тебя раздражать.
6. Модульный процесс запросов после начального этапа
Для последующих исправлений или изменений давайте ИИ по одной задаче за раз, если только задачи не очень простые.Хороший пример:
"Теперь обнови функцию list_records, добавив параметр для фильтрации записей."
Плохой пример:
"Обнови list_records для фильтрации. Затем я получаю ошибку в функции create_row, что API-ключ не найден. Также нужно добавить документацию в main и README.md."
Важно: Поручайте ИИ обновлять один файл за раз и всегда обновлять README.md, PLANNING.md и TASK.md после изменений.
7. Тестируйте каждую функцию
Либо настройте ИИ через глобальные правила на написание unit-тестов после каждой функции, либо делайте это вручную. Раннее обнаружение ошибок предотвращает накопление проблем!Лучшие практики тестирования:
Создавайте тесты в папке /tests.
Мокайте вызовы к сервисам (БД, ИИ и т. д.), чтобы не взаимодействовать с ними напрямую.
Для каждой функции тестируйте: успешный сценарий, ошибку и граничный случай.
8. Деплой с Docker (пример для Supabase MCP)
Когда проект готов к развертыванию, упакуйте его в Docker-контейнер. ИИ отлично работает с Docker, а большинство облачных сервисов поддерживают контейнеры.Dockerfile:
dockerfile
Copy
FROM python:3.12-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .
CMD ["python", "server.py"]
Команда для сборки:
docker build -t mcp/supabase .
Пример запроса к ИИ:
"Напиши Dockerfile для этого MCP-сервера, используя requirements.txt. Дай команды для сборки контейнера. "