AI Project Starter Protocol

Короткое определение

Как начать AI-проект без хаоса

Эта страница — про предыдущий этап перед hardening-аудитом. Она нужна, когда проекта еще нет или он только стартует, и вы хотите заложить такую архитектуру AI-generated проекта, чтобы потом не разгребать хаос в коде, документации, зависимостях, секретах, deploy path и работе AI-агентов.

Если сказать совсем просто: сначала вы заставляете AI понять задачу, границы и ограничения, потом создаете правильную структуру, документацию и базовые правила безопасности, и только потом разрешаете AI писать реальные фичи.

Не начинайте с “сделай приложение”Сначала intake, scope и starter path.

Выберите путь стартаПустая папка, свой шаблон или готовый starter template.

Зафиксируйте active/deferred surfacesAI не должен случайно включать mobile, admin или payments.

После MVP — hardeningСтартовый протокол не заменяет инженерную доводку перед релизом.

GitHub toolkit package v0.4.1

Начните проект с GitHub toolkit

Если вы стартуете новый AI-проект, можно читать Starter Protocol на сайте или забрать GitHub toolkit и положить нужные файлы прямо в репозиторий проекта.

prompts/product-brief-prompt_en.md и prompts/product-brief-prompt.md
protocols/ai-project-starter-protocol.md
templates/AGENTS.md, templates/PROJECT_MAP.md, templates/ARCHITECTURE_SOURCE_OF_TRUTH.md
repo-local AI IDE files for the toolkit itself: AGENTS.md, CLAUDE.md, .cursorrules, .github/copilot-instructions.md
synthetic examples: examples/todo-app-vibe/, examples/landing-page-vibe/
docs/token-aware-code-discovery.md и checklists/perimeter-security-checklist.md

Открыть Starter toolkit Product Brief prompt (EN)Пример todo-app-vibe

GitHub toolkit package v0.4.1: для старта держите порядок Product Brief -> Architecture Map -> templates/AGENTS.md as AGENTS.md -> templates/PROJECT_MAP.md. После MVP или перед следующим большим фиче-блоком переходите в maintenance lane: /care-refactoring для behavior-preserving cleanup и /ui-refactoring для ownership cleanup на фронтенде. Путь установки остается review-first, Windows — bash-first через Git Bash, WSL или PowerShell wrapper, а security scope и tooling roadmap в toolkit объясняют, что VCP помогает дисциплине, но не заменяет security review или зрелый CLI.

Прямые файлы

Для маленького проекта можно начать с Product Brief + `templates/AGENTS.md` как `AGENTS.md` + PROJECT_MAP.md, а затем запустить vibe-check в starter mode как быструю структурную проверку.

Если новый проект сразу смотрит в интернет, perimeter baseline нужно проектировать до первого deploy: домены, public endpoints, admin routes, rate limits, WAF/CDN/reverse proxy, closed ports, secrets, logs/backups и recurring checks. Откройте Perimeter Security Checklist, Security Operations Baseline и Token-Aware Code Discovery.

Для командного проекта лучше сразу добавить Architecture Source of Truth и PROMPTS.md.

Для нового проекта начните с START_HERE или review-first minimal installer. Для первого vertical slice держите под рукой testing cookbook, а для AI-specific рисков — AI-specific threat model. Посмотрите runnable todo-app-starter, IDE-specific AGENTS templates и modular starter prompt в prompts/modules/. Для новых проектов сразу ведите PROJECT_MAP.md, чтобы AI не тратил контекст на хаотичный поиск по файлам. Перед запуском скрипта всегда просмотрите scripts/init-minimal.sh. Если хотите сначала дать toolkit своему AI, откройте use-this-repo-prompt.md. Сайт удобнее для чтения маршрута. GitHub удобнее, если хотите сразу забрать markdown-файлы в свой проект и дать их AI/IDE.

Что нового

Что нового в v1.4

Общие изменения v1.4

FAQ/content consistency check.
AI IDE compatibility matrix.
Clearer Artifact Pack / Architecture Source of Truth links.
Reviewer Agent clarification.
Architecture update triggers.
AI-generated migration rollback, AI test strategy и PROMPTS.md example.

Что изменилось именно на этой странице

Обновлена формулировка роли в AGENTS.md starter: atomic changes и smallest practical file set.
Добавлены architecture update triggers для ARCHITECTURE.md / Architecture Source of Truth.
Добавлен заполненный пример docs/PROMPTS.md.
Добавлен блок AI-generated test strategy.
Definition of Done теперь учитывает independent diff review для важных изменений.
FAQ и ссылки на Hardening / Troubleshooting уточнены.

Advanced note

Starter v1.4 по-прежнему не пытается превратить старт в enterprise-аудит. Цель страницы прежняя: заложить правильные границы, operational baseline, безопасный intake внешних интеграций и такой первый slice, который не заведет проект в тупик по безопасности, росту или хаотичным AI-итерациям.

Проблема старта

Почему “сделай мне приложение” — плохой старт

Когда AI получает пустую папку и размытое задание, он начинает принимать архитектурные решения сам: выбирает структуру, зависимости, подход к API, хранение данных, авторизацию, env, тесты и деплой. Иногда это выглядит быстро, но через несколько итераций проект становится трудно понимать, расширять и безопасно выкатывать.

Vibe coding без стартового протокола почти всегда ведет к лишним слоям, кривым зависимостям, плавающему scope и переписыванию кода уже на раннем этапе.

Типовые проблемы

Что ломается, если начать с пустой папки

Нет понятной структуры проекта и разделения слоев.
AI тянет лишние зависимости и пакеты “на всякий случай”.
env и секреты появляются хаотично.
Нет PROJECT_MAP.md и ARCHITECTURE.md.
Неясно, где бизнес-логика, а где UI и API glue.
Нет правил для AI-агента и критериев остановки.
Нет deploy path, security baseline и тестовой стратегии.
Непонятно, что точно не надо трогать и что не входит в MVP.

Starter paths

Три способа начать AI-проект

Не каждый проект нужно начинать одинаково. Иногда достаточно пустой папки и строгого intake. Иногда лучше взять свой минимальный шаблон. Иногда выгоднее адаптировать готовый AI-ready starter template. Главное — осознанно выбрать путь, а не позволить AI решить всё за вас.

1. Пустая папка + протокол

Полный контроль над структурой

Когда подходит: маленький MVP, лендинг, internal tool, проект без сложного backend.

Плюсы: минимум лишнего, меньше зависимостей, проще понять проект.
Минусы: docs, env, deploy и security baseline нужно заложить вручную.
CTA: используйте Prompt 0–7 на этой странице.

2. Свой starter template

Повторяемый стек и свои правила

Когда подходит: вы часто делаете похожие проекты и хотите стандартизировать AGENTS.md, README, docs и deploy.

Плюсы: быстро, привычная структура, меньше повторной настройки.
Минусы: шаблон может устареть и тащить лишние зависимости.
CTA: используйте эту страницу как checklist для своего шаблона.

3. Готовый AI-ready starter template

Быстрый full-stack skeleton

Когда подходит: нужен web, backend, landing, contracts, deploy docs и быстрый старт до MVP.

Плюсы: многое уже собрано, есть docs и agent instructions.
Минусы: нельзя копировать вслепую, нужно удалить лишние поверхности и проверить security, deploy path и license.
CTA: используйте блок «Как безопасно адаптировать starter template».

AI Project Starter Protocol

Что такое AI Project Starter Protocol

Это стартовый набор решений, файлов и prompt-блоков, которые нужно задать до активной генерации кода. Его цель — не написать приложение сразу, а создать рамку, в которой AI будет работать безопаснее, предсказуемее и полезнее.

Коротко: сначала сформулируйте идею в Product Brief / ТЗ; затем проведите intake, выберите starter path, зафиксируйте active/deferred surfaces, создайте README, AGENTS.md, PROJECT_MAP.md, ARCHITECTURE.md, добавьте token-aware code discovery, определите package manager и deploy path, а потом запускайте маленький vertical slice.

Сначала границы Определяем, что строим, для кого и что точно не входит в MVP.

Потом starter path Выбираем: empty folder, own template или external starter template.

Потом структура и docs Создаем каркас проекта, source of truth docs и правила для агента.

Потом код Только после этого начинаем писать фичи и планировать первый audit.

Для кого это

Кому полезна эта страница

Founder / solo-builder

Если собираете MVP через AI и хотите не утонуть в хаосе через неделю активного vibe coding.

Разработчик

Если используете Claude Code, Codex, Cursor или Windsurf и хотите, чтобы агент работал по правилам.

Product owner

Если нужно быстро проверить идею, но не потерять контроль над архитектурой и scope.

Команда

Если хотите договориться, как AI должен создавать и развивать новые проекты внутри команды.

Вайбкодер

Если хочется быстро, но не “как попало”, а так, чтобы проект можно было потом поддерживать и развивать.

Маршрут по уровню

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

Beginner route

Если вы только начинаете

Не берите огромный шаблон сразу.
Пройдите Prompt 0 и уточните scope.
Выберите простой MVP и active surfaces.
Создайте только нужные папки и docs.
Заполните README, AGENTS.md и PROJECT_MAP.md.
Сделайте одну главную фичу маленьким vertical slice.
Потом идите в Hardening Protocol.

Advanced route

Если вы уже понимаете стек

Выберите starter template или свой шаблон.
Проведите onboarding template до setup.
Зафиксируйте active/deferred surfaces.
Добавьте token-aware discovery в AGENTS.md.
Создайте Architecture Source of Truth, если проект не игрушечный.
Сразу определите deploy path и rollback.
После MVP пройдите hardening-аудит.

Начать с Prompt 0 Открыть Architecture Source of Truth После MVP перейти к Hardening Protocol

Шаг -1

Product Brief / ТЗ — если идеи еще нет в документе

Перед тем как выбирать стек, шаблон, архитектуру и AGENTS.md, превратите идею в понятный Product Brief.

