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