vault backup: 2025-09-09 14:05:58
This commit is contained in:
Andrey Epifancev
369
⚙️ Техническое/🤖 Унификация разработки с ИИ-агентами.md
Normal file
369
⚙️ Техническое/🤖 Унификация разработки с ИИ-агентами.md
Normal file
@@ -0,0 +1,369 @@
|
||||
---
|
||||
title: Унификация разработки с ИИ-агентами
|
||||
created: 2025-09-09
|
||||
modified: 2025-09-09
|
||||
status: Активная практика
|
||||
type: Руководство
|
||||
category: Development
|
||||
tags:
|
||||
- ai-development
|
||||
- coding-standards
|
||||
- workflow
|
||||
- productivity
|
||||
- best-practices
|
||||
aliases:
|
||||
- AI Development Guidelines
|
||||
- ИИ инструкции разработки
|
||||
- Стандарты кода с ИИ
|
||||
related:
|
||||
- "[[Claude Code]]"
|
||||
- "[[Cursor]]"
|
||||
- "[[Java Development]]"
|
||||
- "[[Go Development]]"
|
||||
- "[[Python Development]]"
|
||||
- "[[Angular Development]]"
|
||||
- "[[Code Review Process]]"
|
||||
- "[[Project Architecture]]"
|
||||
technologies:
|
||||
- Java
|
||||
- Go
|
||||
- Python
|
||||
- Angular
|
||||
- Spring Boot
|
||||
- FastAPI
|
||||
- Django
|
||||
tools:
|
||||
- Claude Code
|
||||
- Cursor
|
||||
- Git
|
||||
priority: high
|
||||
review_date: 2025-12-09
|
||||
author: Personal Knowledge Base
|
||||
version: "1.0"
|
||||
---
|
||||
|
||||
## Проблема
|
||||
|
||||
При работе с множественными проектами на разных языках программирования ([[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