Product Brief перед vibe coding

Если у вас уже есть понятное ТЗ или Product Brief, не проходите этот шаг заново — используйте его как вход для Prompt 0.

Большая ошибка в vibe coding — начинать с фразы “сделай мне приложение”. В этот момент AI сам начинает додумывать продукт, аудиторию, сценарии, архитектуру, роли, данные, платежи и ограничения.

Правильный старт: сначала описать идею, задать уточняющие вопросы и сформировать короткое ТЗ / Product Brief. Только после этого переходить к Starter Protocol: выбору starter path, active/deferred surfaces, стека, AGENTS.md, PROJECT_MAP.md, архитектурной справке и первой безопасной итерации.

Что должно быть в brief

Что за продукт и для кого он.
Какую проблему он решает.
Какие 3–5 главных пользовательских сценариев.
Что входит и что не входит в MVP.
Какие платформы нужны: web, backend, mobile, bot, admin, landing.
Какие данные собираются и есть ли ПДн.
Нужны ли платежи, интеграции, AI/LLM и compliance-проверки.
Какой будет Definition of Done для первой версии.

Архитектурная справка дальше

Если brief показывает, что проект не игрушечный, дальше стоит делать не только краткий `ARCHITECTURE.md`, но и полноценную архитектурную справку. Для этого у нас уже есть отдельный шаблон Architecture Source of Truth.

Product Brief отвечает на вопрос “что строим и зачем”, а архитектурная справка — “как это устроено, какие есть границы, риски, интеграции, rollback и readiness gates”.

У меня есть идея проекта. Помоги превратить ее в понятное ТЗ перед началом AI-разработки.

Не предлагай код, стек и архитектуру сразу.

Сначала задай уточняющие вопросы, без которых нельзя нормально сформировать проект.

Обязательно уточни:

1. Что за продукт я хочу сделать?
2. Для кого этот продукт?
3. Какую проблему он решает?
4. Какие 3–5 главных пользовательских сценариев?
5. Что входит в MVP?
6. Что точно не входит в MVP?
7. Какие платформы нужны:
- web;
- backend/API;
- mobile;
- bot;
- admin;
- landing;
- Telegram Mini App;
- другое.
8. Какие данные будут храниться?
9. Есть ли персональные или чувствительные данные?
10. Нужны ли регистрация и роли пользователей?
11. Нужны ли платежи?
12. Нужны ли внешние интеграции?
13. Нужен ли AI/LLM внутри продукта?
14. Есть ли юридические, privacy, payment или compliance риски?
15. Есть ли ограничения по срокам, бюджету и сложности?
16. Какой результат будет считаться готовой первой версией?

После вопросов сформируй документ:

# Product Brief

## 1. Идея продукта

## 2. Целевая аудитория

## 3. Проблема пользователя

## 4. Основные пользовательские сценарии

## 5. MVP scope

## 6. Not in scope

## 7. Платформы и поверхности проекта

Раздели на:
- active surfaces;
- deferred surfaces;
- not in scope.

## 8. Данные и сущности

## 9. Auth / роли

## 10. Интеграции

## 11. AI/LLM, если нужно

## 12. Legal / privacy / payments риски

## 13. Ограничения

## 14. Definition of Done первой версии

## 15. Открытые вопросы

## 16. Рекомендованный следующий шаг

В конце скажи, готов ли проект переходить к AI Project Starter Protocol.

Не ограничивайся только тем, что я явно написал. Если видишь пропущенные риски, недостающие вопросы или смежные направления проверки — выведи их отдельно в разделе “Что я мог упустить”.

После формирования brief перепроверь результат и выведи:
- что сделано;
- что еще не определено;
- что я мог упустить;
- какие follow-up вопросы нужно закрыть до технического старта.

Не пиши код до моего подтверждения Product Brief.

Условный пример

Как может выглядеть результат

Это условный пример, не реальный кейс.

Product Brief:
Продукт — Telegram Mini App для записи заявок на консультацию.

MVP:
- landing;
- форма заявки;
- админский список заявок;
- уведомление в Telegram.

Active surfaces:
- landing;
- backend/API;
- database.

Deferred surfaces:
- online payments;
- mobile app;
- complex CRM;
- AI assistant.

Risks:
- персональные данные в форме;
- нужна политика ПДн;
- нужна защита от spam submissions.

Next step:
перейти к Prompt 0 и выбрать starter path.

До / после

Пример: как идея превращается в стартовый план

Было: “Сделай мне сервис записи клиентов.”

Стало: “MVP: landing + форма заявки + админский список заявок. Не делаем оплату, личный кабинет и мобильное приложение. Данные: имя, телефон, услуга. Active surfaces: landing, backend/API, database. Deferred: payments, mobile app, CRM. Package manager: pnpm. Deploy path: сначала staging/local, production после hardening. Риски: ПДн, spam, хранение заявок.”

Такой результат лучше, чем “сделай приложение”, потому что AI получает границы и не начинает строить лишнюю архитектуру.

Intake до старта

До первой генерации кода нужно ответить на вопросы

Продукт

Что строим?
Кто пользователь?
Какие 3 главных сценария?
Что точно не входит в MVP?
Что будет считаться готовым?
Стартуем с пустой папки, своего шаблона или starter template?

Платформы и данные

Какие surfaces active, deferred и not in scope?
Нужна ли база данных и какие основные сущности?
Есть ли персональные или чувствительные данные?
Нужны ли uploads, файлы, backup и restore?
Нужно ли mobile сейчас или позже?

Интеграции и DevOps

Нужна ли авторизация и какие роли?
Нужны ли платежи, email/SMS, AI API, webhooks, endpoints/routes?
Нужен ли deploy сейчас и где будет production?
Есть ли РФ-контур, Yandex Cloud или локализация данных?
Есть ли ограничения по AI-токенам/стоимости и нужен ли discovery subagent?

Project boundaries

Active и deferred surfaces: не включайте всё сразу

Одна из главных ошибок на старте — активировать web, mobile, admin, payments, backend, landing и AI-интеграции одновременно. Хороший starter-протокол должен разделять: что реально делаем сейчас, а что оставляем как deferred surface.

Surface	Status	Что значит
web	active	делаем сейчас
backend/api	active	нужен для MVP
mobile	deferred	не трогаем до отдельного решения
admin	planned	описываем, но не реализуем
payments	deferred	не подключаем без бизнес-решения
landing	active	нужен для запуска

Deferred surface нельзя “случайно” активировать в ходе работы AI. Если позже появляется мобильное приложение, оплата или админка, сначала обновляются scope, docs и architecture, и только потом пишется код.

Выбор стека тоже не должен автоматически активировать лишние поверхности. Если starter template содержит web, backend, mobile, landing или payments, это не значит, что все они входят в MVP. Например: template содержит `web`, `backend`, `mobile`, `landing`, `payments`, а MVP реально использует только `web`, `backend`, `landing`. Тогда `mobile` и `payments` остаются deferred.

Starter architecture

Базовая структура, с которой AI проще работать

Не каждый проект должен содержать все эти папки. Это карта возможных слоев. Для маленького проекта можно оставить только нужное: например `web`, `api`, `shared`, `docs`.

project/
  apps/
    web/
    mobile/
    api/
    landing/
  packages/
    shared/
    contracts/
    ui/
  docs/
    PROJECT_MAP.md
    ARCHITECTURE.md
    SECURITY.md
    DEPLOYMENT.md
    AUDIT_BACKLOG.md
  infra/
    docker/
    ci/
    deploy/
  scripts/
  tests/
  .env.example
  AGENTS.md
  README.md

Starter template vs protocol

Starter template помогает, но не заменяет мышление

Готовый starter template — это не магическая кнопка “сделать проект правильно”. Это ускоритель. Перед использованием нужно понять, какие поверхности активны, какие отложены, какой deploy path выбран, какие документы являются source of truth, какие bootstrap-инструкции нужно удалить после настройки и какие секреты нельзя коммитить.

Не используйте starter template как black box. После установки AI должен объяснить, что именно было создано, какие части активны, какие отложены, какие зависимости добавлены и что нужно проверить перед первой фичей.

Слой	Зачем нужен	Когда можно не делать
apps/web	Веб-интерфейс для пользователя или кабинета	Если проект — только API, бот или служебный backend
apps/api	Backend, маршруты, auth, integration layer	Если это статический сайт без серверной логики
apps/mobile	Мобильное приложение или companion-клиент	Если мобильный клиент не нужен
packages/shared	Общие типы, утилиты и бизнес-правила	Если проект очень маленький и монослойный
packages/contracts	Общие API/data schemas между frontend, backend и mobile	Если проект совсем маленький, API нет или frontend/backend пока находятся в одном приложении без отдельного contract boundary
docs	Архитектура, правила, карта проекта и security notes	Лучше оставлять всегда
infra	Docker, CI, deploy, инфраструктурные правила	Если это очень ранний прототип без deploy

Starter template checklist

Есть README.
Есть AGENTS.md / CLAUDE.md или аналогичные инструкции.
Есть .env.example.
Есть docs по local database.
Есть deploy docs и security docs.
Есть lockfile и testing docs.

Что еще проверить

Есть contracts/shared schemas.
Есть license.
Понятно, какие части шаблона можно удалить.
Понятно, что является bootstrap-only инструкциями.
Понятно, что является source of truth docs.

Пример подхода

AI-ready starter template

Один из примеров такого подхода — open-source репозиторий di-sukharev/vibe. Его не нужно копировать вслепую, но сама идея AI-ready starter template полезна: README как source of truth для first-run setup, AGENTS/CLAUDE инструкции, активные и отложенные поверхности, contracts, deploy docs и cloud path. Это не endorsement и не рекомендация копировать шаблон вслепую. Любой starter template нужно прогонять через onboarding: license, dependencies, security, active/deferred surfaces, deploy path и соответствие вашему продукту.

Starter template onboarding

Как безопасно адаптировать готовый starter template

