vault backup: 2025-09-09 14:01:38
This commit is contained in:
Andrey Epifancev
333
⚙️ Техническое/Унификация разработки с ИИ-агентами.md
Normal file
333
⚙️ Техническое/Унификация разработки с ИИ-агентами.md
Normal file
@@ -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] Результат
|
||||||
|
> Система унифицированных инструкций обеспечивает консистентную, качественную и эффективную разработку с ИИ-агентами на всех используемых технологиях.
|
||||||
Reference in New Issue
Block a user