Тема: Часть 5. Первичная настройка проекта
Уровень сложности: Средний
Расчётное время изучения: 2-3 часа (теория + практика)
Предварительные требования: Базовое знание командной строки (bash/zsh)
Понимание основ Git (init, add, commit, status)
Знакомство с Node.js и npm (установка пакетов, package.json)
Базовые знания TypeScript (tsconfig, компиляция)
Понимание концепции .gitignore
Цели обучения: Самостоятельно создать минимальный SDD-скаффолд: Git-репозиторий, TypeScript-проект с строгим режимом, базовую структуру папок и стартовые документы
Настроить систему Knowledge Priming для агента через QWEN.md и понимать, какие файлы агент должен читать перед началом работы
Отличать первичную настройку от преждевременной реализации продуктовых фичей и уметь объяснить, почему фреймворки и базы данных откладываются до этапа конституции
Проверить готовность репозитория через Qwen Code и корректно интерпретировать его рекомендации без разрешения преждевременных изменений
Обзор: Первичная настройка проекта в методологии SDD (Specification-Driven Development) — это создание минимальной, понятной и безопасной базы для последующей работы агента. В отличие от традиционной разработки, где на этом этапе часто «сразу строят приложение», в SDD задача первичной настройки скромнее: подготовить рабочее пространство, установить границы Git, создать механизм Knowledge Priming и зафиксировать исходные пожелания участников. Этот этап не включает выбор веб-фреймворков, настройку баз данных, реализацию API или продуктовых маршрутов — все эти решения сознательно откладываются до создания конституции проекта (mission.md, tech-stack.md, roadmap.md). Учебный проект AgentClinic — вымышленная клиника психического здоровья для ИИ-агентов — служит практической моделью для освоения этих принципов. По завершении этапа у вас будет: Git-репозиторий, README.md с видением продукта, QWEN.md с правилами поведения агента, конфигурация .qwen/settings.json, минимальная TypeScript-заготовка с пустым src/index.ts, package.json со скриптом typecheck, tsconfig.json со strict: true, и первый коммит с осмысленным сообщением.
Ключевые концепции: Sdd-скаффолд: Минимальная структура проекта, достаточная для начала спецификационной работы. Включает только инфраструктурные элементы без продуктовой логики. Аналог строительных лесов до возведения стен — не дом, но безопасная площадка для работы.
Knowledge priming: Практика предварительной загрузки критически важных контекстных знаний в начало каждой сессии работы с агентом. В корпоративных текстах так называют фиксацию обязательных к прочтению файлов в QWEN.md, чтобы агент не тратил токены на угадывание структуры проекта. Это принципиально отличается от ad-hoc промптинга: правила формализованы и повторяемы.
Конституция проекта: Три документа — specs/mission.md (зачем существует проект), specs/tech-stack.md (какой стек и почему), specs/roadmap.md (какая текущая фаза и что дальше). Создаются после первичной настройки, но до них агент должен знать об их будущем существовании через QWEN.md.
Строгий режим typescript: Конфигурация strict: true в tsconfig.json, обязательная для SDD-проектов. Препятствует неявным any, необязательной проверке null и другим источникам runtime-ошибок. На этапе первичной настройки это инвестиция в надёжность всех последующих спецификаций.
Граница git-коммита: Практика осмысленного коммита после завершения этапа. Первый коммит «Initialize AgentClinic scaffold» создаёт чёткую историческую точку: до неё — инфраструктура, после — начинается конституционная работа. Помогает откатываться и отслеживать, когда были приняты какие решения.
Преждевременная реализация: Антипаттерн, когда агент или разработчик на этапе первичной настройки начинает писать бизнес-логику, выбирать фреймворки или проектировать базу данных. В SDD это нарушение принципа отложенных решений: инфраструктура отделяется от продуктовых решений во времени.
Правило трёх вещей: Агент перед первым действием должен знать три основные вещи: зачем существует проект (mission), какой стек (tech-stack) и какая текущая фаза (roadmap). Это минимальный контекст для осмысленной работы.
Практические упражнения: Название: Создание скаффолда с нуля
Проблема: Вам поручили начать учебный проект AgentClinic в новой папке. Выполните все команды первичной настройки: создайте структуру папок, инициализируйте Git и npm, установите TypeScript, создайте все необходимые файлы. Затем проверьте, что npm run typecheck проходит без ошибок, а git status показывает только неотслеживаемые файлы, которые должны быть в .gitignore.
Решение: 1. mkdir agentclinic && cd agentclinic
- git init
- npm init -y
- npm install -D typescript @types/node
- npx tsc --init
- mkdir -p src specs .qwen
- touch src/index.ts
- Отредактировать tsconfig.json: установить "strict": true
- В package.json добавить скрипт "typecheck": "tsc --noEmit"
- Создать .gitignore с содержимым из материалов курса (node_modules/, dist/, build/, .env, .env., .qwen/memory/, .idea/, .vscode/)
- Создать README.md с видением проекта
- Создать QWEN.md с блоком Knowledge Priming
- Создать .qwen/settings.json (пустой или с безопасной конфигурацией)
- Проверить: npm run typecheck (должен пройти с пустым src/index.ts)
- Проверить: git status (node_modules не должен отображаться как неотслеживаемый)
- git add README.md QWEN.md package.json package-lock.json tsconfig.json src .qwen
- git commit -m "Initialize AgentClinic scaffold"
Сложность: beginner
Название: Анализ запроса на преждевременную реализацию
Проблема: Коллега прислал вам промпт для агента: «Построй приложение AgentClinic. Настрой Hono для API, подключи SQLite через Drizzle, сделай таблицы для агентов и терапий, реализуй CRUD-маршруты. Используй TypeScript со strict режимом.» Объясните, что в этом запросе нарушает принципы SDD-первичной настройки, и перепишите запрос в соответствии с методологией.
Решение: Нарушения в исходном запросе:
- «Построй приложение» — смешивает инфраструктуру и продуктовую логику
- «Настрой Hono» — выбор веб-фреймворка на этапе, когда ещё нет конституции
- «Подключи SQLite через Drizzle» — выбор ORM и БД до tech-stack.md
- «Сделай таблицы» — схема данных без спецификации
- «Реализуй CRUD-маршруты» — продуктовые маршруты до mission.md
Переписанный запрос: «Подготовь репозиторий к SDD для проекта AgentClinic. Пока не выбирай веб-фреймворк — это решение отложим до specs/tech-stack.md. Не реализуй продуктовые маршруты — сначала создадим specs/mission.md.
Убедись, что:
- Git-репозиторий инициализирован
- TypeScript настроен со strict: true
- Есть скрипт typecheck в package.json
- Созданы папки src/, specs/, .qwen/
- QWEN.md содержит правила Knowledge Priming
- README.md отражает видение продукта
- .gitignore исключает артефакты сборки и секреты
Всё, что касается Hono, SQLite, Drizzle и бизнес-логики — зафиксируй как открытые вопросы для следующих этапов.»
Сложность: intermediate
Название: Диагностика репозитория через Qwen Code
Проблема: Вы выполнили первичную настройку, но при проверке через Qwen Code агент предложил: «Давай сразу добавим Hono для будущего API, это ускорит разработку. И я вижу, что у вас нет тестов — установлю Vitest.» Ваша задача: сформулировать ответ агенту, который остановит преждевременные действия, не нарушая при этом конструктивный тон, и объяснить, почему эти предложения выходят за рамки текущего этапа.
Решение: Ответ агенту: «Спасибо за инициативу, но давай придерживаться этапности SDD.
Hono: выбор веб-фреймворка — это продуктовое решение, которое должно попасть в specs/tech-stack.md с обоснованием. Сейчас у нас ещё нет specs/mission.md, поэтому мы не знаем, нужен ли нам вообще HTTP-сервер (возможно, проект будет CLI-утилитой или библиотекой). Отложим до этапа конституции.
Vitest: тестирование важно, но стратегия тестирования (unit, integration, e2e) зависит от архитектуры, которую мы ещё не спроектировали. Добавление Vitest сейчас создаст иллюзию готовности тестировать то, что не специфицировано. Зафиксируем в roadmap.md как задачу после создания первой спецификации фичи.
Текущая задача: проверить только инфраструктуру. Подтверди, что:
- strict режим TypeScript работает
- Git-репозиторий чистый
- QWEN.md содержит правила Knowledge Priming
- Все файлы первичной настройки на месте
Если всё в порядке — заверши сессию без изменений.»
Сложность: intermediate
Название: Аудит безопасности .qwen/settings.json
Проблема: В вашем .qwen/settings.json оказались следующие строки: { "model": "qwen-coder-plus-latest", "apiKey": "sk-qwen-2b3c...9f4a", "temperature": 0.7 } Проанализируйте проблему, определите правильное действие, выполните его и объясните, почему конфигурация модели может оставаться в репозитории, а apiKey — нет.
Решение: Проблема: apiKey — секрет, который нельзя коммитить в Git. Даже в приватных репозиториях это нарушает принцип least privilege и создаёт риск утечки при клонировании, форках или случайной публикации.
Действия:
- Немедленно отозвать ключ через панель управления провайдера API
- Удалить ключ из .qwen/settings.json
- Добавить apiKey в .gitignore как паттерн (опционально: "apiKey" или более специфичный)
- Переместить ключ в переменную окружения: export QWEN_API_KEY=sk-... в .env
- .env добавлен в .gitignore (уже должен быть)
- Обновить документацию: указать, что ключ передаётся через QWEN_API_KEY
- Сделать коммит только исправленного .qwen/settings.json
Почему model можно оставить: имя модели — это конфигурация команды, она не чувствительна, не даёт доступа к ресурсам и помогает всем разработчикам использовать единую версию. Это аналог "node": "20" в package.json — декларативное требование, а не секрет.
Почему apiKey нельзя: это credential, дающий доступ к платным ресурсам. Его коммит эквивалентен публикации пароля.
Сложность: advanced
Кейсы: Название: Команда «Быстрый старт» и технический долг конституции
Сценарий: Стартап HealthAI решил разработать платформу для телемедицины. Команда из трёх разработчиков получила доступ к Claude Code и решила «не терять время на бюрократию». За первую неделю они создали репозиторий, сразу установили Next.js, Prisma, PostgreSQL, настроили аутентификацию через Auth0 и даже сделали прототип записи на приём. Всё это было закоммичено в main без промежуточных этапов.
Задача: Через две недели инвестор потребовал pivot: продукт должен стать B2B-платформой для корпоративных клиник, а не B2C-сервисом для частных пациентов. Оказалось, что: Next.js с server components не подходит для требуемой микросервисной архитектуры; Prisma-ORM создала жёсткую связь со схемой, оптимизированной под B2C; Auth0 с корпоративным SSO требовал другого плана лицензирования; записи на приём как фича вообще отпадала — нужен был API для интеграции с существующими HIS-системами. Команда потратила 6 недель на рефакторинг вместо 3 дней на новую конституцию.
Решение: Параллельный проект в той же компании (модуль аналитики) применил SDD с правильной первичной настройкой. Они: создали скаффолд за 2 часа; потратили 3 дня на specs/mission.md, tech-stack.md, roadmap.md с участием продакта; получили одобрение конституции от инвестора; и только затем начали реализацию. Когда пришёл аналогичный запрос на pivot — изменения касались только specs/, а инфраструктура адаптировалась за день.
Результат: Проект «Быстрый старт» вышел на рынок на 4 месяца позже конкурента с SDD-подходом, потерял ключевое окно и был закрыт. Модуль аналитики стал ядром выжившей платформы. Внутренняя ретроспектива выявила: 73% технического долга «Быстрого старта» возникло до написания первой спецификации.
Извлечённые уроки: Преждевременный выбор фреймворков создаёт «замороженные решения», которые дорого размораживать
Отсутствие конституции делает невозможным аргументированный отказ от фич при pivot — всё кажется «уже вложенным»
2 часа на скучную первичную настройку экономят 6 недель рефакторинга
Инвесторы и стейкхолдеры воспринимают конституцию как документ для обсуждения, а код — как свершившийся факт
Связанные концепции: Преждевременная реализация
SDD-скаффолд
Конституция проекта
Граница Git-коммита
Название: Корпоративное внедрение Knowledge Priming в банке
Сценарий: Крупный банк внедрил агентов для сопровождения legacy-систем на COBOL. 200 разработчиков работали с разными агентами в разных командах. Проблема: каждая сессия начиналась с 10-15 минут «разогрева», когда агент угадывал структуру монорепозитория из 40 микросервисов, часто ошибаясь и предлагая нерелевантные рефакторинги.
Задача: Потеря времени масштабировалась катастрофически: 200 разработчиков × 2 сессии в день × 12 минут = 80 человеко-часов в день на «ввод в курс дела». При этом агенты периодически «галлюцинировали» архитектуру, предлагая мигрировать сервисы, которых не существовало, или игнорируя критические ограничения регулятора.
Решение: Команда платформенной инженерии создала единый скаффолд первичной настройки для всех микросервисов: стандартный QWEN.md с блоком Knowledge Priming, обязывающий читать service-manifest.yaml (аналог specs/mission.md), compliance-rules.md (регуляторные ограничения) и current-sprint.md (активная спецификация). .qwen/settings.json был стандартизирован и хранился в центральном репозитории шаблонов. При старте работы с любым сервисом разработчик клонировал шаблон, и агент сразу получал правильный контекст.
Результат: Время «разогрева» сократилось с 12 до 2 минут. Галлюцинации архитектуры снизились на 87% по метрикам качества кода (меньше откатов ревью). Шаблон стал обязательным для всех новых сервисов, а retrofit для legacy занял 3 месяца вместо запланированных 9.
Извлечённые уроки: Knowledge Priming масштабируется только при стандартизации первичной настройки
Регуляторные ограничения должны быть в обязательном прочтении — агенты не интуитивно понимают compliance
Централизованный шаблон .qwen/settings.json предотвращает дрейф конфигураций между командами
Экономия времени на разогрев компенсирует вложения в инфраструктуру шаблонов за 2-3 недели
Связанные концепции: Knowledge Priming
Правило трёх вещей
SDD-скаффолд
Советы по изучению: Проходите материал дважды: первый раз — следуя командам буквально, создавая идентичный скаффолд; второй раз — через неделю, создавая новый проект с другим именем, чтобы проверить запоминание и понимание последовательности
Ведите «дневник отложенных решений»: при каждом искушении «сразу добавить фичу» записывайте, что хотели добавить, и почему это преждевременно. Через месяц сверьтесь — были ли эти решения правильно отложены?
Используйте метод «красная команда»: попросите коллегу или воображаемого оппонента атаковать ваш скаффолд промптами «а давай сразу...» и тренируйтесь отвечать убедительным отказом с объяснением этапности
Для визуального стиля обучения: нарисуйте диаграмму переходов состояний проекта (скаффолд → конституция → спецификация фичи → реализация) и отметьте, какие файлы появляются на каждом этапе
Для аудиального стиля: диктуйте себе команды вслух перед выполнением — это активирует другие каналы памяти и помогает ловить ошибки
Для кинестетического стиля: физически удалите файлы и повторите создание скаффолда с нуля минимум 3 раза, пока команды не войдут в мышечную память
Создайте чек-лист «антисоблазны» — список вещей, которые НЕ надо делать на этом этапе, и повесьте его рядом с рабочим местом
Практикуйте объяснение концепции «скучной первичной настройки» другим: способность просто и убедительно объяснить, почему это важно — лучший индикатор понимания
Дополнительные ресурсы: Официальная документация typescript — tsconfig.json: https://www.typescriptlang.org/tsconfig — справочник по всем опциям компилятора, особенно раздел strict
Git book — основы ветвления: https://git-scm.com/book/ru/v2 — глава о коммитах и истории для понимания границ Git
Паттерн «architectural decision records» (adr): https://adr.github.io/ — методология фиксации отложенных решений, родственная SDD-конституции
Статья «knowledge priming for llm agents»: Концептуальная основа практики, рекомендуется поиск по термину в академических базах для глубокого погружения
Документация qwen code: https://github.com/QwenLM/qwen-code — актуальные рекомендации по QWEN.md и .qwen/settings.json
Интерактивный тренажёр git: https://learngitbranching.js.org/?locale=ru_RU — для закрепления понимания коммитов как границ этапов
Курс «specification-driven development»: Полный курс, из которого взят данный материал — для контекста последующих частей
Резюме: Первичная настройка в SDD — это дисциплина создания минимальной, но надёжной базы для последующей спецификационной работы. Её ключевые принципы: отделение инфраструктуры от продуктовых решений во времени; формализация контекста для агента через Knowledge Priming; строгий режим TypeScript как инвестиция в качество; осмысленные Git-границы как точки фиксации этапов. Антипаттерн — преждевременная реализация, когда «скучная» настройка превращается в «построй приложение». Правильно выполненный этап даёт: Git-репозиторий, README.md, QWEN.md с правилами первичного чтения, .qwen/settings.json, TypeScript-скаффолд со strict: true, package.json с typecheck, и первый коммит. Всё остальное — фреймворки, базы данных, бизнес-логика — сознательно откладывается до создания конституции проекта (mission, tech-stack, roadmap) и последующих спецификаций фич. Экономия от «скучности» на этом этапе измеряется неделями, сэкономленными на рефакторинге при изменениях требований.