Base

AI Instruments

время чтения ~13 мин.

Вайбкодинг

Пути

  • Напрямую в чате задать свой вопрос и получить ответ
    • Плюсы: дёшево
    • Минусы: нужно разбираться в задаче и разрабатывать продукт самому
    • Тулинг: chatgpt
  • Автокомплит
    • Тулинг: github copilot
  • Agentic-development - разработка с помощью AI-агента, который будет писать код за нас
    • Плюсы: крайне быстрая разработка
    • Минусы:
      • нужно разбираться, как настраивать работу агента
      • очень дорого стоит
      • нужно заранее представлять архитектуру проекта, его фичи и представлять проект на каждом этапе
    • Тулинг: Cursor, Windsurf, Antigravity, Codex, Claude Code, Gemini

Agents

  • IDE
  • CLI
  • Web

Разработка

Подготовка требований

Бизнес-анализ

Сначала нам нужно составить полностью бизнес-требования для будущего приложения и составить его план

Запрос:

Я хочу сделать API для сервиса учёта кликов. Нужна детальная документация по нему. В ней нужно отразить следующие сценарии: 
 
Авторизация:
 
- Я, как пользователь, хочу создать аккаунт по email и паролю
- Я, как пользователь, хочу восстановить пароль, введя email
- Я, как пользователь, хочу ввести email и пароль, чтобы авторизоваться в сервисе
 
Функционал:
 
- Я, как пользователь, хочу, введя полную ссылку, получить на выходе короткую
- Я, как пользователь, хочу получить статистику по переходам по этой ссылке
Системный анализ

Далее нам ИИ вернёт полный план сервиса, который нам нужно будет поместить в проект

Ответ с прошлого шага помещаем в файл:

docs / requiremnts.md

## 1. Авторизация и управление аккаунтом
 
## 1.1 Регистрация
 
**US-001:** Я, как новый пользователь, хочу создать аккаунт по email и паролю, чтобы получить доступ к сервису.
 
**Acceptance Criteria:**
 
- Email должен быть уникальным и валидным (формат)
    
- Пароль минимум 8 символов, содержит буквы и цифры
    
- После регистрации отправляется письмо с подтверждением email
    
- До подтверждения email функционал ограничен (опционально)
    
- Возвращается JWT токен для доступа к API
    
- При попытке зарегистрировать существующий email возвращается ошибка 409
    
 
**API Endpoint:**
 
text
 
`POST /api/v1/auth/register Body: { "email": "user@example.com", "password": "password123" } Response: { "token": "jwt_token", "userId": "uuid", "emailVerified": false }`
 
---
 
## 1.2 Подтверждение email
 
**US-002:** Я, как пользователь, хочу подтвердить свой email по ссылке из письма, чтобы активировать полный функционал.
 
...

Правила архитектуры

Запрос:

Далее мне нужно создать короткие архитектурные правила для ИИ:
 
- используем NestJS
- тонкие контроллеры: только DTO + делегирование в Command Bus / Query Bus
- идемпотентность: обзательна для команд создания Indempotecy-key + таблица ключей
- Read-модели: агрегации, обновляются асинхронно
- Redirect: fire-and-forget, лёгкий endpoint без тяжёлой логики, только редирект
- Валидация: nestjs-zod для DTO, бизнес-инварианты в domain-слое
- Авторизация: Guards + провреки владельца в хендлерах
- CQRS: команды изменяют состояние и запросы чтение разделены, отделлные Command и Query Handlers

И далее помещаем результат в проект

docs / arch-rules.md

# Архитектурные правила проекта
 
## Стек и фреймворк
 
- **Backend framework:** NestJS (TypeScript)
    
- **Архитектурный паттерн:** CQRS + Event Sourcing (опционально)
    
- **Validation:** nestjs-zod для DTO-слоя
    
- **Database:** PostgreSQL (или укажи свою)
    
 
---
 
## 1. Контроллеры (Controllers)
 
**Принцип:** Тонкие контроллеры — только маршрутизация и делегирование.
 
...

Правила использования

