diff --git a/⚙️ Техническое/Унификация разработки с ИИ-агентами.md b/⚙️ Техническое/Унификация разработки с ИИ-агентами.md new file mode 100644 index 0000000..def570b --- /dev/null +++ b/⚙️ Техническое/Унификация разработки с ИИ-агентами.md @@ -0,0 +1,333 @@ +#ai-development #coding-standards #workflow #productivity + +**Создано:** 2025-09-09 +**Статус:** Активная практика +**Теги:** [[AI Tools]] [[Development Process]] [[Best Practices]] + +--- + +## Проблема + +При работе с множественными проектами на разных языках программирования ([[Java]], [[Go]], [[Python]], [[Angular]]) и использовании ИИ-агентов ([[Claude Code]], [[Cursor]]) возникают проблемы: + +- Отсутствие единых стандартов между проектами +- Неэффективная коммуникация с ИИ-агентами +- Потеря времени на объяснение контекста каждый раз +- Непоследовательность в архитектурных решениях + +## Решение: Система унифицированных инструкций + +### Базовый принцип + +Каждый проект должен содержать структурированный набор инструкций для ИИ-агентов, обеспечивающий: +- ✅ Консистентность кода между проектами +- ✅ Быстрый старт работы с ИИ +- ✅ Соблюдение архитектурных принципов +- ✅ Качественный код на всех языках + +--- + +## Структура системы + +### 🗂️ Файловая структура + +``` +project-root/ +├── .ai-instructions/ # 🎯 Ключевая папка с инструкциями +│ ├── project-context.md # Контекст и цели проекта +│ ├── coding-standards.md # Стандарты для каждого языка +│ ├── architecture.md # Архитектурные решения +│ ├── workflow.md # Процесс работы с ИИ +│ └── tech-stack.md # Специфика технологий +├── .cursorrules # Правила для Cursor +├── .claudeproject # Конфигурация Claude Code +└── README.md # Документация проекта +``` + +> [!tip] Ключевая идея +> Папка `.ai-instructions/` становится единым источником истины для всех ИИ-агентов в проекте + +### 🔧 Конфигурационные файлы + +#### .cursorrules +```txt +# Процесс: АНАЛИЗ → ДЕКОМПОЗИЦИЯ → ПЛАН → ПОДТВЕРЖДЕНИЕ → РЕАЛИЗАЦИЯ +# Языки: Java (Spring), Go, Python (FastAPI/Django), Angular +# Стандарты: читай .ai-instructions/coding-standards.md +``` + +#### .claudeproject +```json +{ + "instructions": [ + "ОБЯЗАТЕЛЬНЫЙ ПРОЦЕСС: АНАЛИЗ → ДЕКОМПОЗИЦИЯ → ПЛАН → ПОДТВЕРЖДЕНИЕ → РЕАЛИЗАЦИЯ", + "Читай контекст из .ai-instructions/ перед работой" + ] +} +``` + +--- + +## Основной рабочий процесс + +### 🎯 Пятиэтапный процесс + +```mermaid +graph TD + A[📊 АНАЛИЗ] --> B{Сложная задача?} + B -->|Да| C[🔧 ДЕКОМПОЗИЦИЯ] + B -->|Нет| D[📋 ПЛАНИРОВАНИЕ] + C --> D + D --> E[✅ ПОДТВЕРЖДЕНИЕ] + E -->|Одобрено| F[⚡ РЕАЛИЗАЦИЯ] + E -->|Изменения| D +``` + +#### 1. 📊 Анализ задачи +**Что делает ИИ:** +- Изучает контекст и существующий код +- Определяет затронутые компоненты +- Оценивает сложность и риски +- Выявляет зависимости + +**Ключевые вопросы:** +- Какие компоненты системы будут изменены? +- Есть ли зависимости от других модулей? +- Требуются ли изменения в API? +- Какие могут быть побочные эффекты? + +#### 2. 🔧 Декомпозиция (при необходимости) +**Критерии для декомпозиции:** +- ❗ Задача затрагивает > 3 файлов +- ❗ Нужны изменения в разных языках +- ❗ Требуется изменение архитектуры +- ❗ Есть сложные зависимости + +#### 3. 📋 Планирование +**Обязательная структура плана:** +``` +## План реализации: [название] + +### Этап 1: [название этапа] +**Технология:** Java/Go/Python/Angular +**Файлы:** список файлов для изменения +**Изменения:** конкретные изменения + +### Риски и предосторожности: +- [Риск]: [способ минимизации] +``` + +#### 4. ✅ Подтверждение плана +> [!important] Критически важно +> ИИ НЕ НАЧИНАЕТ реализацию без явного подтверждения плана пользователем + +#### 5. ⚡ Реализация +Следование утверждённому плану с соблюдением всех стандартов. + +--- + +## Стандарты кодирования по языкам + +### ☕ Java (Spring Boot) + +**Именование:** +- Классы: `UserService`, `OrderRepository` (PascalCase) +- Методы: `getUserById`, `calculateTotal` (camelCase) +- Константы: `MAX_RETRY_ATTEMPTS` (UPPER_SNAKE_CASE) + +**Архитектура:** +``` +@RestController → @Service → @Repository +``` + +**Ключевые принципы:** +- JavaDoc для публичных методов +- Stream API для коллекций +- Обязательная обработка исключений +- Bean Validation (@Valid, @NotNull) + +### 🐹 Go + +**Именование:** +- Пакеты: `userservice`, `orderrepo` (lowercase) +- Функции: `GetUserByID` (экспорт), `calculateTotal` (внутренние) +- Переменные: `userName`, `totalAmount` (camelCase) + +**Идиомы:** +- Handle errors explicitly +- Use interfaces for abstractions +- Prefer composition over inheritance +- Channels for goroutine communication + +### 🐍 Python + +**Именование:** +- Классы: `UserService`, `OrderRepository` (PascalCase) +- Функции: `get_user_by_id`, `calculate_total` (snake_case) +- Константы: `MAX_RETRY_ATTEMPTS` (UPPER_SNAKE_CASE) + +**Требования:** +- Type hints обязательны +- Docstrings для публичных функций +- Follow PEP 8 +- Максимум 100 строк в функции + +### 🅰️ Angular/TypeScript + +**Именование:** +- Компоненты: `user-profile.component.ts` (kebab-case) +- Сервисы: `user-data.service.ts` (kebab-case) +- Классы: `UserProfile`, `UserDataService` (PascalCase) + +**Архитектура:** +``` +Components → Services → Models +Feature Modules + Shared Module + Core Module +``` + +--- + +## Шаблоны коммуникации + +### 🎯 Постановка задачи для ИИ + +```markdown +🎯 ЗАДАЧА: [краткое описание] + +📝 ОПИСАНИЕ: +[детальное описание] + +🔧 ТЕХНИЧЕСКИЙ КОНТЕКСТ: +- Язык/фреймворк: [Java Spring/Go/Python/Angular] +- Модуль: [конкретный модуль] +- Связанные компоненты: [если есть] + +📋 ТРЕБОВАНИЯ: +- [Функциональное требование 1] +- [Нефункциональное требование] + +🚫 ОГРАНИЧЕНИЯ: +- [Ограничение 1] +- [Ограничение 2] +``` + +### 📋 Ожидаемый ответ ИИ + +```markdown +📊 АНАЛИЗ ЗАДАЧИ +[понимание задачи и контекста] + +🔧 ДЕКОМПОЗИЦИЯ (если нужна) +[разбивка на подзадачи] + +📋 ПЛАН РЕАЛИЗАЦИИ +### Этап 1: [название] +[детали этапа] + +⚠️ ПОТЕНЦИАЛЬНЫЕ РИСКИ: +[список рисков и способов их минимизации] + +❓ Готов приступить к реализации? +``` + +--- + +## Практическое применение + +### 🚀 Быстрый старт нового проекта + +1. **Создание структуры:** +```bash +mkdir -p .ai-instructions +touch .cursorrules .claudeproject +``` + +2. **Заполнение инструкций:** + - [[#project-context.md]] - описание проекта + - [[#coding-standards.md]] - стандарты языков + - [[#architecture.md]] - архитектурные решения + +3. **Первая задача:** + - Используй шаблон постановки задачи + - Дождись анализа и плана от ИИ + - Подтверди план перед реализацией + +### 🔄 Интеграция в существующий проект + +1. **Анализ кодовой базы:** + - Изучи существующую архитектуру + - Определи используемые паттерны + - Выяви стандарты именования + +2. **Создание инструкций:** + - Задокументируй текущее состояние + - Опиши желаемые стандарты + - Укажи принципы миграции + +3. **Постепенное внедрение:** + - Применяй стандарты к новому коду + - Рефактори старый код по возможности + - Обновляй инструкции по мере развития + +--- + +## Преимущества системы + +### ✅ Для разработчика + +- **Экономия времени:** не нужно объяснять контекст каждый раз +- **Консистентность:** единые стандарты во всех проектах +- **Качество:** ИИ следует лучшим практикам автоматически +- **Масштабируемость:** легко адаптируется под новые проекты + +### ✅ Для команды + +- **Единые стандарты:** все следуют одним правилам +- **Быстрое onboarding:** новые разработчики быстрее включаются +- **Предсказуемость:** понятно, как будет выглядеть код +- **Maintenance:** легче поддерживать кодовую базу + +### ✅ Для ИИ-агентов + +- **Контекст:** полное понимание проекта и требований +- **Эффективность:** сразу генерируют качественный код +- **Последовательность:** следуют установленным паттернам +- **Автономность:** меньше уточняющих вопросов + +--- + +## Связанные заметки + +- [[Claude Code]] - настройка и использование +- [[Cursor]] - интеграция в workflow +- [[Java Development]] - специфика разработки на Java +- [[Go Development]] - особенности работы с Go +- [[Python Development]] - стандарты Python проектов +- [[Angular Development]] - фронтенд разработка +- [[Code Review Process]] - процесс проверки кода +- [[Project Architecture]] - архитектурные паттерны + +--- + +## Чек-лист для внедрения + +### Новый проект +- [ ] Создана структура `.ai-instructions/` +- [ ] Настроены `.cursorrules` и `.claudeproject` +- [ ] Заполнен контекст проекта +- [ ] Определены стандарты кодирования +- [ ] Описана архитектура +- [ ] Проведена первая задача по новому процессу + +### Существующий проект +- [ ] Проанализирована текущая кодовая база +- [ ] Созданы инструкции на основе существующих паттернов +- [ ] Настроены конфигурационные файлы +- [ ] Протестирован процесс на простой задаче +- [ ] Обновлена документация проекта +- [ ] Команда ознакомлена с новым процессом + +--- + +> [!success] Результат +> Система унифицированных инструкций обеспечивает консистентную, качественную и эффективную разработку с ИИ-агентами на всех используемых технологиях. \ No newline at end of file