Все говорят: «возьми любой AI-кодер, подключи к проекту, и будет магия». Я тоже так думал, а потом понял, что этого мало. И пришлось учиться этим пользоваться по-нормальному.
Harness engineering — это новая дисциплина проектирования сред, ограничений и циклов обратной связи, которые делают AI-агентов надёжными в производстве. Это не модное слово и не очередной фреймворк. Это здравый смысл, применённый к работе с AI-агентами.
В этой статье разберем:
Harness дословно переводится как «упряжь». Метафора грубая, но точная: это всё, что помогает агенту тянуть в нужную сторону и не сваливаться в кювет.
Ключевое различие:
| Промпт | Harness |
|---|---|
| Разовая инструкция | Система |
| Работает в одной сессии | Работает между сессиями |
| Забывается после завершения | Сохраняется в репозитории |
| Зависит от памяти модели | Зависит от инфраструктуры |
Mitchell Hashimoto (создатель Terraform, Vagrant) сформулировал принцип: если агент совершает ошибку, ты не просто исправляешь результат, а создаёшь условие, при котором эта ошибка больше не повторится .
OpenAI в своих внутренних экспериментах с Codex пришли к тому же выводу в масштабе организации: вся команда строила продукт руками агентов, а люди только «рулили» .
Полноценный harness включает четыре взаимосвязанных компонента:
1. Документация для агента
2. Скрипты и инструменты
3. Архитектурные ограничения
4. Машинно-доступная обратная связь
Если у вас подписка на любой AI-кодер, большая часть этих денег должна идти не на новые фичи. А на подготовку проекта к тому, чтобы AI мог в нём эффективно работать. На ваши обсуждения с агентом архитектуры, кейсов, краевых случаев, написание специфкаций, планов. Их обуждение, ревизия, критика. И только потом уже код и его совместная отладка.
Распределение бюджета времени:
Формула: AI в первую очередь не для фичей. AI для подготовки продукта к возможностям AI и для наведения порядка.
Традиционные спецификации написаны для людей. Они предполагают:
AI-агент не обладает этими способностями в той же мере. Для агента спецификация должна быть:
Вот рабочий шаблон, который можно использовать:
# SPEC: [Название задачи]
## ID
`SPEC-2025-001`
## Статус
`draft` | `approved` | `in_progress` | `completed` | `rejected`
## Контекст
**Проблема:** [Какую проблему решаем]
**Пользователь:** [Кто использует эту функцию]
**Сценарий:** [Описание пользовательского сценария]
## Требования
### Функциональные
- [ ] Требование 1 (верифицируемое)
- [ ] Требование 2 (верифицируемое)
- [ ] Требование 3 (верифицируемое)
### Нефункциональные
- Производительность: [метрики]
- Безопасность: [требования]
- Совместимость: [браузеры, версии, API]
## Архитектурные ограничения
**Запрещено:**
- Изменять файлы: [список]
- Использовать библиотеки: [список]
- Менять структуру: [описание]
**Обязательно:**
- Следовать паттерну: [название]
- Использовать интерфейс: [название]
- Покрыть тестами: [минимальный %]
## Входные данные[Примеры входных данных с граничными случаями]
## Ожидаемый результат[Примеры выходных данных]
## Критерии приёмки
- [ ] Тест X проходит
- [ ] Линтер не выдаёт ошибок
- [ ] Документация обновлена
- [ ] PR ревьюирован
## Связанные документы
- [[ARCH-001]] — Архитектура модуля
- [[TEST-001]] — План тестирования
- [[API-001]] — Спецификация API
## История изменений
| Дата | Версия | Изменение | Автор |
|------|--------|-----------|-------|
| 2025-01-15 | 1.0 | Initial draft | [Имя] |# SPEC: Система кэширования запросов к внешнему API
## ID
`SPEC-2025-003`
## Статус
`approved`
## Контекст
**Проблема:** Текущая система делает 500+ запросов/мин к внешнему Payment API,
что превышает лимит тарифа и вызывает rate limiting ошибки.
**Пользователь:** Сервис обработки платежей, интеграционный слой
**Сценарий:**
1. Пользователь инициирует платёж
2. Система проверяет статус платежа через внешний API
3. При повторных запросах того же платежа используется кэш
4. Кэш инвалидируется при изменении статуса
## Требования
### Функциональные
- [ ] Кэширование ответов API с TTL 300 секунд
- [ ] Инвалидация кэша при получении webhook от платёжной системы
- [ ] Graceful degradation при недоступности кэша
- [ ] Логирование cache hit/miss метрик
### Нефункциональные
- Производительность: p99 < 50ms для cache hit
- Безопасность: кэш не должен содержать PAN данные карт
- Совместимость: Redis 6+, Node.js 18+
## Архитектурные ограничения
**Запрещено:**
- Изменять файлы: `src/payment/gateway.ts`, `src/payment/processor.ts`
- Использовать библиотеки: любые новые зависимости без approval
- Менять структуру директорий `src/payment/`
**Обязательно:**
- Следовать паттерну: Cache-Aside (Lazy Loading)
- Использовать интерфейс: `ICacheProvider` из `src/cache/types.ts`
- Покрыть тестами: минимально 85% coverage новых файлов
## Входные данные
```typescript
// Пример запроса
{
paymentId: "pay_123456",
merchantId: "merch_789",
timestamp: "2025-01-15T10:30:00Z"
}
// Граничный случай: отсутствующий paymentId
{
paymentId: null,
merchantId: "merch_789"
}// Cache hit
{
status: "completed",
amount: 1000,
currency: "RUB",
cached: true,
cacheAge: 120 // секунд
}
// Cache miss
{
status: "completed",
amount: 1000,
currency: "RUB",
cached: false,
cacheAge: 0
}npm run test:unit)npm run test:integration)npm run lint)npm run build)docs/cache/ обновлена| Дата | Версия | Изменение | Автор |
|---|---|---|---|
| 2025-01-15 | 1.0 | Initial draft | AI Agent |
| 2025-01-16 | 1.1 | Добавлены граничные случаи | Developer |
| 2025-01-17 | 1.2 | Approved после ревью | Tech Lead |
### 2.4 Как работать со спецификацией вместе с агентом
**Шаг 1: Создание черновика**Задача: Создай черновик спецификации SPEC-2025-004 для функции «Экспорт отчётов в PDF». Используй шаблон из docs/templates/spec-template.md.
Включи:
Шаг 2: Уточнение требований
Задача: Проанализируй SPEC-2025-004 и выяви:
1. Неоднозначные формулировки
2. Отсутствующие граничные случаи
3. Противоречия с существующей архитектурой (см. ARCH-001)
Предложи исправления в формате diff.Шаг 3: Валидация перед началом разработки
Задача: Проверь SPEC-2025-004 на полноту:
1. Все ли требования верифицируемы?
2. Есть ли тесты для каждого требования?
3. Соответствуют ли архитектурные ограничения текущей кодовой базе?
Создай чек-лист валидации.Структура директорий:
docs/
├── specs/
│ ├── active/ # Активные спецификации
│ │ ├── SPEC-2025-001.md
│ │ └── SPEC-2025-002.md
│ ├── completed/ # Завершённые
│ │ └── SPEC-2024-045.md
│ └── rejected/ # Отклонённые
│ └── SPEC-2024-012.md
├── templates/
│ ├── spec-template.md
│ └── arch-template.md
└── registry.json # Реестр всех спецификацийregistry.json:
{
"specifications": [
{
"id": "SPEC-2025-001",
"title": "Система кэширования запросов",
"status": "completed",
"created": "2025-01-15",
"completed": "2025-01-25",
"agent": "claude-sonnet-4",
"developer": "ivan.petrov",
"files_changed": 12,
"tests_added": 34
}
]
}Anthropic рекомендует держать CLAUDE.md под 200 строк на файл . Длинные инструкции быстро превращаются в шум .
Ключевые принципы:
AGENTS.md как карта-оглавление — не храните всё в одном файле, используйте ссылки на структурированные docs/ внутри репозитория
Конкретика вместо абстракций — не «пиши чистый код», а «запускай npm run lint после каждого изменения в src/»
Машинная читаемость — если агент не может получить знание во время работы, для него этого знания не существует
Вот полная структура, которую я использую:
# AGENTS.md — Руководство для AI-агентов
## Быстрый старт
```bash
# Установка зависимостей
npm install
# Запуск dev-сервера
npm run dev
# Запуск тестов
npm run test:unit
npm run test:integration
# Линтинг
npm run lint
npm run lint:fixsrc/
├── api/ # API endpoints
├── services/ # Бизнес-логика
├── models/ # Типы данных и схемы
├── utils/ # Утилиты
├── tests/ # Тесты
└── config/ # Конфигурацияuser-service.ts)UserService)getUserById)MAX_RETRY_COUNT)// ✅ Правильно
import { UserService } from '@/services/user-service'
import type { User } from '@/models/user'
// ❌ Неправильно
import UserService from '../services/UserService'// ✅ Правильно
try {
await userService.getUser(id)
} catch (error) {
if (error instanceof NotFoundError) {
logger.warn(`User ${id} not found`)
throw error
}
logger.error('Unexpected error', { error })
throw new InternalError('Failed to get user')
}| Команда | Описание | Когда использовать |
|---|---|---|
npm run test:unit |
Unit тесты | После каждого изменения |
npm run test:integration |
Integration тесты | Перед коммитом |
npm run lint |
Проверка стиля | После каждого изменения |
npm run typecheck |
Проверка типов | Перед коммитом |
npm run build |
Сборка | Перед PR |
Доступные skills находятся в .claude/agents/:
code-review — автоматическое ревью кодаtest-generator — генерация тестовrefactor — рефакторинг с сохранением поведенияdocs-update — обновление документацииsrc/legacy/ без approvalЕсли ты обнаружил ошибку или недостающую информацию в этом файле:
Вместо одного большого AGENTS.md используйте модульную структуру:
docs/agents/
├── README.md # Главная точка входа (AGENTS.md)
├── conventions/
│ ├── naming.md # Соглашения по именованию
│ ├── error-handling.md
│ └── logging.md
├── architecture/
│ ├── overview.md
│ ├── modules/
│ │ ├── auth.md
│ │ ├── payment.md
│ │ └── notification.md
│ └── decisions/
│ └── ADR-001.md
├── workflows/
│ ├── new-feature.md
│ ├── bug-fix.md
│ └── hotfix.md
└── tools/
├── available-commands.md
└── scripts.mdREADME.md (главный AGENTS.md):
# Руководство для AI-агентов
Это оглавление. Реальная документация находится в поддиректориях.
## Быстрая навигация
- [Конвенции кода](./conventions/naming.md)
- [Архитектура](./architecture/overview.md)
- [Рабочие процессы](./workflows/new-feature.md)
- [Инструменты](./tools/available-commands.md)
## Контекст текущей задачи
Перед началом работы проверь:
1. [[./workflows/new-feature.md]] — если создаёшь новую функцию
2. [[./workflows/bug-fix.md]] — если исправляешь баг
3. [[./architecture/overview.md]] — для понимания контекстаКлючевой принцип harness engineering: после каждой ошибки агента обновляй документацию, чтобы ошибка не повторилась.
Пример:
Ошибка: Агент создал файл в неправильной директории.
Действие: Добавь в AGENTS.md:
## Расположение файлов
| Тип файла | Директория | Пример |
|-----------|------------|--------|
| Сервисы | `src/services/` | `src/services/user-service.ts` |
| Контроллеры | `src/api/controllers/` | `src/api/controllers/user-controller.ts` |
| Модели | `src/models/` | `src/models/user.ts` |
| Тесты | `src/tests/` | `src/tests/user-service.test.ts` |
Перед созданием нового файла проверь эту таблицу.Ошибка: Агент не запустил линтер перед коммитом.
Действие: Добавь pre-commit hook и обнови AGENTS.md:
## Pre-commit проверки
Перед каждым коммитом автоматически запускаются:
- `npm run lint` — проверка стиля
- `npm run typecheck` — проверка типов
- `npm run test:unit` — unit тесты
Если проверки не проходят, коммит блокируется.
Не пытайся обойти проверки флагом `--no-verify`.Skill — это не просто промпт. Это целый контекст: какие файлы читать, какому стилю следовать, какие ограничения соблюдать .
Различия:
| Промпт | Skill |
|---|---|
| Одноразовая инструкция | Переиспользуемый шаблон |
| В памяти чата | В файловой системе |
| Забывается после сессии | Доступен в любой сессии |
| Зависит от формулировки | Стандартизирован |
Вот полная структура skill с примерами:
# .claude/agents/code-review.yaml
name: code-review
description: Автоматическое ревью кода перед коммитом
version: 1.2.0
author: team
context:
files:
- "docs/conventions/*.md"
- "docs/architecture/overview.md"
commands:
- "npm run lint"
- "npm run typecheck"
- "npm run test:unit"
instructions: |
Ты — старший разработчик, проводящий code review.
Твоя задача:
1. Проверить код на соответствие конвенциям (см. docs/conventions/)
2. Найти потенциальные баги и уязвимости
3. Проверить покрытие тестами
4. Оценить читаемость и поддерживаемость
Формат отчёта:
```markdown
## Code Review Report
### Файлы изменены
- [список файлов]
### Критические проблемы
- [список с приоритетом P0]
### Предупреждения
- [список с приоритетом P1]
### Рекомендации
- [список с приоритетом P2]
### Статус
✅ APPROVED | ⚠️ APPROVED WITH COMMENTS | ❌ REJECTEDПравила:
examples:
input: "src/services/user-service.ts (новые методы)" output: |
src/services/user-service.ts (+45 lines)
❌ Line 23: Отсутствует обработка ошибки NotFoundError Исправление: добавить try-catch блок
⚠️ Line 15: Метод можно сделать private Причина: используется только внутри класса
💡 Добавить JSDoc для публичных методов
⚠️ APPROVED WITH COMMENTS
triggers:
output_format: markdown max_tokens: 4000
### 4.3 Каталог обязательных skills
Вот минимальный набор skills для любого проекта:
.claude/agents/ ├── code-review.yaml # Ревью кода ├── test-generator.yaml # Генерация тестов ├── refactor.yaml # Рефакторинг ├── docs-update.yaml # Обновление документации ├── security-scan.yaml # Проверка безопасности ├── performance-check.yaml # Проверка производительности ├── migration-helper.yaml # Помощь с миграциями └── onboarding.yaml # Онбординг нового разработчика
### 4.4 Skill: Генератор тестов
```yaml
# .claude/agents/test-generator.yaml
name: test-generator
description: Генерация unit и integration тестов
version: 1.0.0
context:
files:
- "docs/testing/strategy.md"
- "src/tests/**/*.test.ts"
commands:
- "npm run test:unit"
- "npm run test:coverage"
instructions: |
Ты — инженер по тестированию. Твоя задача — создавать полные,
надёжные тесты для нового и изменённого кода.
Принципы:
1. Покрытие: минимально 85% для новых файлов
2. Изоляция: каждый тест независим
3. Читаемость: название теста описывает сценарий
4. Граничные случаи: null, undefined, пустые строки, максимумы
Структура теста:
```typescript
describe('UserService', () => {
describe('getUserById', () => {
it('должен вернуть пользователя по valid ID', async () => {
// Arrange
const userId = 'user_123'
mockRepository.findById.mockResolvedValue(expectedUser)
// Act
const result = await service.getUserById(userId)
// Assert
expect(result).toEqual(expectedUser)
expect(mockRepository.findById).toHaveBeenCalledWith(userId)
})
it('должен выбросить NotFoundError для несуществующего ID', async () => {
// Arrange
const userId = 'user_999'
mockRepository.findById.mockResolvedValue(null)
// Act & Assert
await expect(service.getUserById(userId))
.rejects
.toThrow(NotFoundError)
})
})
})Процесс:
examples:
input: "src/services/payment-service.ts (новый файл, 150 строк)" output: | Создано тестов: 12 Покрытие: 89%
Файлы:
src/tests/payment-service.test.ts (новый)
Сценарии покрыты: ✅ processPayment — happy path ✅ processPayment — недостаточный баланс ✅ processPayment — недоступен внешний API ✅ refundPayment — полный возврат ✅ refundPayment — частичный возврат ✅ getPaymentStatus — существующий платёж ✅ getPaymentStatus — несуществующий платёж ...
triggers:
output_format: code
### 4.5 Skill: Рефакторинг
```yaml
# .claude/agents/refactor.yaml
name: refactor
description: Рефакторинг кода с сохранением поведения
version: 1.1.0
context:
files:
- "docs/architecture/overview.md"
- "docs/conventions/*.md"
commands:
- "npm run test:unit"
- "npm run test:integration"
- "npm run lint"
instructions: |
Ты — старший разработчик, специализирующийся на рефакторинге.
Правила рефакторинга:
1. Поведение не меняется — все тесты должны проходить
2. Маленькие шаги — один PR = одна цель рефакторинга
3. Тесты сначала — если тестов нет, создай их перед рефакторингом
4. Документация обновляется — если изменился публичный API
Типы рефакторинга:
### Извлечение метода
Когда: код повторяется или метод слишком длинный (>50 строк)
Пример:
```typescript
// Было
function processOrder(order: Order) {
// 60 строк кода...
}
// Стало
function processOrder(order: Order) {
validateOrder(order)
calculateTotal(order)
applyDiscounts(order)
}Когда: имя не отражает назначение Правило: переименовывай везде, где используется
Когда: вложенные if > 3 уровней Пример:
// Было
if (user) {
if (user.active) {
if (user.verified) {
return true
}
}
}
return false
// Стало
return user?.active && user.verifiedПроцесс:
triggers:
output_format: code
### 4.6 Как создавать новые skills
**Шаг 1: Идентифицируй повторяющуюся задачу**Ведите журнал задач, которые вы делаете чаще 3 раз в неделю:
Шаг 2: Документируй процесс
Запиши каждый шаг, который ты делаешь вручную:
1. Какие файлы читаешь
2. Какие команды запускаешь
3. Какие решения принимаешь
4. Какой формат вывода ожидаешьШаг 3: Создай skill
name: [название]
description: [одно предложение]
context:
files: [список файлов для чтения]
commands: [список команд для запуска]
instructions: |
[Подробные инструкции]
examples:
- input: [пример входа]
output: [пример выхода]
triggers: [слова-триггеры]Шаг 4: Протестируй skill
1. Запусти skill на реальном коде
2. Проверь результат
3. Уточни инструкции
4. Повтори пока результат не станет стабильнымШаг 5: Добавь в каталог
Обнови docs/agents/README.md с новым skill
Добавь примеры использованияАгент без архитектурных ограничений уходит в фантазии: создаёт файлы где попало, использует не те паттерны, ломает существующие зависимости .
Проблемы без архитектуры:
Фаза 1: Контекст
Задача: Я планирую добавить систему уведомлений в проект.
Перед тем как предлагать решения, ответь на вопросы:
1. Какие модули уже существуют в проекте? (см. docs/architecture/overview.md)
2. Какие есть ограничения по инфраструктуре?
3. Какие паттерны используются для похожих задач?
Не предлагай решения пока не поймёшь контекст.Фаза 2: Анализ вариантов
Задача: На основе контекста предложи 3 варианта архитектуры
для системы уведомлений.
Для каждого варианта укажи:
- Преимущества
- Недостатки
- Сложность реализации (S/M/L/XL)
- Влияние на существующий код
- Необходимые новые зависимости
Формат: таблица сравнения.Фаза 3: Рекомендация
Задача: На основе анализа выбери рекомендуемый вариант.
Обоснуй выбор:
1. Почему этот вариант лучше других для нашего контекста?
2. Какие риски и как их минимизировать?
3. Какой план миграции если нужно изменить существующий код?
Создай ADR (Architecture Decision Record).Фаза 4: Детализация
Задача: Для выбранного варианта создай:
1. Диаграмму компонентов (Mermaid формат)
2. Список новых файлов с путями
3. Интерфейсы для ключевых абстракций
4. План реализации по шагам
Каждый шаг должен быть независимой задачей, которую
можно выполнить за одну сессию.# ADR-003: Система уведомлений
## Статус
`proposed` | `accepted` | `rejected` | `deprecated`
## Контекст
Требуется система уведомлений для:
- Email уведомления пользователям
- Push уведомления в приложение
- Webhook для внешних систем
Текущее состояние: уведомления разбросаны по коду, нет единого интерфейса.
## Решение
Использовать паттерн Observer с централизованным NotificationService.
Компоненты:┌─────────────────┐ │ NotificationService │ ├─────────────────┤ │ EmailProvider │ │ PushProvider │ │ WebhookProvider │ └─────────────────┘
## Последствия
### Положительные
- Единый интерфейс для всех типов уведомлений
- Легко добавлять новые каналы
- Централизованное логирование
### Отрицательные
- Новая зависимость (nodemailer)
- Требуется миграция существующего кода
### Нейтральные
- Увеличение количества файлов на 8
## План реализации
1. Создать интерфейс INotificationProvider
2. Реализовать EmailProvider
3. Создать NotificationService
4. Мигрировать существующие уведомления
5. Добавить тесты
## Ссылки
- [[SPEC-2025-005]] — Спецификация системы уведомлений
- [[docs/architecture/patterns/observer.md]] — Паттерн Observer
## История
| Дата | Статус | Автор |
|------|--------|-------|
| 2025-01-20 | proposed | AI Agent |
| 2025-01-21 | accepted | Tech Lead |Агент может генерировать диаграммы в формате Mermaid:
flowchart TD
subgraph Client["Клиент"]
Web[Веб-приложение]
Mobile[Мобильное приложение]
end
subgraph API["API Gateway"]
Gateway[API Gateway]
Auth[Auth Service]
end
subgraph Services["Сервисы"]
User[User Service]
Payment[Payment Service]
Notification[Notification Service]
end
subgraph Data["Данные"]
DB[(PostgreSQL)]
Cache[(Redis)]
Queue[RabbitMQ]
end
Web --> Gateway
Mobile --> Gateway
Gateway --> Auth
Gateway --> User
Gateway --> Payment
Gateway --> Notification
User --> DB
User --> Cache
Payment --> DB
Payment --> Queue
Notification --> Queue
Notification --> CacheПромпт для генерации:
Задача: Создай Mermaid диаграмму архитектуры для системы уведомлений.
Требования:
- Покажи все компоненты из ADR-003
- Включи существующие сервисы (User, Payment)
- Покажи потоки данных между компонентами
- Используй subgraph для группировки
- Добавь базы данных и очередь сообщений
Формат: Mermaid flowchart TDПеред началом реализации агент должен проверить архитектуру:
Задача: Проведи валидацию архитектуры из ADR-003.
Проверь:
1. Соответствие существующим паттернам (docs/architecture/patterns/)
2. Совместимость с текущей инфраструктурой
3. Потенциальные точки отказа
4. Масштабируемость решения
5. Безопасность (аутентификация, авторизация, данные)
Создай отчёт с рисками и рекомендациями по их минимизации.
Формат:
## Валидация архитектуры ADR-003
### ✅ Соответствие паттернам
[описание]
### ⚠️ Риски
| Риск | Вероятность | Влияние | Митигация |
|------|-------------|---------|-----------|
| [риск] | Low/Med/High | Low/Med/High | [как минимизировать] |
### 📋 Рекомендации
[список]Уровень 1: Roadmap (квартал)
Q1 2025 — Система уведомлений
├── Январь: Проектирование и ADR
├── Февраль: Базовая реализация
└── Март: Интеграция и тестированиеУровень 2: Sprint Plan (2 недели)
Sprint 3 (20.01-31.01)
├── SPEC-2025-005: Спецификация уведомлений
├── ADR-003: Архитектурное решение
├── TASK-001: Интерфейс INotificationProvider
├── TASK-002: EmailProvider реализация
├── TASK-003: Базовые тестыУровень 3: Task Plan (день/сессия)
TASK-001: Интерфейс INotificationProvider
├── Шаг 1: Анализ (15 мин)
├── Шаг 2: Определение методов (30 мин)
├── Шаг 3: Создание файла (15 мин)
├── Шаг 4: Unit тесты (30 мин)
└── Шаг 5: Документация (15 мин)# PLAN: TASK-001 — Интерфейс INotificationProvider
## Контекст
Часть реализации ADR-003 (Система уведомлений)
## Цель
Создать интерфейс для провайдеров уведомлений
## Входные данные
- ADR-003: docs/architecture/decisions/ADR-003.md
- Существующие интерфейсы: src/services/*.ts
- Конвенции: docs/conventions/naming.md
## Шаги
### Шаг 1: Анализ (15 мин)
- [ ] Изучить ADR-003
- [ ] Найти похожие интерфейсы в коде
- [ ] Выявить общие паттерны
### Шаг 2: Проектирование (30 мин)
- [ ] Определить методы интерфейса
- [ ] Определить типы данных
- [ ] Продумать обработку ошибок
### Шаг 3: Реализация (15 мин)
- [ ] Создать файл src/notifications/types.ts
- [ ] Добавить интерфейс INotificationProvider
- [ ] Добавить типы Notification, NotificationResult
### Шаг 4: Тестирование (30 мин)
- [ ] Создать src/tests/notifications/types.test.ts
- [ ] Проверить TypeScript компиляцию
- [ ] Запустить npm run typecheck
### Шаг 5: Документация (15 мин)
- [ ] Добавить JSDoc к интерфейсу
- [ ] Обновить docs/architecture/modules/notification.md
- [ ] Добавить пример использования
## Критерии завершения
- [ ] Файл создан в правильной директории
- [ ] TypeScript компилируется без ошибок
- [ ] Тесты проходят
- [ ] JSDoc добавлен
- [ ] PR создан
## Риски
- Конфликт имён с существующими типами
- Несовместимость с будущими провайдерами
## Митигация
- Проверить все существующие типы перед созданием
- Сделать интерфейс максимально общимПеред началом сессии:
Задача: Загрузи план TASK-001 и подтверди понимание.
1. Перечисли все шаги плана
2. Укажи какие файлы нужно прочитать
3. Укажи какие команды нужно запустить
4. Подтверди критерии завершения
Если что-то непонятно — задай вопросы перед началом.После каждого шага:
Задача: Шаг 1 завершён.
1. Отметь выполненные пункты в плане
2. Покажи результат шага
3. Подтверди готовность к шагу 2
4. Если обнаружились проблемы — сообщи перед продолжениемВ конце сессии:
Задача: Сессия завершена.
1. Отметь все выполненные пункты плана
2. Перечисли созданные/изменённые файлы
3. Покажи результат запуска тестов
4. Укажи что осталось на следующую сессию
5. Создай summary для передачи контекстаПроблема: контекст утекает между сессиями .
Решение: Session Summary
# SESSION SUMMARY: TASK-001
## Дата
2025-01-20 14:00-15:30
## Выполнено
- ✅ Шаг 1: Анализ (15 мин)
- ✅ Шаг 2: Проектирование (30 мин)
- ✅ Шаг 3: Реализация (15 мин)
- ⏸️ Шаг 4: Тестирование (частично)
- ⏹️ Шаг 5: Документация (не начато)
## Созданные файлы
- src/notifications/types.ts (новый, 45 строк)
## Изменённые файлы
- none
## Проблемы
- TypeScript ошибка в строке 23: тип NotificationResult не экспортирован
- Нужно исправить перед продолжением
## Следующие шаги
1. Исправить экспорт NotificationResult
2. Завершить тестирование (Шаг 4)
3. Добавить документацию (Шаг 5)
4. Создать PR
## Контекст для следующей сессии
Открытые файлы:
- src/notifications/types.ts
- src/tests/notifications/types.test.ts (частично)
Команды для запуска:
- npm run typecheck (должно пройти после исправления)
- npm run test:unit (для новых тестов)Хранение summary:
docs/sessions/
├── 2025-01/
│ ├── 2025-01-20-TASK-001.md
│ └── 2025-01-21-TASK-001.md
└── 2025-02/Большой PR = много проблем. Маленький PR = быстрое ревью, меньше багов.
Правила:
Шаг 1: Подготовка окружения
Задача: Подготовь окружение для разработки TASK-001.
1. Создай новую ветку: feature/TASK-001-notification-interface
2. Убедись что все тесты проходят в main
3. Запусти npm run lint, npm run typecheck
4. Создай файл плана в docs/plans/TASK-001.md
Команды:
```bash
git checkout main
git pull origin main
git checkout -b feature/TASK-001-notification-interface
npm run test:unit
npm run lint
**Шаг 2: Реализация**Задача: Реализуй Шаг 3 плана TASK-001.
Требования:
Шаг 3: Тестирование
Задача: Реализуй Шаг 4 плана TASK-001.
1. Создай файл: src/tests/notifications/types.test.ts
2. Напиши тесты для типов:
- Проверка структуры Notification
- Проверка структуры NotificationResult
- Проверка интерфейса INotificationProvider
3. Запусти npm run test:unit
4. Проверь coverage: npm run test:coverage
Требования:
- Минимальное покрытие 85%
- Все тесты должны быть независимы
- Используй паттерн Arrange-Act-AssertШаг 4: Документация
Задача: Реализуй Шаг 5 плана TASK-001.
1. Проверь что JSDoc добавлен ко всем элементам
2. Обнови docs/architecture/modules/notification.md
3. Добавь пример использования
4. Запусти npm run docs:build (если есть)
Требования:
- Пример должен быть рабочим (можно скопировать и запустить)
- Опиши все методы интерфейса
- Укажи возможные ошибкиШаг 5: Code Review
Задача: Подготовь PR для TASK-001.
1. Запусти все проверки:
- npm run lint
- npm run typecheck
- npm run test:unit
- npm run test:integration
2. Создай PR с описанием:
- Ссылка на SPEC-2025-005
- Ссылка на ADR-003
- Ссылка на план TASK-001
- Список изменений
- Скриншот coverage
3. Запроси ревью у tech lead
4. Исправь замечания из ревью
5. После approval — mergе в main# Pre-commit Checklist
## Код
- [ ] npm run lint проходит без ошибок
- [ ] npm run typecheck проходит без ошибок
- [ ] npm run test:unit проходит (все тесты зелёные)
- [ ] npm run test:integration проходит (если затронуты интеграции)
- [ ] Coverage не уменьшился (npm run test:coverage)
## Документация
- [ ] JSDoc добавлен к новым публичным элементам
- [ ] AGENTS.md обновлён (если изменились конвенции)
- [ ] README.md обновлён (если изменился публичный API)
## Git
- [ ] Ветка названа по шаблону: feature/TASK-XXX-description
- [ ] Коммиты атомарные (один коммит = одно изменение)
- [ ] Сообщения коммитов следуют конвенции:
feat: добавление новой функции
fix: исправление бага
docs: обновление документации
refactor: рефакторинг без изменения поведения
test: добавление тестов
chore: изменения в сборке, зависимости
## PR
- [ ] Описание PR заполнено
- [ ] Ссылки на SPEC/ADR/PLAN добавлены
- [ ] Reviewers назначены
- [ ] Labels добавленыЕсли задача слишком большая для одной сессии:
Декомпозиция:
Задача: TASK-010 слишком большая (оценка 40 часов).
Разбей на подзадачи по 4-6 часов каждая.
Для каждой подзадачи создай:
1. Отдельный PLAN-XXX
2. Критерии завершения
3. Зависимости от других подзадач
4. Ожидаемый результат
Формат:
TASK-010.1 — [название] (4 часа)
TASK-010.2 — [название] (4 часа)
...Пример декомпозиции:
TASK-010: Система уведомлений (40 часов)
├── TASK-010.1: Интерфейсы и типы (4 часа)
├── TASK-010.2: EmailProvider (6 часов)
├── TASK-010.3: PushProvider (6 часов)
├── TASK-010.4: WebhookProvider (6 часов)
├── TASK-010.5: NotificationService (8 часов)
├── TASK-010.6: Интеграция с существующим кодом (6 часов)
├── TASK-010.7: Тесты интеграции (4 часа)
└── TASK-010.8: Документация и ADR update (4 часа)AI-агенты особенно эффективны для тестирования: они могут генерировать тесты быстрее человека, находить граничные случаи, которые человек упускает .
Уровни тестирования:
┌─────────────────────────────────────┐
│ E2E Tests (10%) │
│ (Playwright, Cypress) │
├─────────────────────────────────────┤
│ Integration Tests (20%) │
│ (API, Database, External) │
├─────────────────────────────────────┤
│ Unit Tests (70%) │
│ (Functions, Classes) │
└─────────────────────────────────────┘# .claude/agents/unit-test-generator.yaml
name: unit-test-generator
description: Генерация unit тестов для функций и классов
version: 1.0.0
context:
files:
- "docs/testing/strategy.md"
- "docs/testing/unit-test-patterns.md"
commands:
- "npm run test:unit"
- "npm run test:coverage"
instructions: |
Ты — инженер по тестированию, специализирующийся на unit тестах.
Принципы:
1. Один тест = одна проверка
2. Тесты независимы (нет порядка выполнения)
3. Тесты быстрые (< 100ms каждый)
4. Тесты читаемые (понятно что тестируется без чтения кода)
Структура теста (AAA):
```typescript
it('должен [ожидаемое поведение] когда [условие]', async () => {
// Arrange — подготовка данных
const input = {...}
mockDependency.mockReturnValue({...})
// Act — вызов тестируемого кода
const result = await functionUnderTest(input)
// Assert — проверка результата
expect(result).toEqual(expected)
expect(mockDependency).toHaveBeenCalledWith(...)
})Граничные случаи которые нужно покрыть:
Таймауты и retry
Процесс:
examples:
input: "src/utils/validator.ts (функция validateEmail)" output: | Создано тестов: 8 Покрытие: 100%
Сценарии: ✅ valid email (standard) ✅ valid email (subdomain) ✅ valid email (plus addressing) ❌ invalid email (no @) ❌ invalid email (no domain) ❌ invalid email (special chars) ❌ invalid email (empty) ❌ invalid email (null)
triggers:
output_format: code
### 8.3 Skill: Генерация integration тестов
```yaml
# .claude/agents/integration-test-generator.yaml
name: integration-test-generator
description: Генерация integration тестов для API и сервисов
version: 1.0.0
context:
files:
- "docs/testing/strategy.md"
- "docs/testing/integration-test-patterns.md"
- "docs/api/openapi.yaml"
commands:
- "npm run test:integration"
- "docker compose up -d test-db"
instructions: |
Ты — инженер по тестированию, специализирующийся на integration тестах.
Принципы:
1. Тесты используют реальную БД (test database)
2. Тесты изолированы (транзакции rollback после каждого теста)
3. Тесты проверяют взаимодействие между компонентами
4. Тесты медленнее unit (< 5 секунд каждый)
Структура integration теста:
```typescript
describe('UserService Integration', () => {
beforeAll(async () => {
await db.connect(TEST_DB_URL)
await db.migrate()
})
beforeEach(async () => {
await db.truncate() // Очистка перед каждым тестом
await seedTestData()
})
afterAll(async () => {
await db.disconnect()
})
it('должен создать пользователя и вернуть ID', async () => {
// Arrange
const userData = {
email: 'test@example.com',
name: 'Test User'
}
// Act
const result = await userService.create(userData)
// Assert
expect(result.id).toBeDefined()
expect(result.email).toBe(userData.email)
// Проверка в БД
const fromDb = await db.users.findById(result.id)
expect(fromDb).toEqual(expect.objectContaining(userData))
})
})Сценарии для API тестов:
triggers:
output_format: code
### 8.4 Skill: Поиск недостающих тестов
```yaml
# .claude/agents/test-gap-analyzer.yaml
name: test-gap-analyzer
description: Анализ покрытия и поиск недостающих тестов
version: 1.0.0
context:
files:
- "coverage/lcov-report/index.html"
- "src/**/*.ts"
- "src/tests/**/*.test.ts"
commands:
- "npm run test:coverage"
instructions: |
Ты — инженер по тестированию, анализирующий покрытие кода.
Задача: Найти файлы и функции без достаточного тестового покрытия.
Процесс:
1. Запусти npm run test:coverage
2. Проанализируй отчёт coverage
3. Найди файлы с coverage < 80%
4. Для каждого файла:
- Выяви нетестированные функции
- Определи приоритет тестирования
- Предложи план добавления тестов
Приоритеты:
- P0: Публичный API без тестов
- P1: Бизнес-логика без тестов
- P2: Утилиты без тестов
- P3: Private методы без тестов (опционально)
Формат отчёта:
```markdown
## Test Gap Analysis
### Файлы требующие внимания
| Файл | Coverage | Приоритет | Нетестированные функции |
|------|----------|-----------|------------------------|
| src/services/payment.ts | 45% | P0 | processPayment, refund |
| src/utils/validator.ts | 60% | P1 | validateEmail, validatePhone |
### План действий
#### payment.ts (P0)
- [ ] Тесты для processPayment (3 теста)
- [ ] Тесты для refund (2 теста)
- [ ] Тесты для ошибок (2 теста)
Оценка: 4 часа
#### validator.ts (P1)
- [ ] Тесты для validateEmail (4 теста)
- [ ] Тесты для validatePhone (3 теста)
Оценка: 2 часаtriggers:
output_format: markdown
### 8.5 TDD с AI-агентом
Test-Driven Development особенно хорошо работает с AI:
**Цикл TDD:**
┌──────────────┐ │ 1. RED │ ← Напиши тест (который падает) └──────┬───────┘ │ ▼ ┌──────────────┐ │ 2. GREEN │ ← Напиши код (чтобы тест прошёл) └──────┬───────┘ │ ▼ ┌──────────────┐ │ 3. REFACTOR│ ← Улучши код (тесты остаются зелёными) └──────┬───────┘ │ ▼ (повтор)
**Промпт для TDD:**Задача: Реализуй функцию calculateDiscount с использованием TDD.
Шаг 1 (RED):
Шаг 2 (GREEN):
Шаг 3 (REFACTOR):
После каждого шага покажи:
Pre-commit hook для тестов:
#!/bin/bash
# .git/hooks/pre-commit
echo "Running tests before commit..."
# Запуск unit тестов для изменённых файлов
CHANGED_FILES=$(git diff --cached --name-only --diff-filter=ACM | grep '\.ts$')
if [ -n "$CHANGED_FILES" ]; then
for file in $CHANGED_FILES; do
test_file="${file/.ts/.test.ts}"
if [ -f "$test_file" ]; then
echo "Running tests for $file..."
npm run test:unit -- --testPathPattern="$test_file"
if [ $? -ne 0 ]; then
echo "❌ Tests failed for $file"
exit 1
fi
else
echo "⚠️ No tests found for $file"
echo "Consider creating $test_file"
fi
done
fi
# Проверка coverage не уменьшился
npm run test:coverage -- --changedSince=main
if [ $? -ne 0 ]; then
echo "❌ Coverage decreased"
exit 1
fi
echo "✅ All tests passed"
exit 0Инструкция для агента в AGENTS.md:
## Pre-commit проверки
Перед каждым коммитом автоматически запускаются:
- Тесты для изменённых файлов
- Проверка что coverage не уменьшился
Если для нового файла нет тестов:
1. Создай тесты перед коммитом
2. Минимальное покрытие 80% для новых файлов
3. Используй skill `unit-test-generator`
Обход проверок флагом `--no-verify` запрещён.Одна модель не может эффективно делать всё. Разные задачи требуют разных моделей .
Распределение задач:
| Задача | Модель | Почему |
|---|---|---|
| Рутинные проверки | Haiku / Sonnet | Дёшево, быстро |
| Архитектурные решения | Opus / GPT-4 | Точность, контекст |
| Code review | Sonnet | Баланс цена/качество |
| Генерация тестов | Sonnet | Понимание кода |
| Рефакторинг | Opus | Сохранение поведения |
# .claude/agents/orchestrator.yaml
name: orchestrator
description: Маршрутизация задач между subagents
version: 1.0.0
subagents:
- name: code-reviewer
model: claude-sonnet-4
max_tokens: 4000
tasks:
- "code review"
- "проверь код"
- "найди баги"
- name: test-writer
model: claude-sonnet-4
max_tokens: 6000
tasks:
- "напиши тесты"
- "test coverage"
- "unit test"
- name: architect
model: claude-opus-4
max_tokens: 8000
tasks:
- "архитектура"
- "ADR"
- "проектирование"
- name: refactoring
model: claude-opus-4
max_tokens: 6000
tasks:
- "рефакторинг"
- "оптимизируй"
- "улучши код"
- name: docs
model: claude-haiku-3
max_tokens: 3000
tasks:
- "документация"
- "README"
- "JSDoc"
routing_rules:
- if: "contains(task, 'review')"
then: "code-reviewer"
- if: "contains(task, 'test')"
then: "test-writer"
- if: "contains(task, 'architect') OR contains(task, 'ADR')"
then: "architect"
- if: "contains(task, 'refactor')"
then: "refactoring"
- if: "contains(task, 'doc')"
then: "docs"
- else: "code-reviewer" # defaultАгент должен работать в песочнице, чтобы не сломать систему разработчика .
.devcontainer/devcontainer.json:
{
"name": "AI Agent Development",
"image": "node:20-alpine",
"features": {
"git": "latest",
"docker-in-docker": "latest"
},
"customizations": {
"vscode": {
"extensions": [
"dbaeumer.vscode-eslint",
"esbenp.prettier-vscode"
]
}
},
"postCreateCommand": "npm install",
"remoteUser": "node",
"mounts": [
"source=${localEnv:HOME}/.claude,target=/home/node/.claude,type=bind"
],
"runArgs": [
"--memory=4g",
"--cpus=2"
]
}Преимущества:
Pre-session hooks:
# .claude/hooks/pre-session.sh
#!/bin/bash
# Инжект git контекста
echo "Current branch: $(git branch --show-current)"
echo "Last commit: $(git log -1 --oneline)"
echo "Uncommitted changes: $(git status --porcelain | wc -l)"
# Запуск линтера на изменённых файлах
echo "Running lint on changed files..."
npm run lint -- --fix
# Проверка типов
echo "Running typecheck..."
npm run typecheckPost-session hooks:
# .claude/hooks/post-session.sh
#!/bin/bash
# Создание session summary
echo "Creating session summary..."
# (скрипт генерирует summary в docs/sessions/)
# Проверка что тесты проходят
echo "Running final test check..."
npm run test:unit
# Коммит изменений (если настроено)
# git add -A
# git commit -m "AI: session changes"Harness — инвестиция времени:
Итого: 8-19 дней начальных инвестиций
Когда окупается:
Когда не окупается:
Метрики до harness:
- Время на задачу: 8 часов
- Время на ревью: 2 часа
- Багов после релиза: 5
- Переделок: 3Метрики после harness:
- Время на задачу: 3 часа
- Время на ревью: 30 минут
- Багов после релиза: 1
- Переделок: 0.5ROI:
Экономия времени: (8+2) - (3+0.5) = 6.5 часов на задачу
Уменьшение багов: 5 → 1 = 80% улучшение
Окупаемость: 80 часов инвестиций / 6.5 часов экономии = 12 задач
Если делаете > 12 задач в месяц — окупается за месяц.Регулярные сессии по наведению порядка окупаются многократно .
Еженедельная cleanup-сессия:
Задача: Проведи cleanup проекта.
Найди и создай PR для:
1. Устаревшие TODO (старше 30 дней)
2. Мёртвый код (не используется > 30 дней)
3. Несогласованные паттерны (отличаются от конвенций)
4. Устаревшие зависимости (npm outdated)
5. Дублирующийся код
Формат отчёта:
## Cleanup Report
### Удалено
- [файлы/функции]
### Обновлено
- [зависимости]
### Исправлено
- [паттерны]
### PR создан
- [ссылка]Автоматизация cleanup:
# .github/workflows/cleanup.yml
name: Weekly Cleanup
on:
schedule:
- cron: '0 9 * * 1' # Каждый понедельник в 9:00
jobs:
cleanup:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Run AI cleanup
run: |
npm install
npx ai-cleanup --output=cleanup-report.md
- name: Create PR
uses: peter-evans/create-pull-request@v5
with:
title: "AI: Weekly cleanup"
body-path: cleanup-report.md
branch: ai-cleanup-${{ github.run_id }}Я анализировал типичные ошибки AI-кодера. Почти все эти ошибки — симптомы слабого harness, а не глупости модели .
Ошибка 1: «Не читает сгенерированный код»
Симптом: Агент генерирует код с ошибками, которые можно было бы поймать линтером.
Причина: Нет автоматических проверок.
Лечение harness:
## Post-generation checks
После каждого изменения кода:
1. npm run lint — проверка стиля
2. npm run typecheck — проверка типов
3. npm run test:unit — проверка тестов
Если любая проверка не прошла:
- Не коммить код
- Исправь ошибки
- Запусти проверки снова
Эти команды запускаются автоматически через pre-commit hook.Ошибка 2: «Расползание скоупа»
Симптом: Агент «на ходу» зарефачит половину кодовой базы.
Причина: Нет архитектурных ограничений.
Лечение harness:
## Архитектурные ограничения
### Запрещено без approval
- Изменять файлы в src/legacy/
- Добавлять новые зависимости
- Менять публичный API без version bump
- Рефакторить больше 5 файлов за один PR
### Обязательно
- Один PR = одна задача из плана
- Максимум 300 строк изменений
- Все изменения должны быть в SPECОшибка 3: «Контекст утекает»
Симптом: Агент забывает что было в прошлой сессии.
Причина: Сессии слишком длинные, нет механизма передачи контекста.
Лечение harness:
## Session management
### Максимальная длительность сессии
- 90 минут для сложных задач
- 45 минут для простых задач
### Session Summary
В конце каждой сессии создавай summary:
- docs/sessions/YYYY-MM-DD-TASK-XXX.md
С summary должно быть понятно:
- Что сделано
- Что осталось
- Какие файлы открыты
- Какие команды запускались
### Persistent memory
Важная информация сохраняется в:
- AGENTS.md — конвенции
- docs/architecture/ — решения
- docs/plans/ — планы задачОшибка 4: «Слепое доверие модели»
Симптом: Код принимается без ревью.
Причина: Нет слоя верификации.
Лечение harness:
## Code review process
### Обязательное ревью
- Все PR требуют минимум 1 approval
- AI-генерированный код требует human review
- Критические изменения требуют 2 approval
### Subagent reviewer
Перед human review запусти:
- skill: code-reviewer
- skill: security-scan
Human ревью фокусируется на:
- Архитектурных решениях
- Бизнес-логике
- Edge cases
AI ревью фокусируется на:
- Стиле кода
- Типах
- ТестахОшибка 5: «Документация устаревает»
Симптом: AGENTS.md направляет агента по старым рельсам.
Причина: Документация не обновляется.
Лечение harness:
## Documentation maintenance
### После каждой ошибки
1. Исправь код
2. Добавь правило в AGENTS.md
3. Создай PR с обновлением документации
### Еженедельная проверка
- Пройтись по AGENTS.md
- Проверить что все ссылки работают
- Удалить устаревшие разделы
- Обновить примеры кода
### Version documentation
AGENTS.md имеет версию:
- v1.0 — initial
- v1.1 — после первого обновления
- v2.0 — после крупных изменений
При обновлении версии создай CHANGELOG.md| Ошибка | Причина | Решение harness | Сложность |
|---|---|---|---|
| Код с ошибками | Нет проверок | Pre-commit hooks | Low |
| Расползание скоупа | Нет ограничений | Архитектурные правила | Medium |
| Утечка контекста | Нет передачи | Session summary | Low |
| Нет ревью | Нет процесса | Mandatory review | Low |
| Устаревшая docs | Нет обновлений | Update after error | Medium |
| Неправильные файлы | Нет структуры | File location rules | Low |
| Новые зависимости | Нет контроля | Dependency policy | Medium |
| Нет тестов | Нет требований | Coverage requirements | Medium |
Если вы сейчас работаете с AI-кодером без обвязки, вот минимальный набор:
День 1: Базовая документация
□ Создать AGENTS.md (одна страница)
- Структура проекта
- Ключевые команды
- Конвенции именования
□ Создать docs/architecture/overview.md
- Основные модули
- Потоки данных
- Ключевые зависимостиДень 2: Команды и скрипты
□ Проверить что команды работают:
- npm run lint
- npm run test:unit
- npm run typecheck
- npm run build
□ Добавить команды в AGENTS.md с примерами:
- Не «запусти тесты», а npm run test:unit -- --watch
- Не «подними окружение», а docker compose up -dДень 3: Первый skill
□ Выбрать самую частую задачу:
- Code review?
- Написание тестов?
- Рефакторинг?
□ Создать skill в .claude/agents/
- Использовать шаблон из статьи
- Добавить примеры
- Протестировать на реальном кодеДень 4: Cleanup-сессия
□ Запустить агента на поиск:
- Устаревшие TODO
- Мёртвый код
- Несогласованные паттерны
□ Создать PR с cleanup
□ Обновить AGENTS.md с найденными проблемамиДень 5: Process
□ Настроить pre-commit hooks
□ Создать шаблон PR
□ Создать шаблон SPEC
□ Создать шаблон PLAN# AI Readiness Checklist
## Документация
- [ ] AGENTS.md существует и актуален
- [ ] Архитектура задокументирована
- [ ] Конвенции кода описаны
- [ ] Команды задокументированы с примерами
## Инфраструктура
- [ ] Линтер настроен и работает
- [ ] Типизация включена (TypeScript)
- [ ] Тесты запускаются одной командой
- [ ] CI/CD пайплайн работает
## Skills
- [ ] Минимум 1 skill создан
- [ ] Skills протестированы на реальном коде
- [ ] Skills задокументированы
## Процесс
- [ ] SPEC шаблон используется
- [ ] PLAN шаблон используется
- [ ] Session summary создаётся
- [ ] Code review обязателен
## Безопасность
- [ ] Secrets не в репозитории
- [ ] DevContainer настроен
- [ ] Ограничения на зависимости
## Готовность
- [ ] Проект будет жить > 6 месяцев
- [ ] Есть время на настройку (8-19 дней)
- [ ] Команда готова к процессуНеделя 1: Фундамент
День 1-2: AGENTS.md и базовая документация
День 3-4: Настройка команд и скриптов
День 5: Первый skill (code-review или test-generator)Неделя 2: Процессы
День 6-7: SPEC и PLAN шаблоны
День 8-9: Session summary процесс
День 10: Pre-commit hooksНеделя 3: Расширение
День 11-12: Второй и третий skill
День 13-14: Subagents конфигурация
День 15: DevContainer настройкаНеделя 4: Оптимизация
День 16-17: Cleanup-сессия
День 18-19: Обновление документации
День 20: Измерение метрик
День 21-23: Итерация на основе метрик
День 24-25: Документирование лучших практик
День 26-30: Масштабирование на командуHarness engineering — это не модное слово и не очередной фреймворк. Это здравый смысл, применённый к работе с AI-агентами.
Ключевые выводы:
Модели будут становиться умнее, но без качественной среды вокруг них даже самая умная модель будет спотыкаться на ровном месте .
60-70% бюджета подписки должно идти на подготовку проекта к тому, чтобы AI мог в нём эффективно работать.
После каждой ошибки агента обновляй документацию, чтобы ошибка не повторилась — это ядро harness engineering .
Harness окупается только на длинной дистанции — если проект живёт два месяца и умирает, тратить время бессмысленно.
Переинжиниринг harness — реальная проблема — в какой-то момент нужно остановиться и сказать: «ок, достаточно, теперь работаем» .
Формула успеха:
AI эффективность = (Качество модели) × (Качество harness)
Качество harness = Документация + Skills + Ограничения + Обратная связьВкладывайтесь в инфраструктуру, и она вернёт вам это сторицей.
# AGENTS.md
## Быстрый старт
```bash
npm install
npm run dev
npm run test:unit
npm run lint[дерево файлов]
[именование, импорт, ошибки]
[таблица команд]
[список доступных skills]
[что запрещено, что обязательно]
[документация]
### B. Шаблон SPEC
[см. Часть 2.2]
### C. Шаблон PLAN
[см. Часть 6.2]
### D. Шаблон ADR
[см. Часть 5.3]
### E. Шаблон Session Summary
[см. Часть 6.4]
### F. Каталог skills
.claude/agents/ ├── code-review.yaml ├── test-generator.yaml ├── refactor.yaml ├── docs-update.yaml ├── security-scan.yaml ├── performance-check.yaml ├── migration-helper.yaml └── onboarding.yaml
### G. Pre-commit hook
[см. Часть 8.6]
### H. DevContainer конфигурация
[см. Часть 9.3]