Далее в самом агенте нужно сделать реф на эти правила и объяснить ему, за что отвечают эти файлы либо поместить в корневой файл для агентов

AGENTS.md

Все правила архитектуры описаны в `docs / arch-rules.md`
Бизнес требования описаны в `docs / requirements.ts`

План реализации

Далее ИИ нужно запросить создать план реализации

docs / plan.md

Вот пошаговый план реализации сервиса сокращения ссылок с учётом всех требований из предыдущих документов. План структурирован для AI-агента (Claude Code, Cursor, или другого) с чёткими задачами и зависимостями.[nestjs+2](https://docs.nestjs.com/recipes/cqrs)
 
---
 
# План реализации сервиса сокращения ссылок (URL Shortener)
 
## Фаза 0: Подготовка инфраструктуры
 
## 0.1 Инициализация проекта
 
**Цель:** Создать базовый NestJS проект с необходимыми зависимостями.
 
**Шаги:**
 
bash
 
`# Создать NestJS приложение nest new url-shortener-api cd url-shortener-api # Установить зависимости npm install @nestjs/cqrs @nestjs/typeorm @nestjs/passport @nestjs/jwt \   typeorm pg redis nestjs-zod zod bcrypt class-validator class-transformer \  @nestjs/config @nestjs/event-emitter npm install -D @types/bcrypt @types/passport-jwt`
 
**Файлы для создания:**
 
- `docker-compose.yml` — PostgreSQL + Redis
    
- `.env.example` — переменные окружения
    
- `tsconfig.json` — настройки TypeScript
    
 
**Критерий выполнения:** Проект запускается, есть Docker-окружение с БД и Redis.
 
...

Архитектура проекта

Так же нам нужно поддерживать актуальной нашей архитектурной схемы проекта

AGENTS.md

При изменении проекта, нужно вносить правки описания архитектуры в документ `docs / architecture.md` и использовать его в работе

Далее ИИ нужно запустить выполнять план. По ходу его реализации, агент будет совершать ошибки. Чтобы исправлять неточности, их всегда нужно фиксировать в соответствующем файле документации docs.

docs / arch-rules.md

Версии: 
- Вместо NodeJS, используй Bun последней версии

Код ревью

Основа, которая потребуется от разработчика - это ревью кода и архитектура. Некоторые части кода проще и быстрее будет написать вручную, но огромную часть бойлерплейта агент заберёт на себя.

Использование на больших проектах

Вайб-кодинг хорошо работает на высокодокументированных проектах, где описана архитектура, подходы, правила, требования, где есть комментарии и чёткие очевидные связи между модулями.

Большие legacy-проекты не представляется возможным допиливать через агента, потому что тут будет мало информации по технологии и связи, зачастую, будут неявными.

Современные агенты хорошо заточены на разработку небольших фич с чёткоопределёнными границами. Так же нужно не забывать следить за агентом, потому что он и сам может превратить проект в неподдерживаемый, добавив огромное количество костыльных решений, которые могут только помешать вдальнейшем.

Установка инструментов

Установка агентов через npm:

npm i -g @anthropic-ai/claude-code @openai/codex

Инициализация в проекте

Файл AGENTS.md содержит описание агентов, их ролей и инструкций для работы в проекте. В этом файле можно определить:

  • Роли различных AI-агентов
  • Инструкции по работе с кодом
  • Стиль кодирования и стандарты проекта
  • Архитектурные принципы
# AI Agents Configuration
 
## Code Agent
Роль: Разработчик
Инструкции: Следовать принципам SOLID, писать чистый код

Эти файлы помогают AI-агентам лучше понимать контекст проекта и работать более эффективно.

Сlaude

Вызов Claude Code интерфейса в терминале:

claude

При открытии, нас встречает простой интерфейс с описанием модели.

Операции

В промпт строке мы можем вводить сразу промпт с задачей, которую нам нужно выполнить либо триггернуть операции через /

Операции:

  • /install - позволит установить бинарник в систему

  • /init - обязательная операция, которая соберёт CLAUDE.md, в котором будет описан проект для ИИ-агента.

    Промпт можно дополнить и, если в проекте есть документация, то сослаться на неё

    /init учти документацию @docs/architecture-rules.md

    Через @... идёт обращение к файлу

    Чем подробнее мы опишем структуру проекта в CLAUDE.md, тем меньше контекста потребуется для определения конкретных мест, которые нужно доработать.

  • /permissions - позволяет настроить правила по работе с данным проектом (чтение, запись, вызов команд)

  • /config - эта команда позволяет изменить настройки клода

Конфигурации

Так же присутствует глобальный ~/.claude/CLAUDE.md, из которого будет браться информация для всех проектов.

После данных минимальных настроек, у нас появится .claude, который будет хранить информацию, нужную для агента.

Режимы запросов

Shift+Tab позволяет сменить текущий режим модели:

  • code - дефолтный режим, в котором работает claude
  • plan mode - позволяет создать чек-лист, по которому агент будет исполнять задачу

Советы по разработке

  • После каждой большой выполненной задачи, особенно после plan mode, мы должны проверить изменения и совершить commit
  • CLAUDE.md в паре с правильной проектной документацией - это лучший оптимизатор контекста
  • сюда можно вставлять изображения из буфера обмена через ctrl + v
  • Для обычных задач стоит использовать sonnet, так как это просто дешевле

Context

Подробнее про оставшийся контекст можно глянуть через /context

  • /compact - сожмёт текущий контекст в рамках текущей операции
  • /clear - очистит контекст, когда мы уже будем выполнять абсолютно другую операцию

Лимиты

/coast - цена запросов, если мы используем API

/usage - лимиты при использовании по подписке

Prompt

У нас есть три способа ввода промпта:

  • просто вводить промпт в поле ввода
  • воспользоваться ctrl + G, чтобы перейти в дефолтный редактор (vim) для ввода большого промпта
  • воспользоваться prompt-file подходом и попросить агента выполнить описанный в файле промпт: execute @prompts/task-description-prompt.md

Subagents

Уникальная особенность клода - агенты. Агенты - это автономные боты, которые триггерятся на команды или на описанные в промпте действия. Они имеют свой контекст, выполняют нпрямую задачу, которую мы описали в их предназначении.

Мы можем создать агента для этого проекта и общих агентов, которые

Определяем, в зависимости от выполняемых им задач, доступные ему операции. Для код-ревью можно не предоставлять операции для редактирования кода.

Далее выбираем ему цвет и тут же увидем имя

На последнем экране у нас будет возможность изменить его описание, название и параметры

Далее мы просто текстово можем вызывать операцию и клод поймёт, что нам нужно вызвать определённого агента, который выполнит операцию

Commands

Команды - это наши кастомные запросы, которые мы обозначили, как команды, которые мы можем вызвать через /

В папке с настройками клода нужно создать раздел commands и добавить .md файл с командами. В этом файле у нас есть возможность передавать параметры из промпта и окружения через $

.claude / commands / code-review

Сделай код ревью с помощью code-review-advisor и учти в этом: $ARGUMENTS

И далее останется вызывать нашу команду и у нас будет возможность передать туда аргументы (наш промпт)

GitHub

Под капотом клод использует для работы с гитхабом утилиту gh. Нам нужно иметь её на устройстве и заранее авторизовать проект.

Мы можем запросить: Сделай PR с описанием фичи в main. И он сам уже сможет оперировать нашим проектом в гите.

MCP

Claude поддерживает огромное количество MCP (model content protocol), посредством которых он может подключаться к Figma, Notion, GitHub, Netlify и так далее

claude mcp add --transport http figma-remote-mcp https://mcp.figma.com/mcp

Ссылки

Таск-трекер Beads

Beads — это инструмент, который предоставляет агентам общую память и систему отслеживания задач.

Установка

Устанавливаем на устройство утилиту Beads

curl -fsSL https://raw.githubusercontent.com/steveyegge/beads/main/scripts/install.sh | bash

Далее нужно проинициализировать его в проекте. После этой операции, у нас дополнится AGENTS.md разделом о том, как с ним работать и появится .beads папка.

bd init

Далее нужно указать агенту, что он должен пользоваться этой утилитой.

echo "Use 'bd' for task tracking" >> AGENTS.md

Далее триггерим fix прекоммит хуков

bd doctor fix

Применение

Далее описанный план разработки задачи нужно перенести в bd. С этим справится и сам агент

Разбей на задачи с помощью bd требования `tasks / categories-xml-import.md`

Установим консольный вьювер задач из beads

brew install dicklesworthstone/tap/bv

И далее можно просмотреть все задачи для агентов через команду

bv

Тут у нас в реальном времени создаются и обновляются задачи агентом и определяется их импакт для системы, приортеты, причина реализации и аналитика

Так же нужно обратить внимание на то, что задачи должны выполняться последовательно друг за другом

Контроль выполнения

Далее уже можно приступать к выполнению задач. Чтобы разработка шла проще, очень важно каждую задачу выполнять отдельно друг от друга, что, следовательно, потребует вызов подобного промта:

Выполни сначала первую задачу и возьми только её

Web UI тасок

Установка

npm i -g beads-ui

Запуск UI

bdui start --open

И в результате у нас откроется такой UI с нашими задачами в браузере

Spec Kit

Spec Kit — это open-source платформа для управления разработкой с помощью AI-агентов (Claude Code, GitHub Copilot, Cursor, Gemini CLI). Он превращает хаотичные промпты в структурированные спецификации, помогая AI генерировать качественный код.

Установка

uvx --from git+https://github.com/github/spec-kit.git specify init <ИМЯ_ПРОЕКТА>

После инициализации команды Spec Kit становятся доступны через slash-команды в AI-агенте (вводите ”/” в чате).

Процесс работы: SPTI-цикл

Spec Kit работает по модели SPTI (Specify → Plan → Tasks → Implement):

  1. S (Specify) — создаёте подробное описание проекта, AI генерирует детальную спецификацию
  2. P (Plan) — формулируете архитектуру и ограничения, AI создаёт технический план с альтернативами
  3. T (Tasks) — AI разбивает архитектурный план на конкретные выполнимые задачи
  4. I (Implement) — AI последовательно выполняет задачи, проверяя соответствие требованиям на каждом этапе

Основные операции

Constitution (/speckit.constitution)

Назначение: Установка базовых принципов и правил проекта.

Что добавлять:

  • Принципы разработки проекта
  • Стили кодирования и стандарты
  • Архитектурные ограничения
  • Технологические предпочтения
  • Требования к качеству кода
  • Принципы безопасности

Пример использования:

/speckit.constitution
 
Принципы:
- Следовать SOLID принципам
- Использовать TypeScript строгий режим
- Писать unit-тесты для всех публичных методов
- Документировать сложную бизнес-логику

Specify (/speckit.specify)

Назначение: Создание детальной спецификации на основе описания требований.

Что добавлять:

  • Описание функциональности
  • Бизнес-требования
  • Пользовательские истории
  • Ожидаемое поведение системы
  • Входные и выходные данные

Пример использования:

/speckit.specify
 
Нужно создать систему аутентификации пользователей:
- Регистрация с email и паролем
- Вход в систему
- Восстановление пароля
- Двухфакторная аутентификация

Clarify (/speckit.clarify)

Назначение: Уточнение и детализация требований и спецификаций.

Что добавлять:

  • Ответы на вопросы AI о требованиях
  • Уточнение неясных моментов
  • Дополнительные детали функциональности
  • Разъяснение бизнес-логики
  • Уточнение технических деталей

Пример использования:

/speckit.clarify
 
Уточнение по аутентификации:
- Пароль должен быть минимум 8 символов
- Email должен быть уникальным
- При регистрации отправляется письмо подтверждения

Plan (/speckit.plan)

Назначение: Генерация технического плана разработки с учётом архитектуры и ограничений.

Что добавлять:

  • Архитектурные требования
  • Технологические ограничения
  • Интеграции с другими системами
  • Масштабируемость и производительность
  • Безопасность

Результат: AI создаёт технический план с альтернативными подходами и обоснованием выбора.

Пример использования:

/speckit.plan
 
Создать план для системы аутентификации:
- Использовать JWT для токенов
- Хранить пароли с bcrypt
- Использовать Redis для сессий
- Поддержать OAuth2

Tasks (/speckit.tasks)

Назначение: Разбиение архитектурного плана на конкретные выполнимые задачи.

Результат: AI создаёт список задач с возможностью тестирования на каждом этапе.

Пример использования:

/speckit.tasks
 
Разбить план на задачи:
1. Создать модель User
2. Реализовать регистрацию
3. Реализовать вход
4. Добавить валидацию
5. Написать тесты

Analyze (/speckit.analyze)

Назначение: Анализ существующего кода и требований.

Что анализирует:

  • Соответствие кода спецификациям
  • Качество реализации
  • Потенциальные проблемы
  • Соответствие принципам из constitution
  • Покрытие тестами

Пример использования:

/speckit.analyze
 
Проанализировать текущую реализацию аутентификации
на соответствие спецификации и принципам безопасности.

Implement (/speckit.implement)

Назначение: Выполнение задач из списка с проверкой соответствия требованиям.

Процесс:

  • AI последовательно выполняет задачи
  • Проверяет соответствие спецификации на каждом этапе
  • Следует принципам из constitution
  • Генерирует код согласно плану

Пример использования:

/speckit.implement
 
Начать реализацию задач из списка, начиная с создания модели User.

Опциональные операции

Помимо основных операций, Spec Kit предоставляет дополнительные инструменты для валидации, проверки и контроля качества:

Checklist (/speckit.checklist)

Назначение: Создание чек-листов для проверки соответствия реализации спецификациям.

Применение:

  • Проверка полноты реализации функциональности
  • Валидация соответствия кода требованиям
  • Контроль качества на разных этапах разработки
  • Проверка архитектурных решений

Пример использования:

/speckit.checklist
 
Создать чек-лист для проверки системы аутентификации:
- Все эндпоинты реализованы
- Валидация входных данных работает
- Пароли хешируются правильно
- Тесты покрывают основную функциональность

Review (/speckit.review)

Назначение: Проведение ревью кода на соответствие стандартам и спецификациям.

Применение:

  • Проверка соответствия кода принципам из constitution
  • Выявление потенциальных проблем безопасности
  • Проверка стиля кодирования
  • Валидация архитектурных решений

Пример использования:

/speckit.review
 
Провести ревью кода аутентификации на соответствие
принципам безопасности и лучшим практикам.

Validate (/speckit.validate)

Назначение: Валидация требований и спецификаций на разных этапах разработки.

Применение:

  • Проверка полноты спецификации
  • Выявление противоречий в требованиях
  • Валидация технического плана
  • Проверка реализуемости задач

Пример использования:

/speckit.validate
 
Проверить спецификацию аутентификации на полноту
и отсутствие противоречий в требованиях.

Ограничения и лучшие практики

Эффективность:

  • Spec Kit наиболее эффективен для проектов с 20-50 задачами
  • На больших проектах (200+ задач) контекст может разваливаться
  • Требует хорошо сформулированные бизнес-требования на входе (принцип “garbage in — garbage out”)

Рекомендации:

  • Начинайте с чётких бизнес-требований
  • Используйте SPTI-цикл последовательно
  • Регулярно используйте опциональные операции для валидации
  • Комбинируйте Spec Kit с другими инструментами (например, Beads для трекинга задач)
  • Не используйте Spec Kit для постоянных правок и модификаций — он лучше подходит для систематизации процесса с нуля

Когда использовать:

  • При начале нового проекта
  • Для систематизации хаотичного процесса разработки
  • Когда нужно превратить идеи в структурированные документы
  • Для создания технической документации из требований

Когда не использовать:

  • Для небольших быстрых изменений
  • Если у вас уже есть налаженный аналитический процесс
  • Для проектов с очень большим количеством задач без разбиения на модули

Вид графа

Обратные ссылки

Вид графа

Обратные ссылки