Если вы начинаете не с пустой папки, а с готового репозитория-шаблона, сначала проведите onboarding проекта. AI не должен сразу писать фичи.

Мы начинаем новый проект на базе готового starter template.

Не пиши фичи сразу.

Сначала проведи onboarding шаблона:

1. Прочитай README.md.
2. Прочитай AGENTS.md / CLAUDE.md, если они есть.
3. Прочитай docs/*.md, которые относятся к активным частям проекта.
4. Определи, какие поверхности есть в шаблоне:
- web
- backend/api
- landing
- mobile
- admin
- packages/contracts
- database
- infra/deploy
5. Спроси меня, какие поверхности реально активны в этом проекте.
6. Спроси, какие поверхности нужно отложить.
7. Спроси, нужен ли deploy сейчас.
8. Спроси, какой cloud/deploy path использовать, если есть выбор.
9. Проверь .env.example и не создавай реальные секреты в репозитории.
10. Переименуй проектные идентификаторы только после подтверждения.
- package.json name;
- app slug;
- namespace;
- import paths;
- env var prefixes;
- Docker/service names, если есть.
11. Не коммить секреты.
12. Не оставляй bootstrap-only инструкции после завершения настройки.
13. Не добавляй новые зависимости до объяснения необходимости.
14. Не удаляй части шаблона без подтверждения.

После onboarding выведи отчет:

- что есть в шаблоне;
- что будет активно;
- что будет отложено;
- какие документы являются source of truth;
- какие команды доступны;
- какие env нужны;
- какие риски есть;
- что нужно сделать перед первой фичей.

Только после моего подтверждения переходи к setup.

Этот prompt подходит для любого starter template, а не только для одного конкретного репозитория. Если используете другой starter template, применяйте тот же onboarding prompt.

Выбор технологий

Stack Decision Framework: не выбирайте технологии наугад

AI не должен выбирать стек по привычке. Он должен объяснить варианты, оверхед, риски и соответствие продукту.

В vibe coding нельзя универсально сказать “используйте только Next.js” или “используйте только Bun/Hono”. Один starter template может быть построен на Bun/Hono + React + Expo + Astro + PostgreSQL, другой — на Next.js + Supabase, третий — на FastAPI + React, четвертый — на Laravel. Это нормально. Проблема не в разном стеке, а в слепом выборе.

1. Simple MVP stack

Минимум зависимостей и самый быстрый старт

Когда подходит: лендинг, простой бот, internal tool, маленький MVP, нет сложной бизнес-логики.

Требование к AI: предложить самый простой вариант с минимумом зависимостей.
Примеры: plain HTML/CSS/JS, Astro, Next.js без лишнего backend, simple Node/Python backend при необходимости API.
Важно: не тянуть mobile, admin, payments, complex auth и microservices без решения.

2. Standard production-ready stack

Баланс скорости, поддержки и deploy

Когда подходит: web app, SaaS, личный кабинет, backend/API, база данных, auth, интеграции.

Требование к AI: предложить баланс скорости, поддержки, безопасности и deploy.
Примеры: Next.js / React + backend/API, Node.js / Hono / Fastify / Nest, Python / FastAPI, PostgreSQL, managed auth, если уместно.
Важно: Docker/CI добавлять только если реально нужен.

3. Template-based stack

Когда уже есть AI-ready starter template

Когда подходит: используем готовый starter template, нужен full-stack skeleton, нужны web/backend/mobile/landing/contracts/deploy docs.

Требование к AI: не выбирать технологии заново, а сначала разобрать стек шаблона.
AI должен ответить: какой стек навязывает template, что активно, что deferred, что можно удалить, какие dependencies критичны и какие security/license риски есть.
Важно: готовый AI-ready starter template может заранее выбрать backend, web, mobile, landing, shared contracts, database и deploy path. Это удобно, но такой стек нужно принять осознанно, а не копировать вслепую.

Stack Decision Matrix

Что AI должен сравнить перед выбором стека

Используйте этот mini-prompt, если хотите заставить AI объяснить стек, а не просто навязать любимый набор технологий.

Предложи 3 варианта стека:

1. Simple MVP stack
- самый простой вариант;
- минимум зависимостей;
- быстрее всего стартовать.

2. Standard production-ready stack
- баланс скорости, поддержки, безопасности и деплоя.

3. Template-based stack
- если используем готовый starter template;
- какие технологии он навязывает;
- что можно отключить;
- какие риски и оверхед.

Для каждого варианта укажи:
- frontend;
- backend;
- database;
- auth;
- deploy;
- mobile, если нужно;
- package manager;
- почему подходит;
- почему может не подойти;
- что будет active;
- что будет deferred;
- что будет not in scope.

Если пользователь уже выбрал starter template, не заменяй его стек без причины. Сначала объясни стек template, затем предложи, что оставить, что отключить и какие риски проверить.

После setup

После установки шаблона удалите bootstrap-only инструкции

Starter template часто содержит инструкции только для первого запуска: как клонировать, что спросить, как переименовать проект, какие части активировать. После setup эти инструкции могут мешать агенту и путать будущую работу.

Checklist

Переименовать project slug и package identifiers.
Отвязать template remote, если проект не является вкладом в исходный template.
Удалить bootstrap-only блоки из AGENTS.md / CLAUDE.md.
Оставить ongoing engineering rules.
Записать active/deferred surfaces в README.
Обновить PROJECT_MAP.md и ARCHITECTURE.md.
Сделать initial commit после проверки.
Перейти к безопасному плану первой фичи.

Минимальный набор

Файлы, которые должны быть в хорошем AI-проекте

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

README.md

Что это за проект, как запустить, какие команды есть и где лежит документация.

AGENTS.md

Правила для AI-агента: как искать код, что не трогать, как вносить изменения и как писать отчет.

PROJECT_MAP.md

Карта проекта: entrypoints, модули, API, данные, integrations и risky areas.

ARCHITECTURE.md

Краткая архитектурная справка: слои, потоки данных, auth, storage и deploy path.

Architecture Source of Truth

Полноценная архитектурная справка проекта для backend, AI, payments, mobile и production deploy.

SECURITY.md

Правила безопасности: env, секреты, зависимости, auth, scanner checks и what not to commit.

.env.example

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

DEPLOYMENT.md

Как деплоить, как откатывать, какие env нужны и что проверить перед production.

AUDIT_BACKLOG.md

Список будущих находок и задач на исправление после первого hardening-аудита.

Открыть Architecture Source of Truth template Открыть raw markdown Открыть все шаблоны

AGENTS.md

AGENTS.md для Claude Code, Codex и Cursor: правила, чтобы AI не импровизировал

AGENTS.md — инструкция для AI-агента внутри проекта. Она объясняет, как работать с кодом, как не трогать секреты, как соблюдать project boundaries и как отчитываться после правок.

# AGENTS.md

## Role

You are working on this project as a careful senior engineer.
Your job is to make atomic, safe, well-explained changes, targeting the smallest practical file set per iteration.

## Project boundaries

- Keep active surfaces explicit: web, api, landing, mobile, admin, packages, infra.
- Keep deferred surfaces explicit.
- Keep MVP scope explicit.
- Keep not-in-scope explicit.
- Do not activate deferred surfaces without approval.

## General rules

- Do not rewrite the project from scratch.
- Do not make large changes without a plan.
- Do not edit secrets or production env files.
- Do not expose tokens, passwords, API keys or private data.
- Before editing, explain what files you will change and why.
- After editing, report what changed, what was tested and what remains.

## Dependency policy

- Do not add dependencies without justification.
- Check license before adding a dependency.
- Check package maintenance and install scripts.
- Respect the chosen package manager and lockfile.
- Do not mix package managers or lockfiles without approval.
- Prefer the existing stack and current project patterns.
- Explain alternatives before adding a new package.

## KISS / YAGNI

- Prefer KISS and YAGNI.
- Do not create enterprise abstractions before they are needed.
- Do not add repositories, services, factories or interfaces if a simple module or function is enough.
- Keep architecture evolutionary.
- Every abstraction must have a current reason, not a hypothetical future reason.

## Documentation update rule

- Update README, PROJECT_MAP, ARCHITECTURE and SECURITY when changing structure, API, env, auth, deploy, data model or integrations.
- Update ARCHITECTURE.md or Architecture Source of Truth whenever API endpoints/routes, data model, auth/roles, integrations, deploy path, background jobs/workers/queues, external APIs, payment flow, security model, database migrations, storage/files or public/internal boundaries change.

## Approval gates

Ask approval before:
- adding auth, payment, admin or mobile;
- changing deploy path;
- adding paid external services;
- adding a new database;
- changing the security model;
- mass refactor;
- deleting template parts.

## Token-aware Code Discovery

When code discovery is needed, keep the main process focused on decisions and implementation.
If available, delegate broad repository search to a cheaper or lightweight subagent first.

The subagent must only search and summarize. It must not edit files.

The subagent must return a compact evidence map only:
- path:line
- symbol / component / endpoint/route / function name
- relevant snippet or signature
- why it matters
- confidence: high / medium / low

The main process must verify critical findings directly in source files before editing.

Rules:
- do not read .env, .env.local, .env.production unless explicitly allowed;
- do not print secrets;
- do not read binary files, logs, build outputs or large generated files unless necessary;
- prefer targeted reading over full-project scanning;
- keep discovery output compact;
- for large repositories, limit the evidence map to the most relevant 50 files;
- if evidence is incomplete, ask for a second focused search instead of reading the whole repository.

## Memory Bank

Update project memory files when changing scope, architecture, endpoints/routes, API, env, data model, auth, deploy path, integrations or security model.

Project memory files:
- README.md
- PROJECT_MAP.md
- ARCHITECTURE.md
- SECURITY.md
- AUDIT_BACKLOG.md
- CHANGELOG.md, if present
- docs/PROMPTS.md, if the project is driven through reusable AI prompts

Create CHANGELOG.md only if the project needs release notes.

Do not rely on chat history as the only source of truth.

## Git workflow

- Before large changes, check git status.
- If the repository is not initialized, propose git init before mass file creation.
- Do not commit without explicit approval.
- Show changed files after the task.
- Track expensive AI loops and stop if the task starts expanding without new evidence.

## Stop Conditions

Stop and ask for approval when:
- change touches more than 10 files;
- change touches more than 2 layers at once: frontend + backend + database;
- change adds auth, payments, admin, mobile, worker, queue or external API;
- change requires new dependency or package manager change;
- change changes database schema or migrations;
- change rewrites architecture instead of making a small vertical slice;
- change deletes files or template parts;
- tests/build are red and the fix is not obvious;
- you are unsure whether a surface is active or deferred.

Do not continue by guessing. Ask for approval and propose a smaller plan.

## Reporting

Every task must end with:
- files changed
- commands run
- tests passed/failed
- risks remaining
- next recommended step

Token-aware workflow

Экономия AI-токенов: сначала code discovery, потом реализация

Большая часть контекста в Claude Code, Codex, Cursor и других AI IDE часто уходит не на реализацию, а на поиск кода: агент ходит по дереву файлов, читает отдельные файлы, уточняет связи. Это нормально, но этим можно управлять.

Идея простая: главный AI-процесс должен принимать решения и реализовывать, а широкую разведку по репозиторию можно отдавать более дешевому или легкому subagent, если инструмент это позволяет. Это и есть практический слой token-aware code discovery и один из практических элементов vibe coding security на старте.

Роли

Что делает discovery subagentИщет файлы, entrypoints, endpoints/routes, services, возвращает path:line, сигнатуру, why it matters и confidence.

Чего он не делаетНе редактирует код, не принимает архитектурные решения, не выводит .env и не делает финальный вывод без проверки главным агентом.

Что делает main agentПроверяет критичные findings, читает только нужные файлы, принимает решения, вносит изменения, запускает тесты и пишет отчет.

Token-aware Code Discovery

Copyable block для AGENTS.md

Практика управления контекстом: сначала compact evidence map, потом точечное чтение и реализация.

## Token-aware Code Discovery

When code discovery is needed, keep the main process focused on decisions and implementation.

If available, delegate broad repository search to a cheaper or lightweight subagent first:
- in Codex, use a cheaper/smaller search-capable subagent when available;
- in Claude Code, use a cheaper capable model for repository search when available;
- in other AI IDEs, use any available lightweight search/review mode.

The subagent must only search and summarize. It must not edit files.

The subagent must return a compact evidence map only:
- path:line
- symbol / component / endpoint/route / function name
- relevant snippet or signature
- why it matters
- confidence: high / medium / low

The main process must verify critical findings directly in source files before editing.

Rules:
- do not read .env, .env.local, .env.production unless explicitly allowed;
- do not print secrets;
- do not read binary files, logs, build outputs or large generated files unless necessary;
- prefer targeted reading over full-project scanning;
- keep discovery output compact;
- for large repositories, limit the evidence map to the most relevant 50 files;
- if evidence is incomplete, ask for a second focused search instead of reading the whole repository.

AI Cost Awareness

AI Cost Awareness: не тратьте контекст впустую

Перед широким discovery уточнить scope поиска.
Не читать весь репозиторий, если можно начать с PROJECT_MAP.md.
Не генерировать сотни файлов без approval.
Не запускать LLM/API вызовы в цикле без лимитов.
Для больших задач разделять discovery, planning, implementation, review.
Фиксировать expensive loops в AUDIT_BACKLOG.md или docs/PROMPTS.md.

Практика

AI cost awareness не означает “ничего не читать”. Это означает: сначала evidence, потом решение, потом маленький controlled diff. Если контекст растет без новых фактов, задача уже уходит в дорогой loop и это нужно остановить.

Memory Bank

Memory Bank для AI-проекта

AI-сессии заканчиваются, контекст теряется, а проект остается. Поэтому важные решения нужно фиксировать в файлах, а не держать только в чате.

После изменений AI должен обновлять memory bank, если поменялись scope, endpoints/routes, API, env, data model, auth, deploy path, external integrations или security model.

Минимальный Memory Bank

README.md — что это за проект и как его запускать.
AGENTS.md — как AI должен работать с проектом.
PROJECT_MAP.md — где что находится.
ARCHITECTURE.md — как устроены слои и потоки данных.
SECURITY.md — правила безопасности.
AUDIT_BACKLOG.md — задачи, риски и accepted risks.
CHANGELOG.md / RELEASE_NOTES.md — если проект развивается итерациями или уже есть пользователи.
docs/PROMPTS.md — если проект ведется через AI и важны версии prompts.

Deploy path

Deploy path: не выбирайте облако случайно

AI может предложить DigitalOcean, Vercel, Railway, Render, Yandex Cloud, VPS или что-то еще. Это не должно быть случайным выбором. На старте нужно зафиксировать deploy path: где будет backend, где база, где статика, где storage, кто управляет доменом, где secrets и как делать rollback.

Checklist

Нужен ли deploy сейчас.
Где будет production и есть ли staging.
Где будет база данных и uploads/media.
Кто владеет доменом и где хранятся secrets.
Как происходит rollback и какие есть prerequisites.
Есть ли РФ-контур, Yandex Cloud или локализация данных.

KISS / YAGNI

Не стройте enterprise до первой фичи

AI часто переусложняет архитектуру, если попросить “сделай правильно”. На старте важнее простая эволюционная структура, чем абстракции “на будущее”. Репозитории, сервисные слои, фабрики, event bus и микросервисы должны появляться только когда для них есть реальная причина.

Что значит на практике

Prefer KISS and YAGNI.
Не добавляйте enterprise abstractions без текущей причины.
Не стройте дизайн-систему, если сначала нужно проверить связку слоев.
Пусть архитектура будет эволюционной, а не гипотетически enterprise-ready.

Prompt Versioning

Версионируйте prompts, если проект ведется через AI

Если вы адаптируете prompt-блоки под проект, сохраняйте их в docs/PROMPTS.md с датой, версией протокола и кратким результатом. Это помогает понять, почему AI принял определенные решения, и передать проект другому человеку.

Пример

# PROMPTS.md

## 2026-05-25 — Starter Protocol v1.4 — Prompt 0

### Prompt
Used Starter Protocol Prompt 0 for technical intake.

### Result
Selected stack: Next.js + PostgreSQL.
Active surfaces: web, backend/API, database.
Deferred surfaces: mobile, payments, admin.

### Files changed
- README.md
- AGENTS.md
- PROJECT_MAP.md
- ARCHITECTURE.md

### Notes / risks
Payments mentioned in Product Brief but deferred until Hardening.
Need to revisit legal/payment checks before production.

Architecture Source of Truth

Когда обычного ARCHITECTURE.md уже мало

Для маленького MVP достаточно краткого ARCHITECTURE.md. Но если проект включает backend, базу данных, оплату, AI, внешние интеграции, mobile или production deploy, лучше сразу завести Architecture Source of Truth — архитектурную справку как рабочий источник правды.

product boundaries и C4 architecture;
NFR/SLO и runtime topology;
integrations registry и API/data contracts;
threat model, privacy, backup/restore;
release/rollback lifecycle, ADR и known risks.

Шаблон

Если проект не игрушечный, после структуры лучше создать не только `docs/ARCHITECTURE.md`, но и полноценный Architecture Source of Truth как рабочий engineering-control document.

Открыть Architecture Source of Truth template Открыть raw markdown Вся система протоколов

Operational baseline

Operational baseline: что заложить до production

Даже на старте проекта нужно решить, где будут храниться внутренние документы, как будут подключаться внешние API, какие процессы будут запускаться, кто имеет доступ к секретам, где будут logs, alerts и update scripts. Иначе AI может создать рабочий код, но оставить проект открытым для сканирования и утечек.

Checklist

Где хранится Product Brief / ARCHITECTURE / PROJECT_MAP / AGENTS / SECURITY.
Какие документы можно держать в репозитории, а какие только локально или в приватном хранилище.
Не попадают ли .md, .env, .log, .bak, .yaml, .json и dumps в public webroot.
Есть ли .gitignore для секретов, логов и build artifacts.
Где будут production secrets и кто имеет к ним доступ.
Есть ли admin routes и нужны ли worker/scanner/browser automation процессы.
Под каким пользователем должны работать фоновые процессы и нужны ли outbound restrictions.
Нужны ли alerting, staging и THIRD_PARTY.md / integrations registry.

Docs policy

Где хранить архитектурную справку

Architecture Source of Truth полезен, но это чувствительный документ. В нем могут быть внутренние endpoints, интеграции, процессы, ограничения, риски, deployment model, security decisions и backlog. Такой документ нельзя случайно отдавать публично.

Для публичного сайта не храните полную архитектурную справку в webroot.
Храните ее локально, в приватном репозитории, private docs storage или на сервере вне public root.
Ограничьте доступ по ролям и используйте шифрование для чувствительных проектов.
Проверьте, что /architecture.md, /ARCHITECTURE.md, /PROJECT_MAP.md, /AGENTS.md, /README.md, /CHANGELOG.md, /integrations-catalog.md не отдаются публично.
Если нужна публичная документация, делайте sanitized version без secrets, internal paths, IP, tokens, admin routes и private APIs.

Safe intake

Перед подключением внешнего repo/API/package

Проверить источник, лицензию и активность проекта.
Проверить lockfile, install scripts, postinstall и prepare.
Проверить GitHub Actions/workflows, бинарники и obfuscated code.
Не запускать curl|bash, root-only scripts и непроверенные Docker images без review.
Не давать production secrets и запускать интеграцию сначала в sandbox/staging.
Зафиксировать origin, version/commit, license и risks в integrations registry.

Growth path

Database / Load Readiness: не создавайте архитектурный тупик

Не нужно строить enterprise с первого дня, но нужно не закрывать себе путь к росту.

На старте AI часто предлагает самую быструю реализацию: одна таблица, синхронные операции, отсутствие индексов, бизнес-логика в UI, прямые вызовы внешних API из request handler, отсутствие очередей и миграций. Для демо это может работать, но при первых пользователях такие решения становятся дорогими.

Scalability-ready не значит сложный. Это значит: простая архитектура, понятные границы, миграции, индексы, idempotency, rate limits и план, что делать при росте.

Database

Выбрать primary database осознанно.
Понять, какие данные будут расти быстрее всего.
Определить ключевые сущности и query patterns.
Не смешивать доменные данные, логи, события и временные данные в одну таблицу без причины.
Предусмотреть migration history и индексы под ожидаемые запросы.
Не хранить большие blobs в основной БД без причины.

Load / request path

Определить critical user flows.
Не делать тяжелые операции синхронно, если их можно вынести в background job.
Учитывать rate limits внешних API и quota risks.
Предусмотреть idempotency для payments, webhooks и imports.
Не вызывать LLM/API в цикле без лимитов.
Добавить timeout/retry/backoff strategy и degradation mode.

Growth path

Что можно оставить простым сейчас.
Что нужно сделать перед production.
Что станет bottleneck первым.
Какие решения точно нельзя принимать “на потом”.
Какие задачи добавить в scalability backlog.
Не добавлять queue/cache/microservices без текущего обоснования.

Definition of Ready

Когда можно начинать писать фичи

Если этих пунктов нет, AI еще рано писать большие фичи.

Идея проекта описана в Product Brief / ТЗ

Понятно, что строим и кто пользователь

MVP scope и not in scope зафиксированы

Основные пользовательские сценарии описаны

Open questions зафиксированы

Выбран starter path

Active surfaces зафиксированы

Deferred surfaces зафиксированы

Выбран стек

Есть README.md

Есть AGENTS.md

Проект инициализирован как git repo или git init осознанно отложен

GitHub/Git remote создан или явно отложен

Есть .env.example

.gitignore закрывает .env, node_modules, dist, logs и local files

Есть PROJECT_MAP.md

Есть ARCHITECTURE.md или Architecture Source of Truth

Есть SECURITY.md

Решено, какие docs private / sanitized / public

Понятен deploy path или deploy явно deferred

Нет реальных секретов в репозитории

Понятно, где будут храниться secrets и кто к ним имеет доступ

Dependency policy понятна

Есть хотя бы smoke-check для critical path или задача на него

AI знает, когда спрашивать approval

Копируемая инструкция

Полные prompt-шаги для старта AI-ready проекта

Это self-service playbook: можно идти по шагам, копировать каждый prompt отдельно и строить проект безопасно с первого дня. Если у вас еще нет Product Brief, начните с Шага -1. Если brief уже есть, используйте его как вход для Prompt 0. Дальше маршрут включает шаги 0–7: от технического intake до первой safe iteration.

Перейти к первому шагу

Шаг 0

Сначала задай вопросы

Не пишите код сразу. Пусть AI сначала проведет технический intake и уточнит все архитектурно важные вводные.

Мы начинаем новый AI/vibe-coded проект.

Не пиши код сразу.

Перед этим шагом желательно иметь Product Brief. Если Product Brief еще нет, сначала выполни Шаг -1 и помоги пользователю сформулировать ТЗ.

Если Product Brief уже есть, не задавай заново продуктовые вопросы из Шага -1. Используй brief как входные данные и переходи к техническому intake. Если Product Brief неполный — задай только недостающие вопросы.

Сначала проведи intake: задай мне вопросы, без которых нельзя безопасно выбрать архитектуру.

Обязательные вопросы:

1. Есть ли уже Product Brief / ТЗ?
2. Если его нет — сначала сформировать его?
3. Начинаем с пустой папки, своего шаблона или готового starter template?
4. Какие surfaces active / deferred / not in scope?
5. Какой стек и package manager выбираем?
6. Какой lockfile разрешен и можно ли менять package manager?
7. Репозиторий уже инициализирован или нужно предложить git init?
8. Нужен ли Git remote / GitHub remote сейчас или он явно отложен?
9. Нужен ли web, mobile, backend, landing, admin?
10. Нужна ли база данных и какие основные сущности уже подтверждены в brief?

Дополнительные вопросы:
11. Нужны ли внешние интеграции, endpoints/routes, uploads/files, email/SMS/push?
12. Нужен ли deploy сейчас?
13. Есть ли предпочтительный cloud/provider?
14. Есть ли РФ-контур, Yandex Cloud или локализация данных?
15. Нужен ли Docker/CI/CD/staging?
16. Есть ли ограничение по AI-токенам/стоимости?
17. Нужно ли использовать token-aware code discovery?
18. Какие docs и артефакты должны быть source of truth на старте?
19. Какие ограничения по срокам, бюджету и сложности влияют именно на технический старт?
20. Что будет считаться технической Definition of Ready перед первой фичей?

Вопросы для production / integrations:
21. Где будут храниться private docs и какие файлы нельзя публиковать в webroot?
22. Где будут production secrets и кто получает к ним доступ?
23. Нужны ли worker/scanner/browser automation процессы и под каким пользователем они будут работать?
24. Какие внешние repo/API/package придется подключать и нужен ли integrations registry?
25. Какой первый bottleneck по данным или нагрузке видится уже сейчас?

После вопросов предложи 2-3 варианта архитектуры:
- простой MVP;
- стандартный production-ready;
- расширенный вариант.

Не ограничивайся только тем, что я явно написал. Если видишь важные риски, пропущенные вопросы, недостающие проверки или смежные проблемы — предложи их отдельно в разделе “Что я мог упустить”.

Не создавай файлы до моего подтверждения.

Условный пример

Как может выглядеть результат Prompt 0

Условный пример результата intake:

Starter path: own template
MVP scope: web + backend + simple auth
Active surfaces:
- web
- backend/api
- database

Deferred surfaces:
- mobile
- payments
- admin
- AI integrations

Package manager:
- pnpm
- only pnpm-lock.yaml allowed

Deploy path:
- staging deferred
- production deploy not configured yet

Docs to create:
- README.md
- AGENTS.md
- PROJECT_MAP.md
- ARCHITECTURE.md
- SECURITY.md

Open questions:
- нужен ли email-login или magic link?
- где будет production database?
- нужны ли персональные данные на MVP?

Шаг 1

Выбери стек и границы проекта

На этом этапе AI должен предложить архитектуру проекта, но не писать код и не создавать папки заранее.

На основе моих ответов предложи архитектуру проекта.

Не пиши код сразу.

Сформируй:

1. Предложи 3 варианта стека:
- Simple MVP stack
- Standard production-ready stack
- Template-based stack
2. Starter path:
- empty folder
- own template
- external starter template
3. Active surfaces.
4. Deferred surfaces.
5. Not in scope.
6. Какие части проекта нужны:
- web
- backend/api
- mobile
- landing
- admin
- shared contracts
- database
- queue/cron/workers
- payments
- AI/LLM integrations
7. Основные сущности данных.
8. Основные API endpoints/routes.
9. Auth/roles модель.
10. Где будет храниться конфигурация.
11. Какой deploy path выбрать.
12. Нужен ли Architecture Source of Truth: yes/no.
13. Какие риски есть у этой архитектуры.
14. Что можно упростить.
15. Короткая оценка Database / Load Readiness:
- primary database;
- expected growing tables/entities;
- migration strategy;
- index strategy;
- background jobs needed now/later;
- caching needed now/later;
- rate limits;
- external API quota risks;
- idempotency needs;
- first likely bottleneck;
- what is intentionally deferred.

Правила:
- prefer KISS and YAGNI;
- do not create enterprise abstractions before they are needed;
- architecture should be evolutionary.
- не предлагай сложную архитектуру без причины;
- если выбранное решение создает очевидный тупик для роста, укажи это и предложи более устойчивую альтернативу;
- если пользователь уже выбрал starter template, не заменяй его стек без причины;
- сначала объясни стек template, затем предложи, что оставить, что отключить и какие риски проверить;
- выбор стека не должен автоматически активировать deferred surfaces.
- если предлагаешь внешний repo/template/package/API — сначала проведи safe third-party intake; не подключай и не запускай ничего до approval.

Для каждого варианта стека укажи:
- frontend;
- backend;
- database;
- auth;
- deploy;
- mobile, если нужно;
- package manager;
- почему подходит;
- почему может не подойти;
- что будет active;
- что будет deferred;
- что будет not in scope.

Выведи итог в формате:

- Recommendation
- Simple MVP stack
- Standard production-ready stack
- Template-based stack
- Starter path
- Project boundaries
- Active surfaces
- Deferred surfaces
- MVP scope
- Not in scope
- Database / Load Readiness
- Что можно оставить простым сейчас
- Что нужно сделать перед production
- Первый likely bottleneck
- Cloud/deploy recommendation
- Architecture risks
- Open questions

Не ограничивайся только тем, что я явно написал. Если видишь важные риски, пропущенные вопросы, недостающие проверки или смежные проблемы — выведи их отдельно в разделе “Что я мог упустить”.

После этого спроси подтверждение.

Шаг 2

Создай стартовую структуру проекта

Только после подтверждения создавайте каркас: без лишних приложений, пакетов и premature complexity.

Создай стартовую структуру проекта на основе утвержденной архитектуры.

Правила:

- Не добавляй лишние приложения и пакеты.
- Не добавляй зависимости без необходимости.
- Не создавай deferred surfaces.
- Если проект еще не инициализирован в Git, сначала предложи выполнить git init.
- Если пользователь подтверждает, выполни git init до массового создания файлов.
- Если lockfile уже есть, используй соответствующий package manager.
- Не запускай install случайным package manager.
- Если package manager не определен — спроси пользователя.
- Если используется starter template — сначала проведи onboarding.
- Не удаляй template parts без approval.
- Создай только нужные директории.
- Добавь README.md.
- Добавь AGENTS.md.
- Добавь .env.example без реальных секретов.
- Добавь docs/PROJECT_MAP.md.
- Добавь docs/ARCHITECTURE.md.
- Добавь docs/SECURITY.md.
- Добавь docs/DEPLOYMENT.md, если есть deploy.
- Добавь docs/AUDIT_BACKLOG.md.
- После setup обнови README, PROJECT_MAP и ARCHITECTURE.

После создания выведи:

- какие файлы созданы;
- почему такая структура;
- какие команды доступны;
- какие части пока заглушки;
- git status;
- что нужно заполнить дальше.

Не делай commit без подтверждения пользователя.

Шаг 3

Заполни стартовую документацию

README, PROJECT_MAP, ARCHITECTURE и SECURITY должны описывать реальный стартовый проект, а не фантазию модели.

Заполни стартовую документацию проекта.

Не придумывай несуществующие части.

Обнови:

1. README.md
- что это за проект;
- как запустить;
- какие команды есть;
- где лежат docs;
- какие env нужны;
- какие surfaces active/deferred;
- какой starter path выбран.

2. docs/PROJECT_MAP.md
- структура проекта;
- entrypoints;
- основные модули;
- где frontend/backend/database;
- где security-sensitive зоны;
- что еще не реализовано;
- какие surfaces отложены.

3. docs/ARCHITECTURE.md
- назначение проекта;
- слои;
- поток данных;
- auth/roles;
- database/storage;
- external integrations;
- deploy;
- known risks.
- какие документы private / sanitized / public;
- нужна ли encrypted/private storage policy.

4. docs/SECURITY.md
- env/secrets rules;
- dependency rules;
- auth/access rules;
- scanner checks;
- what not to commit.

5. docs/DEPLOYMENT.md
- local;
- staging, если нужен;
- production;
- rollback;
- env checklist.

6. docs/AUDIT_BACKLOG.md
- пустой шаблон backlog для будущих находок.

7. Если проект не простой:
- создай Architecture Source of Truth или ссылку на template;
- запиши, какие документы являются source of truth.

Не ограничивайся только тем, что я явно написал. Если видишь недостающие документы, пропущенные риски или смежные проблемы — предложи их в разделе “Что я мог упустить”.

После обновления выведи краткий отчет:
- что сделано;
- что проверено;
- что не удалось проверить;
- что я мог упустить;
- какие баги найдены попутно;
- что исправлено попутно;
- что требует отдельного approval;
- какие follow-up задачи добавить в backlog.

Шаг 4

Заложи security baseline

До первой серьезной реализации важно убрать хаос в env, зависимостях, правах доступа и будущих scanner checks.

Проверь и заложи минимальный security baseline проекта.

Не внедряй сложные решения без необходимости.

Проверь:

- .env.example есть и не содержит реальных секретов;
- .gitignore закрывает env, build artifacts, logs, local files;
- нет hardcoded secrets;
- зависимости минимальны;
- нет подозрительных install scripts;
- нет ненужных third-party packages;
- есть dependency policy;
- учтен package hallucination risk;
- если использован starter template — учтен template supply-chain risk;
- есть базовая валидация входных данных;
- auth/roles не строятся только на frontend;
- приватные routes/API требуют проверки прав;
- error messages не раскрывают внутренности;
- есть план secret scanning;
- есть dependency scanning;
- есть базовый checklist перед deploy.

Проверь также CI/CD baseline:
- .github/workflows, CI/CD configs и deploy scripts на hardcoded secrets;
- небезопасные permissions;
- вывод env в logs;
- actions без pinning.

Если проект web/frontend:
- предложи security headers;
- проверь XSS-risks;
- проверь external scripts.

Если backend:
- предложи rate limiting;
- timeout для внешних запросов;
- безопасные cookies/sessions, если есть.

После проверки выведи:
- что уже ок;
- что нужно добавить;
- что блокирует production;
- что можно отложить.

Шаг 5

Заложи dev/deploy baseline

Сразу фиксируем минимальный путь запуска, build, deploy и rollback, чтобы AI не строил процесс хаотично потом.

Подготовь минимальный dev/deploy baseline.

Проверь:

- есть понятная команда установки;
- package manager зафиксирован;
- lockfile соответствует выбранному package manager;
- нет смешанных lockfile;
- есть команда dev;
- есть команда build;
- есть lint/typecheck/test, если применимо;
- есть .env.example;
- есть описание локального запуска;
- есть deploy path;
- есть deferred deploy path, если deploy пока отложен;
- есть rollback notes;
- есть staging: yes/no;
- есть healthcheck, если есть backend;
- есть basic logging;
- есть место для monitoring/alerts;
- есть CI checklist;
- не создаются production secrets;
- placeholders fail-fast до deploy;
- понятны cloud prerequisites.

Не настраивай тяжелый CI/CD без подтверждения.
Сначала предложи минимальный вариант.

После проверки выведи:
- какие команды есть;
- каких команд не хватает;
- что нужно перед deploy;
- какой deploy path выбран;
- что можно добавить позже.

Шаг 6

Составь безопасный план первой реализации

Перед кодом нужен implementation plan по маленьким этапам, чтобы AI не делал массовые правки без остановок.

Составь план первой реализации MVP.

Не пиши код сразу.

Разбей на маленькие этапы:

1. Скелет проекта.
2. Модели данных.
3. Auth, если нужен.
4. Основные API endpoints/routes.
5. Основной UI flow.
6. Интеграции.
7. Тесты.
8. Документация.
9. Security checks.
10. Первый hardening audit.

Для каждого этапа укажи:

- какие файлы будут изменены;
- какой риск;
- как проверить;
- какие тесты нужны;
- когда остановиться и запросить подтверждение.

Отдельно:
- перед первой реализацией выполни compact code discovery map;
- если доступен lightweight subagent, раздели main agent и discovery subagent;
- не начинай реализацию, пока active/deferred surfaces и docs не зафиксированы.

Vertical slice первой итерации должен быть минимальным. Примеры:
- вывести одну тестовую запись из базы через API на страницу;
- отправить одну форму и сохранить запись;
- показать один mock/fake response через реальный route;
- проверить связку frontend → backend → storage без сложной бизнес-логики.

Запрет:
- не писать весь продукт сразу;
- не добавлять admin/mobile/payments/auth, если они deferred;
- не делать дизайн-систему, если цель — проверить связку слоев.

После плана спроси:
“Начать с этапа 1?”

Не пытайтесь превратить Starter Protocol в полный аудит. Его задача — правильно стартовать и сделать первый контролируемый slice. Полная проверка security, supply-chain, legal, payments, device QA и scanner checks — это следующий этап: AI Project Hardening Protocol.

Шаг 7 · Optional / Advanced

Первая безопасная итерация — optional / advanced

Этот prompt не обязателен для маленьких проектов. Используйте его после Definition of Ready, когда структура, docs, baseline и plan уже готовы.

Начни первую безопасную итерацию реализации.

Правила:

1. Не расширяй scope.
2. Работай только в active surfaces.
3. Не трогай deferred surfaces.
4. Перед изменениями покажи:
- какие файлы будешь менять;
- зачем;
- какой риск;
- как проверить;
- changed files plan.
5. Если изменения рискованные — предложи checkpoint commit, но не делай commit без approval.
6. После изменений покажи git status и кратко объясни, как откатиться.
7. Если пишешь тесты, фокусируйся на critical path и regressions. Не добавляй новый test framework без approval.
8. После выполнения перепроверь changed files, риски, недостающие проверки и выведи self-review.
9. Не меняй deploy path без approval.
10. Не добавляй auth/payments/admin/mobile без отдельного решения.
11. После реализации обнови docs, если изменились структура/API/env/data model.
12. Запусти доступные проверки.
13. Перед реализацией ответь:

- какие запросы к БД появятся;
- нужны ли индексы уже сейчас;
- будет ли операция синхронной или фоновой;
- есть ли риск N+1;
- есть ли внешний API/LLM в critical path;
- как проверить, что первый slice не создает архитектурный тупик.

14. Выведи отчет:

- что сделано;
- какие файлы изменены;
- какие команды запущены;
- что прошло;
- что не удалось проверить;
- какие риски остались;
- какие таблицы/миграции добавлены;
- какие query patterns появились;
- какие индексы добавлены или отложены;
- какие bottlenecks ожидаются;
- что добавить в scalability backlog;
- git status после изменений;
- как откатить текущую итерацию;
- что делать следующим шагом.

Начни с самого маленького vertical slice, который доказывает основную ценность MVP.

Vertical slice — это не “сделать весь MVP”. Это минимальная сквозная проверка, что выбранные слои проекта соединены правильно.

Запрет:
- не писать весь продукт сразу;
- не добавлять admin/mobile/payments/auth, если они deferred;
- не делать дизайн-систему, если цель — проверить связку слоев.

Не ограничивайся только тем, что я явно написал. Если видишь важные риски, пропущенные проверки или смежные проблемы — выведи их отдельно в разделе “Что я мог упустить”.

После выполнения перепроверь свою работу: сравни результат с исходной задачей, проверь diff/измененные файлы, команды, риски, недостающие проверки и выведи self-review.

Если в процессе обнаружишь баги рядом с задачей: исправь мелкие безопасные баги, если они напрямую связаны с текущей областью; крупные или рискованные изменения не делай без approval — вынеси их в отчет и backlog.

Не пытайся превратить этот этап в полный аудит. Полная проверка security, supply-chain, legal, payments, device QA и scanner checks — это следующий этап: AI Project Hardening Protocol.

После первой safe iteration можно прогнать independent diff review: отдельный AI-reviewer без контекста основной переписки смотрит активный git diff, не редактирует код и возвращает только actionable findings. Для маленьких проектов это optional / advanced, но перед merge или deploy такая проверка полезна. Подробная практика описана в Hardening Protocol.

Перед крупной AI-итерацией проверьте git status, подготовьте changed files plan и при необходимости предложите checkpoint commit. Deploy rollback и AI-change rollback — разные вещи, а commit не должен делаться без approval.

Vertical slice

Что такое маленький vertical slice

Vertical slice — это не “сделать весь MVP”. Это минимальная сквозная проверка, что выбранные слои проекта соединены правильно.

Примеры

Вывести одну тестовую запись из базы через API на страницу.
Отправить одну форму и сохранить запись.
Показать один mock/fake response через реальный route.
Проверить связку frontend → backend → storage без сложной бизнес-логики.

Starter checklist

Чек-лист: проект готов к первой фиче

Цель проекта описана

MVP scope определен

Not-in-scope зафиксирован

Выбран starter path

Active surfaces зафиксированы

Deferred surfaces зафиксированы

Есть README.md

Есть AGENTS.md

Есть .env.example

Есть PROJECT_MAP.md

Есть ARCHITECTURE.md или Architecture Source of Truth

Есть SECURITY.md

Есть DEPLOYMENT.md или deploy явно deferred

Есть AUDIT_BACKLOG.md

AI может показать git diff/status перед изменениями

Роли и auth описаны

Основные сущности данных перечислены

Внешние интеграции перечислены

Deploy path понятен

Зависимости добавляются только с объяснением

Нет реальных секретов в репозитории

AI знает, когда спрашивать approval

Starter Definition of Done

Definition of Done для стартового этапа

Product Brief создан или обновлен

Выбран путь: empty folder / own template / external starter template

Active surfaces зафиксированы

Deferred surfaces зафиксированы

Product Brief связан с README / PROJECT_MAP / ARCHITECTURE

README объясняет проект и команды

AGENTS.md содержит ongoing rules

PROJECT_MAP.md создан

ARCHITECTURE.md или Architecture Source of Truth создан

SECURITY.md создан

DEPLOYMENT.md создан или deploy отложен явно

.env.example безопасен

Package manager выбран

Lockfile один и соответствует выбранному package manager

Нет смешанных lockfile без осознанной причины

CI/CD baseline описан или отложен

First safe implementation plan готов

Первая фича может быть начата маленькой итерацией

Если scope изменился после первой итерации, Product Brief обновлен

После MVP запланирован Hardening Protocol

Success Metrics

Как понять, что старт прошел хорошо

Хороший старт AI-проекта — это не количество созданных файлов. Это снижение хаоса в следующих итерациях.

Другой разработчик понимает структуру проекта за 10–15 минут

AI не активирует deferred surfaces без approval

Нет смешанных package managers и конфликтующих lockfile

README объясняет запуск и основные команды

AGENTS.md объясняет правила работы AI

PROJECT_MAP.md показывает entrypoints и ключевые зоны

ARCHITECTURE.md или Architecture Source of Truth описывает слои

Первая фича делается маленьким vertical slice, а не всем приложением сразу

После первой фичи понятно, когда идти в Hardening Protocol

ROI без цифр

Сколько стоит плохой старт

Плохой старт редко ломает проект в первый день. Он проявляется позже: AI тянет лишние зависимости, активирует mobile/admin/payments без решения, смешивает package managers, забывает docs, теряет контекст между сессиями и заставляет переписывать архитектуру после первых фич.

Протокол занимает время на старте, но снижает риск хаоса в следующих итерациях.

Что дешевле поймать раньше

Смешанные lockfile и случайный package manager.
Лишние deferred surfaces.
Потерянный контекст между AI-сессиями.
Непонятный deploy path.
Документацию, которую AI не обновил после первых изменений.

Если старт уже пошел не по плану

Если проект уже начат хаотично

Иногда проект уже создан через AI без Product Brief, AGENTS.md, PROJECT_MAP.md и архитектуры. В этом случае не нужно продолжать наращивать код. Сначала стабилизируйте контекст.

Остановить новые фичи.
Сделать code discovery без правок.
Создать PROJECT_MAP.md.
Создать или обновить ARCHITECTURE.md.
Добавить AGENTS.md и правила работы AI.
Разделить active/deferred surfaces задним числом.
Составить AUDIT_BACKLOG.md.
Рефакторить только маленькими vertical slices.
После стабилизации перейти к AI Project Hardening Protocol.

Когда переключаться

Если проект уже большой, непонятный или смешал слишком много слоев, не пытайтесь чинить все только стартовым протоколом. Лучше быстро зафиксировать контекст и перейти к полноценному hardening-маршруту.

Если проект уже большой и непонятный — лучше сразу перейти к Hardening Protocol

Сокращенный маршрут

Fast track для маленьких проектов

Для лендинга, простого бота, маленького internal tool или мини-MVP не всегда нужен полный маршрут. Но даже маленькому проекту нужны scope, env, git, package manager и базовые правила для AI.

Шаг -1 — короткий Product Brief.
Prompt 0 — технический intake.
Prompt 2 — минимальная структура.
Prompt 3 — README / AGENTS.md / PROJECT_MAP.md.
Prompt 7 — первая safe iteration.
После первой версии — короткий hardening check.

Важно

Minimum: Product Brief → Prompt 0 → Prompt 2 → Prompt 3 → Prompt 7.

Standard: Шаг -1 → Prompt 0–7.

Advanced: Starter + Architecture Source of Truth + Light Hardening.

Fast track не означает “без безопасности”. Если есть персональные данные, платежи, production deploy, внешние API или AI-agent actions — не ограничивайтесь Minimum.

Для совсем маленьких проектов fast track помогает не перегрузить себя документацией, но не отменяет Product Brief, `.env.example`, `git`, `AGENTS.md` и базовую архитектурную дисциплину.

Антипаттерны

Что не надо делать при старте AI-проекта

Не начинать без intake

Фраза “сделай мне приложение” без вопросов почти гарантирует лишние архитектурные решения со стороны AI.

Не отдавать архитектуру модели полностью

AI не должен сам решать за вас весь продуктовый scope, auth, данные и deploy path.

Не добавлять все сразу

Backend, mobile, admin, payments и workers не надо тащить “на всякий случай”.

Не тянуть зависимости без проверки

Каждый новый пакет должен объясняться пользой, риском и местом в архитектуре.

Не хранить реальные секреты в .env.example

Пример env должен быть безопасным и пригодным для передачи команде и AI-агентам.

Не смешивать слои

UI, бизнес-логика и API glue не должны склеиваться в один неразделимый слой.

Не просить AI “сделать все”

Нужен план маленькими этапами с остановками и подтверждениями.

Не деплоить первую версию без аудита

Starter template и аккуратный старт не заменяют hardening-аудит после первой рабочей сборки. Перед deploy прогоните AI Project Hardening Protocol.

Не считать starter template гарантией безопасности

Шаблон ускоряет старт, но не знает ваши реальные данные, риски и ограничения.

Следующий этап

После старта — обязательно аудит

Эта страница помогает правильно начать проект. Но как только AI собрал первую рабочую версию, нужен второй этап: AI Project Hardening Protocol. Там проект проверяется на архитектуру, security, supply-chain, scanner checks, тесты, monitoring, alerts, backlog исправлений и Definition of Done.

Перейти к AI Project Hardening Protocol Вся система протоколов Architecture Source of Truth Практические шаблоны

Exit Criteria

Когда переходить к Hardening Protocol

Первая рабочая версия собрана

Основной пользовательский сценарий проходит руками

Проведен хотя бы один ручной тест основного сценария

Проект открывается и не падает

Структура зафиксирована в PROJECT_MAP.md

Архитектура описана в ARCHITECTURE.md или Architecture Source of Truth

README и AGENTS.md обновлены после первой реализации

Package manager и lockfile понятны

Нет реальных секретов в репозитории

Понятно, что блокирует merge/deploy

Нужно проверить, можно ли показывать проект пользователям

Для важных изменений проведен independent diff review или явно отложен до Hardening

Перейти к AI Project Hardening Protocol

Tests

AI-generated test strategy

AI не должен писать тесты “на всё подряд”. Тесты должны закрывать critical path и регрессии.

Использовать существующий test framework.
Не добавлять новый test framework без approval.
Тестировать critical user flow.
Mock external APIs and LLM calls.
Не зависеть от live AI responses.
Проверять auth/payment/webhooks, если они active.
Фиксировать, какие тесты intentionally deferred.

Architecture updates

Когда обязательно обновлять архитектурную справку

API endpoints/routes.
Data model.
Auth/roles.
Integrations.
Deploy path.
Background jobs/workers/queues.
External APIs.
Payment flow.
Security model.
Database migrations.
Storage/files.
Public/internal boundaries.

Bridge

Как перейти из Starter в Hardening

После первой safe iteration не начинайте сразу “докидывать фичи”. Сначала передайте артефакты в Hardening Protocol.

Product Brief → проверяется на соответствие реализации.
README.md → используется как onboarding context.
AGENTS.md → становится правилами для аудита и фиксов.
PROJECT_MAP.md → обновляется в code discovery.
ARCHITECTURE.md / Architecture Source of Truth → проверяется и расширяется.
SECURITY.md → проверяется в security baseline.
docs/PROMPTS.md → помогает понять, какими инструкциями создавался проект.
AUDIT_BACKLOG.md → наполняется findings из Hardening.

Следующий шаг

Если после первого working slice у вас одна-две фичи и понятная структура, начните с Light Hardening. Если уже есть deploy intent, ПДн, платежи, внешние API или широкий diff — идите в Standard / Full Hardening.

Перейти к Hardening Protocol

FAQ

Частые вопросы

Что такое AI Project Starter Protocol?

Это стартовый протокол для AI-assisted разработки. Он помогает до первой большой генерации кода определить цель проекта, MVP scope, active/deferred surfaces, starter path, AGENTS.md, PROJECT_MAP.md, ARCHITECTURE.md, security baseline, deploy path и правила работы AI-агента.

Можно ли начинать AI-проект с пустой папки?

Да, если проект небольшой и вы готовы сами задать структуру, документацию и правила. Для маленького MVP это часто лучший путь. Но даже в пустой папке не стоит начинать с “сделай приложение”: сначала нужен intake, scope, package manager и минимальный AGENTS.md.

Нужно ли проходить Шаг -1, если ТЗ уже есть?

Нет. Если Product Brief или ТЗ уже есть, используйте его как вход для Prompt 0. Шаг -1 нужен, когда идея пока только в голове или описана слишком расплывчато.

Нужно ли писать ТЗ перед vibe coding?

Да, хотя бы короткое. Без ТЗ AI сам начинает додумывать продукт, аудиторию, сценарии, роли, данные и ограничения. Для маленького проекта достаточно Product Brief на 1–2 страницы. Для сложного проекта ТЗ должно стать основой для Starter Protocol, архитектуры и будущего hardening-аудита.

Когда нужен starter template?

Starter template полезен, если проект типовой или full-stack: web, backend, auth, база, landing, mobile, deploy docs. Но шаблон нельзя использовать как black box. Перед первой фичей нужно провести onboarding: понять active/deferred surfaces, зависимости, env, deploy path, license и security baseline.

Что такое active и deferred surfaces?

Active surfaces — части проекта, которые делаются сейчас: например web и backend. Deferred surfaces — части, которые пока не трогаем: mobile, payments, admin, workers. Это защищает проект от scope creep, когда AI начинает строить лишние слои “на всякий случай”.

Как экономить AI-токены при работе с большим проектом?

Используйте token-aware code discovery: легкий search/discovery subagent собирает compact evidence map, а основной агент читает только нужные файлы, принимает решения и вносит изменения. Это не гарантирует конкретный процент экономии, но снижает хаотичное чтение репозитория.

Что такое Memory Bank?

Memory Bank — это практика сохранения устойчивого контекста проекта между AI-сессиями: решения, scope, active/deferred surfaces, архитектура, риски, TODO и prompts. В простом проекте эту роль могут выполнять README.md, AGENTS.md, PROJECT_MAP.md, ARCHITECTURE.md, AUDIT_BACKLOG.md и docs/PROMPTS.md.

Нужно ли создавать AGENTS.md?

Да, если проект будет развиваться через Claude Code, Codex, Cursor, Windsurf или других AI-агентов. AGENTS.md снижает хаос: фиксирует правила поиска кода, approval gates, dependency policy, запрет на секреты и порядок отчетов после изменений.

Когда нужен Architecture Source of Truth?

Если проект сложнее простого лендинга: есть backend, база, AI, внешние интеграции, payment, mobile, production deploy или передача проекта другому инженеру. Для маленького MVP может хватить ARCHITECTURE.md, но сложному проекту нужен более полный источник правды.

Когда переходить к Hardening Protocol?

После первой рабочей версии: основной сценарий проходит руками, структура проекта зафиксирована, README/AGENTS/PROJECT_MAP/ARCHITECTURE обновлены, первая фича реализована маленькой итерацией, и лучше начать с Light Hardening, чтобы понять, можно ли мержить, деплоить или показывать проект пользователям.

Что делать, если проект уже начат без этого протокола?

Не продолжайте сразу писать новые фичи. Сначала сделайте PROJECT_MAP.md, ARCHITECTURE.md, AGENTS.md, зафиксируйте active/deferred surfaces и составьте backlog. Затем переходите к Hardening bridge и Troubleshooting в AI Project Hardening Protocol, чтобы стабилизировать проект без хаоса.

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

Да. Для лендинга, простого бота или маленького MVP можно пройти короткий путь: Prompt 0, Prompt 1, Prompt 2 и Prompt 3. Но intake, scope, package manager, .env.example и базовые правила для AI всё равно нужны.

Можно ли пройти сокращенную версию?

Да. Для маленьких проектов используйте Fast Track. Но если есть персональные данные, платежи, production deploy или внешние API — лучше проходить полный маршрут.

Сколько времени занимает старт по протоколу?

Для небольшого проекта обычно достаточно 1–2 часов на intake, структуру, AGENTS.md и базовую документацию. Для full-stack проекта с backend, auth, deploy и внешними интеграциями времени понадобится больше. Зато дальнейшие итерации обычно становятся понятнее, потому что AI знает границы.

Можно ли дать AI только идею и ссылку на эту страницу?

Да. Можно дать AI ссылку на AI Project Starter Protocol и попросить применить подход к вашему проекту. Но лучше явно сказать: сначала сформировать Product Brief, потом выбрать starter path, active/deferred surfaces, структуру, AGENTS.md и план первой безопасной итерации.

Self-service или AI handoff

Можно пройти страницу самому — или дать ссылку своему AI

Если не хотите вручную копировать каждый шаг, можно дать своему AI ссылку на эту страницу и попросить применить методологию к вашему проекту.

Это особенно удобно, если у вас уже есть идея, но вы хотите сначала получить Product Brief, а потом перейти к starter path, структуре, AGENTS.md, архитектурной справке и плану первой безопасной итерации.

Не все AI IDE умеют читать внешние ссылки. Если ваш инструмент не может открыть URL, скопируйте нужные prompt-блоки вручную или используйте кнопку “Скопировать все шаги” и отправьте текст в чат.

Mini-prompt

Prompt для AI по этой странице

Дайте его Claude Code, Codex, Cursor, Windsurf или другому AI-агенту, если хотите пройти методологию вместе с ним.

Изучи эту страницу:
https://anmalishev.ru/expert/vibe-coding-starter.html

Возьми из нее AI Project Starter Protocol и примени к моему проекту.

Не копируй текст слепо. Адаптируй подход под мою идею.

Сначала:
1. помоги сформировать Product Brief / ТЗ;
2. задай уточняющие вопросы;
3. предложи starter path: empty folder / own template / external starter template;
4. определи active / deferred / not in scope surfaces;
5. предложи структуру проекта;
6. подготовь AGENTS.md, PROJECT_MAP.md, ARCHITECTURE.md, SECURITY.md;
7. определи package manager и deploy path;
8. если проект не игрушечный, предложи завести Architecture Source of Truth;
9. составь first safe implementation plan.

Не пиши код до подтверждения Product Brief и плана.

Консультационный формат

Можно разобрать старт проекта вместе

Если не хочется самому выбирать стек, starter path, active/deferred surfaces и правила для AI, можно пройти стартовую сессию вместе.

Формат зависит от проекта: лендинг, SaaS, бот, Telegram Mini App, мобильное приложение, backend/API или full-stack MVP требуют разной глубины.

Что обычно входит

Короткий intake идеи.
Выбор MVP scope.
Выбор starter path.
Разбор стека.
Active/deferred surfaces.
AGENTS.md и Memory Bank.
Package manager и deploy path.
План первой безопасной итерации.
Когда переходить к Hardening Protocol.

Финальный CTA

Сначала правильный старт. Потом безопасная реализация. Потом hardening.

Используйте этот протокол как стартовую рамку для нового AI/vibe-coded проекта. Если хотите пройти этот путь быстрее и не тратить недели на архитектурный хаос, можно разобрать будущий проект вместе: от intake, starter path и active/deferred surfaces до правил для AI и первого implementation plan.

Architecture Source of Truth Практические шаблоны Написать в Telegram

Стартовая архитектура AI-проекта для vibe coding

Как начать AI-проект без хаоса

Начните проект с GitHub toolkit

Что нового в v1.4

Общие изменения v1.4

Что изменилось именно на этой странице

Почему “сделай мне приложение” — плохой старт

Что ломается, если начать с пустой папки

Три способа начать AI-проект

Полный контроль над структурой

Повторяемый стек и свои правила

Быстрый full-stack skeleton

Что такое AI Project Starter Protocol

Кому полезна эта страница

Founder / solo-builder

Разработчик

Product owner

Команда

Вайбкодер

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

Если вы только начинаете

Если вы уже понимаете стек

Product Brief / ТЗ — если идеи еще нет в документе

Как может выглядеть результат

Пример: как идея превращается в стартовый план

До первой генерации кода нужно ответить на вопросы

Active и deferred surfaces: не включайте всё сразу

Базовая структура, с которой AI проще работать

Starter template помогает, но не заменяет мышление

AI-ready starter template

Как безопасно адаптировать готовый starter template

Stack Decision Framework: не выбирайте технологии наугад

Минимум зависимостей и самый быстрый старт

Баланс скорости, поддержки и deploy

Когда уже есть AI-ready starter template

Что AI должен сравнить перед выбором стека

После установки шаблона удалите bootstrap-only инструкции

Файлы, которые должны быть в хорошем AI-проекте

README.md

AGENTS.md

PROJECT_MAP.md

ARCHITECTURE.md

Architecture Source of Truth

SECURITY.md

.env.example

DEPLOYMENT.md

AUDIT_BACKLOG.md

AGENTS.md для Claude Code, Codex и Cursor: правила, чтобы AI не импровизировал

Экономия AI-токенов: сначала code discovery, потом реализация

Copyable block для AGENTS.md

AI Cost Awareness: не тратьте контекст впустую

Memory Bank для AI-проекта

Deploy path: не выбирайте облако случайно

Не стройте enterprise до первой фичи

Версионируйте prompts, если проект ведется через AI

Когда обычного ARCHITECTURE.md уже мало

Operational baseline: что заложить до production

Где хранить архитектурную справку

Перед подключением внешнего repo/API/package

Database / Load Readiness: не создавайте архитектурный тупик

Database

Load / request path

Growth path

Когда можно начинать писать фичи

Полные prompt-шаги для старта AI-ready проекта

Сначала задай вопросы

Как может выглядеть результат Prompt 0

Выбери стек и границы проекта

Создай стартовую структуру проекта

Заполни стартовую документацию

Заложи security baseline

Заложи dev/deploy baseline

Составь безопасный план первой реализации

Первая безопасная итерация — optional / advanced

Что такое маленький vertical slice

Чек-лист: проект готов к первой фиче

Definition of Done для стартового этапа

Как понять, что старт прошел хорошо

Сколько стоит плохой старт

Если проект уже начат хаотично