second-mind-aep/⚙️ Техническое/Унификация разработки с ИИ-агентами.md

#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

# Процесс: АНАЛИЗ → ДЕКОМПОЗИЦИЯ → ПЛАН → ПОДТВЕРЖДЕНИЕ → РЕАЛИЗАЦИЯ
# Языки: Java (Spring), Go, Python (FastAPI/Django), Angular
# Стандарты: читай .ai-instructions/coding-standards.md

.claudeproject

{
  "instructions": [
    "ОБЯЗАТЕЛЬНЫЙ ПРОЦЕСС: АНАЛИЗ → ДЕКОМПОЗИЦИЯ → ПЛАН → ПОДТВЕРЖДЕНИЕ → РЕАЛИЗАЦИЯ",
    "Читай контекст из .ai-instructions/ перед работой"
  ]
}

---

Основной рабочий процесс

🎯 Пятиэтапный процесс

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

---

Шаблоны коммуникации

🎯 Постановка задачи для ИИ

🎯 ЗАДАЧА: [краткое описание]

📝 ОПИСАНИЕ:
[детальное описание]

🔧 ТЕХНИЧЕСКИЙ КОНТЕКСТ:
- Язык/фреймворк: [Java Spring/Go/Python/Angular]
- Модуль: [конкретный модуль]
- Связанные компоненты: [если есть]

📋 ТРЕБОВАНИЯ:
- [Функциональное требование 1]
- [Нефункциональное требование]

🚫 ОГРАНИЧЕНИЯ:
- [Ограничение 1]
- [Ограничение 2]

📋 Ожидаемый ответ ИИ

📊 АНАЛИЗ ЗАДАЧИ
[понимание задачи и контекста]

🔧 ДЕКОМПОЗИЦИЯ (если нужна)
[разбивка на подзадачи]

📋 ПЛАН РЕАЛИЗАЦИИ
### Этап 1: [название]
[детали этапа]

⚠️ ПОТЕНЦИАЛЬНЫЕ РИСКИ:
[список рисков и способов их минимизации]

❓ Готов приступить к реализации?

---

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

🚀 Быстрый старт нового проекта

1. Создание структуры:

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] Результат Система унифицированных инструкций обеспечивает консистентную, качественную и эффективную разработку с ИИ-агентами на всех используемых технологиях.