Skip to content

AIDD_GUIDE_RU.md

Latest commit

 

History

History
809 lines (636 loc) · 27.5 KB

AIDD_GUIDE_RU.md

File metadata and controls

809 lines (636 loc) · 27.5 KB
Raw

AI-Driven Development (AIDD)

Полное руководство по разработке с управлением искусственным интеллектом

📖 Оглавление

  1. Что такое AIDD?
  2. Основные принципы
  3. Архитектура AIDD
  4. Практическое применение
  5. Инструменты и настройка
  6. Рабочий процесс
  7. AI-агенты
  8. Лучшие практики
  9. Примеры использования
  10. Метрики и KPI

🎯 Что такое AIDD?

AI-Driven Development (AIDD) — это революционная методология разработки программного обеспечения, где искусственный интеллект становится основным исполнителем, а человек выступает в роли архитектора и контролёра качества.

Ключевая идея

"Человек определяет ЧТО нужно построить, AI определяет КАК это реализовать"

Сравнение подходов

Традиционная разработка AI-Driven Development
Разработчик пишет код Разработчик пишет спецификации
Ручное написание тестов AI генерирует и запускает тесты
Документация после кода Документация до кода
Код-ревью людьми Автоматическое ревью AI + валидация
Контекст в голове разработчика Контекст в структурированных файлах

Эволюция разработки

1950-1980: Машинный код → Ассемблер
1980-2000: Процедурное → ООП
2000-2020: Монолит → Микросервисы
2020-2030: Ручное кодирование → AI-Driven Development

🏗️ Основные принципы

1. Спецификация превыше всего 📝

  • Спецификация — единственный источник истины
  • Код — производная от спецификации
  • Изменения начинаются со спецификации

2. AI как основная рабочая сила 🤖

  • Специализированные агенты для разных задач
  • Автономная работа в заданных границах
  • Параллельное выполнение задач

3. Контекст — это валюта 💰

  • Структурированный контекст в CLAUDE.md
  • Накопление знаний в ai-docs/
  • Переиспользование паттернов

4. Документация первична 📚

  • Документация пишется до кода
  • Живая документация, которая эволюционирует
  • Двойное назначение: для AI и людей

5. Непрерывный цикл обучения 🔄

  • AI учится на паттернах проекта
  • Документирование решений
  • Каждая итерация улучшает эффективность

🏛️ Архитектура AIDD

Структура проекта

project/
├── CLAUDE.md                 # 🧠 Главный контекст для AI
├── .claude/                  # 🤖 Конфигурация AI
│   ├── agents/              # Специализированные агенты
│   │   ├── planner.md       # Планировщик
│   │   ├── developer.md     # Разработчик
│   │   ├── tester.md        # Тестировщик
│   │   └── reviewer.md      # Ревьюер
│   └── commands/            # Кастомные команды
├── ai-docs/                 # 📚 База знаний AI
│   ├── context.md          # Детальный контекст
│   ├── conventions.md      # Стандарты кодирования
│   ├── current-task.md     # Текущая задача
│   ├── decisions/          # Архитектурные решения
│   └── completed/          # Архив выполненных задач
├── specs/                   # 📋 Спецификации (ПИШУТСЯ ПЕРВЫМИ!)
│   ├── features/           # Функциональные требования
│   └── api/                # API спецификации
├── src/                     # 💻 Исходный код (генерируется AI)
│   ├── domain/             # Бизнес-логика (DDD)
│   ├── api/                # API endpoints
│   └── infrastructure/     # Внешние сервисы
├── tests/                   # 🧪 Тесты (генерируются AI)
└── docs/                    # 📖 Документация для людей

Поток данных в AIDD

graph TD
    A[Бизнес-требования] --> B[Человек: Спецификация]
    B --> C[AI: План реализации]
    C --> D[AI: Написание кода]
    D --> E[AI: Создание тестов]
    E --> F[AI: Код-ревью]
    F --> G[Человек: Валидация]
    G --> H[AI: Документация]
    H --> I[Production]
    I --> J[Обратная связь]
    J --> A
Loading

Роли и ответственности

Человек-архитектор

  • 🎯 Определение бизнес-требований
  • 📝 Написание спецификаций
  • 🏗️ Архитектурные решения
  • ✅ Валидация результатов AI
  • 🎨 Креативные и нестандартные решения

AI-исполнитель

  • 📋 Планирование реализации
  • 💻 Написание кода
  • 🧪 Создание и запуск тестов
  • 🔍 Проверка качества
  • 📚 Обновление документации
  • 🔄 Рефакторинг

💻 Практическое применение

Установка и настройка

Шаг 1: Копирование шаблона

# Копируем AIDD boilerplate
cp -r ~/AI/boiler ~/projects/my-aidd-project
cd ~/projects/my-aidd-project

