Создаем приложение для карточек с GitHub SpecKit + VS Code Codex (Spec-Driven руководство)

В этом посте мы создадим локальное приложение для карточек, используя GitHub SpecKit + расширение Codex для VS Code. Мы пройдем весь процесс Spec-Driven Development от начала до конца: Спецификация → План → Задачи → Реализация.

Почему SpecKit для этого проекта? #why-speckit-for-this-project

Традиционный «вайб-кодинг» делает результаты расплывчатыми. SpecKit переворачивает сценарий: вы пишете четкую спецификацию, создаете технический план, разбиваете его на задачи и позволяете агенту реализовывать маленькие, тестируемые части в сотрудничестве с вами.

Предварительные требования #prerequisites

• VS Code с расширением Codex (войдите под своей учетной записью ChatGPT).
• Git, Python 3.11+ и uv (пакетный менеджер/лаунчер).
• macOS, Linux или Windows (для лучшей работы Codex на Windows рекомендуется WSL).

Публичный репозиторий: https://github.com/nicklaunches/flashcards-speckit

Установка Specify CLI #install-specify-cli

Постоянная установка (рекомендуется):

uv tool install specify-cli --from git+https://github.com/github/spec-kit.git
specify check

Инициализация проекта с подключением к Codex #init-project-wired-to-codex

Создайте папку и инициализируйте SpecKit для Codex:

mkdir flashcards-speckit && cd flashcards-speckit
specify init . --ai copilot
# Пользователи Windows могут добавить: --script ps

Откройте папку в VS Code и убедитесь, что панель Copilot авторизована.

Установка ограничений: Конституция #set-guardrails-constitution

В чате Copilot выполните:

/speckit.constitution
Создай принципы, ориентированные на:
- вертикальные слайсы; 90% задач < 30 минут
- React + Next.js + TypeScript; SQLite через Drizzle
- модульные тесты для основной логики; Playwright smoke-тесты
- доступность (WCAG AA); бюджет производительности: First Load JS < 160KB
- оффлайн-фIRST (без внешних сервисов, все локально)

Это создаст/обновит файл конституции, которому должны следовать будущие шаги.

Написание спецификации (что и почему) #write-the-spec-what-and-why

/speckit.specify
Создай локальное, оффлайн-приложение для карточек для быстрых сессий обучения.

Пользовательские истории:
1) Как ученик, я могу создавать колоды (название и описание).
2) Я могу добавлять, редактировать и удалять карточки (лицо/оборот).
3) Я могу изучать колоду с потоком викторины (показать лицо → перевернуть → оценить Легко/Сложно).
4) Интервальные повторения: повышение/понижение карточек по сложности для повторного появления позже.
5) Поиск: фильтрация колод и карточек по тексту.
6) Данные хранятся локально; приложение работает без сети.
7) Хороший UX: горячие клавиши (J/K/Space), адаптивная верстка, темная тема.

Критерии приемки:
- CRUD сохраняется между сессиями
- Викторина показывает прогресс и точность
- Адаптивность под мобильные устройства и десктоп

Сосредоточьтесь на что/почему. Технические решения сохраните для следующего этапа.

Создание технического плана (как) #create-the-technical-plan-how

/speckit.plan
Технологии и архитектура:
- Next.js + React + TypeScript; Tailwind для UI
- Файловая БД SQLite с Drizzle ORM; абстракция репозитория
- App Router; Server Actions для мутаций
- Модульные тесты: Vitest; E2E: Playwright (smoke-потоки)
- Утилита горячих клавиш; темная тема через CSS-переменные
- Код-сплиттинг страницы изучения; малый размер бандла

Это станет чертежом, по которому будет следовать Codex.

Разбиение на задачи #break-it-into-tasks

/speckit.tasks

Ожидайте сгенерированный tasks.md с упорядоченными шагами, путями к файлам и заглушками тестов. Дополнительные проверки качества:

• /speckit.clarify — уточнение недостаточно специфицированных моментов
• /speckit.analyze — перекрестная проверка покрытия спецификации ↔ плана
• /speckit.checklist — генерация чеклиста QA (например, «модульные тесты для английского языка»)

Реализация с помощью Codex #implement-with-codex

/speckit.implement

Codex следует tasks.md, чтобы создать каркас приложения, написать код и подключить тесты с вашим одобрением.

Запуск и тестирование #run-and-test

pnpm i
pnpm dev
# откройте http://localhost:3000

Как только вы выполните все задачи из плана: Попробуйте: создайте колоду → добавьте карточки → нажмите Study → используйте J/K/Space во время викторины.

Добавление интервальных повторений #add-spaced-repetition

Попросите Codex расширить функционал:

/speckit.tasks
Добавить планировщик:
- У каждой карточки есть бакет сложности (1..3)
- ЛЕГКО → +1 бакет (макс 3); СЛОЖНО → −1 (мин 1)
- Сессия берет больше из нижних бакетов
- Сохранять lastReviewed, nextDue

Затем снова запустите /speckit.implement.

Рекомендуемая структура репозитория #recommended-repo-structure

flashcards-speckit/
  .specify/          # спецификация, план, задачи, артефакты исследований
  .github/           # промпты/шаблоны, добавленные SpecKit
  app/               # маршруты и UI Next.js
  db/                # схема drizzle + сиды
  tests/             # модульные + e2e тесты
  README.md

Устранение неполадок #troubleshooting

• Слэш-команды не появляются в меню Codex: убедитесь, что вы инициализировали с --ai codex, находитесь в корне проекта, и Codex CLI/расширение обновлено. Если отображается только /speckit.constitution, обновите инструменты и шаблоны; некоторые интеграции с агентами исправляются со временем.
• Проверки агента не проходят: добавьте --ignore-agent-tools к specify init, чтобы пропустить проверки и все равно загрузить шаблоны.
• Windows: Codex экспериментален на Windows — используйте WSL для наилучшего результата.

Следующие идеи #next-ideas

• Импорт/экспорт колод в JSON
• Поддержка Markdown на сторонах карточек
• Карточки с изображениями
• Серии и просмотр статистики
• Умная колода «Изучить снова» с использованием nextDue

Источники #sources

• Репозиторий SpecKit (README: установка, агенты, слэш-команды) — https://github.com/github/spec-kit
• Блог GitHub: Spec-driven development with AI: Get started with a new open-source toolkit — https://github.blog/ai-and-ml/generative-ai/spec-driven-development-with-ai-get-started-with-a-new-open-source-toolkit/
• Блог GitHub: Spec-driven development — Using Markdown as a programming language — https://github.blog/ai-and-ml/generative-ai/spec-driven-development-using-markdown-as-a-programming-language-when-building-with-ai/
• Документация расширения Codex IDE — https://developers.openai.com/codex/ide/