371 lines
14 KiB
Markdown
371 lines
14 KiB
Markdown
---
|
||
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"
|
||
---RetryClaude can make mistakes. Please double-check responses.
|
||
|
||
---
|
||
|
||
## Проблема
|
||
|
||
При работе с множественными проектами на разных языках программирования ([[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] Результат
|
||
> Система унифицированных инструкций обеспечивает консистентную, качественную и эффективную разработку с ИИ-агентами на всех используемых технологиях. |