Шаг 2: Инициализация

# Устанавливаем зависимости
npm install

# Инициализируем AIDD структуру
npm run aidd:init

Шаг 3: Настройка CLAUDE.md

# Контекст проекта

## Методология
Проект следует принципам AI-Driven Development (AIDD)

## Описание
[Описание вашего проекта]

## Технологический стек
- TypeScript 5.x
- Node.js 20.x
- PostgreSQL
- Jest для тестирования

## Правила AIDD
1. Спецификации пишутся первыми
2. AI реализует по спецификациям
3. Человек валидирует результат
4. Документация обновляется автоматически

Шаг 4: Запуск Claude Code

claude-code .

🔄 Рабочий процесс

Основной цикл разработки

1️⃣ Написание спецификации

# specs/features/payment.md

# Функция: Обработка платежей

## Требования
- Принимать платежи картами
- Сохранять историю транзакций
- Отправлять email подтверждения

## API Endpoints
POST /api/payments - Обработать платеж
GET /api/payments/:id - Получить детали платежа

## Модель данных
- amount: number (сумма в копейках)
- currency: string (валюта)
- status: pending|completed|failed

2️⃣ Планирование с AI

"Используй агента planner для создания плана реализации 
функции платежей из specs/features/payment.md"

3️⃣ Реализация с AI

"Используй агента backend-developer для реализации 
платежей согласно плану"

4️⃣ Тестирование с AI

"Используй агента test-runner для создания и запуска 
тестов платежной системы"

5️⃣ Код-ревью с AI

"Используй агента code-reviewer для проверки 
реализации платежей"

6️⃣ Валидация человеком

"Покажи мне реализацию платежной системы для проверки"

7️⃣ Документирование

"Обнови документацию API с новыми endpoints платежей"

Работа с багами

# 1. Описание проблемы
"Пользователи сообщают, что платежи дублируются"

# 2. AI исследует
"Используй test-runner для воспроизведения бага дублирования"

# 3. AI исправляет
"Исправь проблему дублирования платежей"

# 4. AI проверяет
"Запусти все тесты платежей для проверки исправления"

# 5. Документирование
"Задокументируй исправление в ai-docs/decisions/"

Рефакторинг

# 1. Определение области
"Нужно оптимизировать производительность платежей"

# 2. AI анализирует
"Проанализируй узкие места в платежной системе"

# 3. AI предлагает
"Предложи план оптимизации"

# 4. AI рефакторит
"Выполни рефакторинг согласно плану"

# 5. AI тестирует
"Убедись, что все тесты проходят после рефакторинга"

🤖 AI-агенты

Планировщик (Planner)

name: planner
description: Создаёт детальные планы реализации
tools: Read, Grep, Glob

Ответственности:

  • Анализ спецификаций
  • Декомпозиция задач
  • Оценка сложности
  • Выявление зависимостей
  • Определение рисков

Пример использования:

"Используй planner для планирования системы авторизации"

Разработчик (Backend-Developer)

name: backend-developer
description: Реализует функциональность по DDD
tools: Read, Write, Grep, Glob, Bash

Ответственности:

  • Написание бизнес-логики
  • Создание API endpoints
  • Реализация доменных моделей
  • Следование паттернам проекта

Пример использования:

"Используй backend-developer для реализации CRUD операций пользователей"

Тестировщик (Test-Runner)

name: test-runner
description: Запускает и исправляет тесты
tools: Read, Write, Bash, Grep

Ответственности:

  • Написание unit-тестов
  • Создание интеграционных тестов
  • Исправление падающих тестов
  • Анализ покрытия кода

Пример использования:

"Используй test-runner для достижения 90% покрытия кода"

Ревьюер (Code-Reviewer)

name: code-reviewer
description: Проверяет качество и безопасность
tools: Read, Grep, Glob

Ответственности:

  • Проверка качества кода
  • Поиск уязвимостей
  • Соответствие стандартам
  • Оптимизация производительности

Пример использования:

"Используй code-reviewer для проверки всех изменений за сегодня"

Создание собственных агентов

# .claude/agents/database-expert.md
---
name: database-expert
description: Эксперт по базам данных и оптимизации
tools: Read, Write, Bash
---

Ты эксперт по PostgreSQL и оптимизации запросов.

## Твои задачи:
- Проектирование схем БД
- Написание миграций
- Оптимизация запросов
- Создание индексов
- Анализ производительности

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

Написание спецификаций

✅ Хорошая спецификация

# Функция: Корзина покупок

## Цель
Позволить пользователям добавлять товары перед оплатой

## Функциональные требования
1. Добавление товара в корзину
   - Проверка наличия на складе
   - Максимум 10 единиц одного товара
