AI-Ready проект: как сделать код понятным для искусственного интеллекта

Введение

С развитием AI-ассистентов (GitHub Copilot, Cursor, Claude) разработка становится быстрее. Но не каждый проект одинаково удобен для работы с AI. Что значит AI-Ready проект и как им стать?

AI-Ready — это когда искусственный интеллект может:

• Быстро понять архитектуру проекта
• Генерировать корректный код в стиле проекта
• Находить нужную информацию без долгих поисков
• Предлагать релевантные изменения

Чек-лист AI-Ready проекта

✅ 1. Качественный README

Что должно быть:

• Краткое описание проекта (1-2 абзаца)
• Требования и зависимости
• Инструкция по установке
• Основные команды
• Ссылки на детальную документацию

Пример плохо:

# MyProject
Установить и запустить

Пример хорошо:

# MyProject - Система управления задачами

Веб-приложение на Node.js + React для управления проектами и задачами.

## Требования
- Node.js >= 18.0
- PostgreSQL >= 14
- Redis (опционально, для кэша)

## Быстрый старт
\`\`\`bash
npm install
cp .env.example .env
npm run db:migrate
npm run dev
\`\`\`

✅ 2. Инструкции для AI (Copilot Instructions)

Создайте файл .github/copilot-instructions.md — специальный файл с правилами для AI-ассистентов:

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

## Архитектура
- Backend: PHP 8.1+ с модульной архитектурой
- БД: MySQL с префиксом таблиц `s_`
- Шаблонизатор: Smarty 4

## Соглашения
- Все классы используют namespace `WeppsCore\ClassName`
- БД через PDO: `Connect::$instance->fetch`
- Расширения наследуются от `Extension`

## Паттерны кода
### Guard Clause
Используем ранний return для валидации:
\`\`\`php
if (!$condition) {
    return ['status' => 400, 'message' => 'Error'];
}
// основной код
\`\`\`

## Стиль коммитов
Conventional Commits на русском:
- `feat:` - новая функциональность
- `fix:` - исправление ошибки
- `docs:` - изменения в документации

Зачем это нужно:

• AI сразу понимает контекст проекта
• Генерирует код в вашем стиле
• Пишет коммиты по вашим правилам
• Не нужно каждый раз объяснять архитектуру

✅ 3. Структурированная документация

Базовый набор:

.docs/
├── technical/
│   ├── 01-installation.md      # Установка
│   ├── 02-architecture.md      # Архитектура
│   ├── 03-database-schema.md   # База данных
│   └── 04-development.md       # Разработка
└── user/
    ├── 01-getting-started.md
    └── 02-features.md

Принципы хорошей документации:

• Файлы пронумерованы — понятна последовательность чтения
• Разделение на техническую и пользовательскую
• Каждый файл решает одну задачу
• Примеры кода в контексте

✅ 4. Понятная структура кода

Признаки хорошей структуры:

• Логичное разделение по папкам
• Один класс = один файл = одна ответственность
• Понятные имена файлов и классов

Пример структуры Wepps Platform:

packages/
├── WeppsCore/          # Ядро системы
│   ├── Connect.php     # Подключение к БД
│   ├── Navigator.php   # Маршрутизация
│   └── Extension.php   # Базовый класс расширений
├── WeppsAdmin/         # Административная панель
└── WeppsExtensions/    # Расширения функционала
    ├── Products/       # Каталог товаров
    ├── Cart/          # Корзина
    └── News/          # Новости

AI легко понимает: WeppsExtensions/Cart/Request.php — это обработчик запросов корзины.

✅ 5. Явное именование

Плохо:

class H {
    public function p($d) { ... }
}

Хорошо:

class HttpHandler {
    public function processRequest($data) { ... }
}

AI понимает контекст из имён. Используйте:

• Полные слова вместо сокращений
• Глаголы для методов (getUser, saveData, validateInput)
• Существительные для классов (User, Product, OrderProcessor)

✅ 6. Комментарии для неочевидного

Когда нужны комментарии:

// Обходим ограничение MySQL на GROUP_CONCAT (максимум 1024 байт)
// Увеличиваем лимит для загрузки больших JSON-массивов
Connect::$instance->db->exec("SET SESSION group_concat_max_len = 10000");

$products = $this->getProducts();

Когда НЕ нужны:

// Получаем пользователя по ID
$user = $this->getUserById($id);  // Избыточно!

Хороший код самодокументируется, комментарии — для почему, а не что.

✅ 7. Примеры кода в проекте

Создайте папку examples/ с типичными задачами:

examples/
├── create-extension.php        # Создание расширения
├── database-queries.php        # Работа с БД
├── api-request.php            # API запросы
└── file-upload.php            # Загрузка файлов

AI использует эти примеры как образцы при генерации кода.

✅ 8. Типизация

Используйте типы где возможно:

// Плохо
function getUser($id) {
    return Connect::$instance->fetch("...");
}

// Хорошо
function getUser(int $id): ?array {
    $result = Connect::$instance->fetch("...");
    return $result ?? null;
}

Типы помогают AI понять, что ожидается на входе и выходе.

✅ 9. Консистентные паттерны

Выберите паттерны и следуйте им:

Для Wepps Platform:

• Все расширения наследуются от Extension
• Метод request() — точка входа
• Guard Clause для валидации
• Работа с БД через Connect::$instance

AI быстро выучивает ваши паттерны и применяет их автоматически.

✅ 10. Тесты как документация

Тесты — лучшая документация для AI:

public function testCreateUser() {
    $user = new User();
    $user->setName("John Doe");
    $user->setEmail("john@example.com");

    $result = $user->save();

    $this->assertTrue($result);
    $this->assertNotNull($user->getId());
}

AI видит, как правильно использовать API проекта.

Оценка Wepps Platform

Давайте оценим проект по этим критериям:

Итого: 7/10 — проект уже хорошо подготовлен для AI!

Что улучшить в Wepps Platform

1. Добавить типизацию

// Было
public function getNavigatorData($id) {
    return $this->fetch("...");
}

// Стало
public function getNavigatorData(int $id): ?array {
    $result = $this->fetch("...");
    return $result ?? null;
}

2. Создать папку examples/

examples/
├── 01-create-extension.php
├── 02-database-query.php
├── 03-template-usage.php
└── 04-api-endpoint.php

3. Добавить базовые тесты

Даже простые тесты помогут:

public function testConnectToDatabase() {
    $this->assertInstanceOf(PDO::class, Connect::$instance->db);
}

4. Дополнить комментарии

Особенно в WeppsCore/ для сложных алгоритмов:

/**
 * Рекурсивно строит дерево навигации
 * 
 * @param int $parentId ID родительского раздела
 * @param array $items Плоский массив всех разделов
 * @return array Древовидная структура
 */
public function buildNavigationTree(int $parentId, array $items): array {
    // реализация
}

Выводы

AI-Ready проект — это не отдельная технология, а культура разработки:

• Пишите понятный код
• Документируйте архитектуру
• Следуйте паттернам
• Создавайте примеры

Преимущества:

• AI генерирует корректный код с первого раза
• Новые разработчики быстрее входят в проект
• Меньше времени на код-ревью
• Проще поддержка и рефакторинг

Wepps Platform уже на 70% готов к работе с AI благодаря:

• Структурированной документации
• Copilot Instructions
• Понятной архитектуре
• Консистентным паттернам

Добавьте типизацию, примеры и базовые тесты — и получите проект, с которым AI работает как опытный разработчик!

Полезные ссылки:

• GitHub Copilot Documentation
• Conventional Commits
• PSR-12: Extended Coding Style