2. Удаление товара из корзины
3. Изменение количества
4. Расчёт общей стоимости с учётом скидок

## API
POST /api/cart/items - Добавить товар
DELETE /api/cart/items/:id - Удалить товар
PUT /api/cart/items/:id - Изменить количество
GET /api/cart - Получить содержимое

## Ограничения
- Корзина хранится 7 дней
- Максимум 50 товаров в корзине

❌ Плохая спецификация

Нужна корзина покупок как в Amazon, 
но проще и с нашим дизайном

Управление контекстом

Оптимальный CLAUDE.md

  • Размер: < 200 строк
  • Структура: Чёткие секции
  • Актуальность: Обновляется еженедельно
  • Фокус: Только важная информация

Структура ai-docs/

ai-docs/
├── context.md          # Статичный контекст проекта
├── conventions.md      # Неизменные правила
├── current-task.md     # Обновляется ежедневно
├── decisions/          # Накапливаются со временем
└── completed/          # Архив для обучения AI

Работа с агентами

Последовательное использование

Spec → Planner → Developer → Tester → Reviewer

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

"Используй 3 агента параллельно:
1. planner для API дизайна
2. developer для моделей данных
3. tester для тест-кейсов"

Специализация агентов

  • Один агент = одна ответственность
  • Чёткие границы между агентами
  • Минимальное пересечение функций

Валидация результатов AI

Чек-лист проверки

  • Соответствует спецификации?
  • Следует конвенциям проекта?
  • Тесты покрывают edge cases?
  • Документация актуальна?
  • Нет очевидных уязвимостей?
  • Производительность приемлема?

Когда требуется ручное вмешательство

  • Сложные алгоритмы
  • Критичная безопасность
  • Интеграция с legacy системами
  • Нестандартные решения
  • Оптимизация производительности

🎯 Примеры использования

Пример 1: E-commerce платформа

Спецификация

# specs/features/product-catalog.md

# Каталог товаров

## Требования
- Иерархические категории
- Фильтрация и поиск
- Сортировка по цене/рейтингу
- Пагинация результатов

## Производительность
- < 100ms ответ API
- Поддержка 10000+ товаров

Команды AIDD

# День 1: Планирование
"Planner: создай план для каталога товаров"

# День 2: Реализация
"Developer: реализуй API каталога"
"Developer: создай доменные модели товаров"

# День 3: Тестирование
"Tester: напиши тесты для каталога"
"Tester: проверь производительность API"

# День 4: Оптимизация
"Reviewer: проверь реализацию каталога"
"Developer: оптимизируй на основе ревью"

Пример 2: SaaS платформа

Структура проекта

saas-platform/
├── specs/
│   ├── features/
│   │   ├── authentication.md
│   │   ├── subscription.md
│   │   ├── billing.md
│   │   └── api-gateway.md
│   └── api/
│       └── public-api-v1.md
├── ai-docs/
│   ├── context.md         # "Multi-tenant SaaS"
│   ├── current-task.md    # "Sprint 23: Billing"
│   └── decisions/
│       ├── 001-auth-jwt.md
│       └── 002-stripe-integration.md
└── src/
    ├── domain/
    │   ├── auth/
    │   ├── billing/
    │   └── subscription/
    └── api/

Типичный спринт

# Понедельник: Планирование
"Прочитай все задачи в specs/features/sprint-23/"
"Planner: создай план спринта"

# Вторник-Четверг: Разработка
"Developer: реализуй billing согласно плану"
"Tester: пиши тесты параллельно с разработкой"

# Пятница: Интеграция
"Reviewer: проверь весь код спринта"
"Developer: исправь замечания ревью"
"Обнови документацию для спринта 23"

Пример 3: Микросервисы

AIDD для микросервисов

# .claude/agents/microservice-architect.md
---
name: microservice-architect
description: Проектирует микросервисную архитектуру
---

Специалист по:
- Определению границ сервисов
- Проектированию API контрактов
- Настройке межсервисного взаимодействия
- Организации распределённых транзакций

Workflow

# Определение границ
"Architect: раздели монолит на микросервисы"

# Для каждого сервиса
"Planner: план для сервиса авторизации"
"Developer: реализуй сервис авторизации"
"Tester: интеграционные тесты между сервисами"

📈 Метрики и KPI

Метрики эффективности AIDD

Скорость разработки

  • Время от спецификации до production
    • Традиционно: 2-3 недели
    • AIDD: 2-3 дня
  • Количество строк кода в день
    • Традиционно: 100-200
    • AIDD: 1000-2000

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

  • Покрытие тестами
    • Целевое: > 80%
    • AIDD среднее: 85-95%
  • Количество багов на 1000 строк
    • Традиционно: 15-20
    • AIDD: 3-5

Документация

  • Актуальность документации
    • Традиционно: 30-40%
    • AIDD: 95-100%
  • Полнота API документации
    • AIDD: 100% автоматически

Расчёт ROI

ROI = (Выгода - Затраты) / Затраты × 100%

Выгода:
- Сокращение времени разработки: 70%
- Снижение количества багов: 75%
- Экономия на документировании: 90%

Затраты:
- Обучение команды AIDD: 40 часов
- Настройка инфраструктуры: 20 часов
- Подписка Claude Code: $20/мес

ROI первого месяца: 300-500%

Мониторинг процесса

Дашборд AIDD

# ai-docs/metrics.md

## Текущая неделя
- Спецификаций написано: 12
- Функций реализовано: 10
- Тестов создано: 145
- Покрытие кода: 87%
- Ревью пройдено: 8/10

## AI использование
- Planner: 15 запросов
- Developer: 48 запросов
- Tester: 32 запроса
- Reviewer: 12 запросов

## Эффективность
- Среднее время feature: 4.5 часа
- Багов найдено AI: 23
- Багов пропущено: 2

🚀 Дорожная карта AIDD

Уровень 1: Начальный (сейчас)

  • ✅ AI помогает с кодом
  • ✅ Базовые агенты
  • ✅ Ручное управление

Уровень 2: Развитый (6 месяцев)

  • 🔄 Автоматическое планирование
  • 🔄 Самообучающиеся агенты
  • 🔄 CI/CD интеграция

Уровень 3: Продвинутый (1 год)

  • 🔮 AI генерирует спецификации
  • 🔮 Автономные команды агентов
  • 🔮 Предиктивная разработка

Уровень 4: Автономный (2-3 года)

  • 🚀 Полностью автономная разработка
  • 🚀 AI архитектор
  • 🚀 Человек только валидирует

❓ Часто задаваемые вопросы

Заменит ли AIDD программистов?

Нет. AIDD меняет роль программиста с "кодера" на "архитектора". Нужны люди для:

  • Понимания бизнес-требований
  • Принятия архитектурных решений
  • Валидации результатов
  • Креативных решений

Какие проекты подходят для AIDD?

Идеально:

  • CRUD приложения
  • API сервисы
  • Бизнес-приложения
  • Админ-панели

Не подходят:

  • Игры
  • Сложные алгоритмы
  • Системное программирование
  • Real-time системы

Какие риски AIDD?

  • Зависимость от AI провайдера
  • Необходимость проверки кода
  • Возможные галлюцинации AI
  • Требует обучения команды

Как начать с AIDD?

  1. Установите Claude Code
  2. Скопируйте boilerplate
  3. Начните с простой функции
  4. Постепенно усложняйте

Сколько стоит AIDD?

  • Claude Code: $20/месяц
  • Обучение: 40 часов
  • ROI: 300-500% в первый месяц

🎓 Обучение AIDD

Неделя 1: Основы

  • Изучить структуру проекта
  • Написать первую спецификацию
  • Использовать planner агента
  • Реализовать простую функцию

Неделя 2: Практика

  • Создать CRUD с AIDD
  • Настроить всех агентов
  • Достичь 80% покрытия тестами
  • Провести код-ревью с AI

Неделя 3: Продвинутый уровень

  • Создать своих агентов
  • Использовать параллельные агенты
  • Реализовать сложную функцию
  • Оптимизировать workflow

Неделя 4: Мастерство

  • Полный цикл разработки функции
  • Интеграция с CI/CD
  • Обучение команды
  • Создание шаблонов проектов

📚 Ресурсы

Официальные ресурсы

Полезные материалы

  • Манифест AIDD: AIDD-MANIFESTO.md
  • Шпаргалка: AIDD-CHEATSHEET.md
  • Примеры спецификаций: specs/examples/
  • Библиотека агентов: .claude/agents/

Инструменты

  • Claude Code
  • Git для версионирования
  • Node.js/Python для runtime
  • PostgreSQL/MongoDB для данных

💡 Заключение

AI-Driven Development — это не просто тренд, а фундаментальный сдвиг в разработке ПО.

Ключевые выводы:

  1. Фокус смещается с написания кода на проектирование систем
  2. AI становится полноценным членом команды
  3. Документация становится кодом
  4. Качество растёт через автоматизацию
  5. Скорость увеличивается в разы

Философия AIDD:

"Мы не заменяем программистов — мы освобождаем их от рутины, позволяя сосредоточиться на том, что действительно важно: решении бизнес-задач и создании ценности."

Начните сегодня:

# Ваш первый AIDD проект
cp -r ~/AI/boiler ~/my-first-aidd
cd ~/my-first-aidd
npm install
claude-code .

# И скажите:
"Давай применим AIDD. Начнём с простой задачи."

Добро пожаловать в будущее разработки! 🚀