PLDF - Progressive Learning Development Framework

PLDF (Progressive Learning Development Framework) - это образовательный фреймворк для обучения студентов разработке программного обеспечения с помощью LLM-агентов. В отличие от других фреймворков, PLDF фокусируется не только на технической реализации, но и на образовательном процессе, помогая студентам понимать ПОЧЕМУ принимаются те или иные решения.

Установка

Требования

• Python 3.11+
• uv для управления пакетами
• Git (опционально, рекомендуется)
• Один из поддерживаемых AI агентов

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

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

uv tool install pldf-cli --from git+https://github.com/MADTeacher/pldf.git

Затем используйте инструмент напрямую:

# Создать новый проект
pldf init <PROJECT_NAME>

# Или инициализировать в существующем проекте
pldf init . --ai cursor-agent
# или
pldf init --here --ai cursor-agent

# Проверить установленные инструменты
pldf check

Для обновления PLDF:

uv tool install pldf-cli --force --from git+https://github.com/MADTeacher/pldf.git

Вариант 2: Одноразовое использование

Запустите напрямую без установки:

uvx --from git+https://github.com/MADTeacher/pldf.git pldf init <PROJECT_NAME>

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

• Инструмент остается установленным и доступным в PATH
• Лучшее управление инструментами с uv tool list, uv tool upgrade, uv tool uninstall
• Более чистая конфигурация shell

Поддерживаемые AI агенты

Особенности

• ✅ Начинает с концепции проекта, а не с технических ограничений
• ✅ Дизайн UI перед техническими решениями
• ✅ Обоснованный выбор технологий с обсуждением
• ✅ Пошаговая реализация с автоматической валидацией
• ✅ Отслеживание прогресса (можно возобновить с любого шага)
• ✅ Проверка обучающегося на понимание текущего состояния проекта и принятых архитектурных решений
• ✅ Review и рефлексия для закрепления знаний

Философия

PLDF построен на принципе итерационного подхода к разработке:

1. Начинаем с концепции (команда /concept), а не с технических ограничений
2. Дизайн UI перед принятием технических решений (команда /design) - создание интерактивных HTML/CSS прототипов, которые можно открыть в браузере и исправить с помощью LLM перед тем, как переходить на следующий шаг
3. Обоснованный выбор технологий (команда /tech) - студент может предложить стек технологий для проекта, либо обсудить предлагаемые LLM варианты
4. Обоснованный выбор архитектуры (команда /architecture) - студент может предложить какие архитектурные паттерны и методологии проектирования должны использоваться в последующем процессе разработки проекта и на этапе планирования, либо обсудить предлагаемые LLM варианты
5. План деплоя (команда /deploy) - согласование того, где и как система будет развернута (окружения, CI/CD, секреты, наблюдаемость). Команда может быть вызвана как до реализации, так и после (аудит готовности и план доработок).
6. Планирование шагов разработки (команда /plan) - носит инкрементный подход, который позволяет планировать реализацию каждого последоющего шага разработки системы в отдельном чате для сохранения "контекстной чистоты" (рекомендуется завершить все шаги планирования перед переходом к следующему этапу, но никто не запрещает чередовать подход план->реализация->тестирование->план->...)
7. Пошаговая реализация (команда /implement) с автоматической валидацией LLM на предмет создания необходимых артефактов и обязательным этапом автоматизированного и ручного тестирования по завершению каждого шага
8. Тестирование. На этом этапе обучающийся должен самостоятельно запустить все автоматизированные тесты, проследить, чтобы модель исправила ошибки, не упростив при этом код самой системы, а также выполнить все этапы ручного тестирования.

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

1. Встроенная база знаний (команда /hint) предоставляет интеллектуальные подсказки для помощи студенту в процессе разработки. Они даются в виде наводящих вопросов, а не прямых ответов, чтобы стимулировать самостоятельное мышление.
2. Проверка знаний (команда /test) позволяет в любой момент пройти тестирование на основе артефактов текущего и всех предыдущих этапов проекта. LLM генерирует тесты трех типов (выбор одного варианта, выбор нескольких вариантов, свободный ответ), проводит интерактивный опрос и сохраняет детальную оценку с историей попыток.
3. Рефлексия (команда /review) предназначена для анализа созданных артефактов, выявления сильных и слабых сторон реализации, и проведения рефлексии над процессом разработки. Это критически важный этап для закрепления знаний и понимания лучших практик.

Структура этапов

Этап 0: Концепция проекта (/pldf.concept)

Определение проблемы, целевой аудитории и основных функций разрабатываемой программной системы

Особенности:

• Автоматическая инициализация GIT репозитория с детальным .gitignore (исключает секреты, зависимости, временные файлы)
• Автоматическая валидация концепции перед переходом к следующему этапу
• Запись ключевых решений (1-3 критичных на этап)
• Первый коммит в GIT после создания концепции

Выходные артефакты:

• .gitignore - файл исключений для GIT репозитория
• .pldf/concept.md - полная концепция проекта
• .pldf/project-context.md - контекст проекта со ссылками на решения

Этап 1: Дизайн UI (/pldf.design)

Создание интерактивных HTML/CSS прототипов интерфейса на основе концепции. Прототипы можно открыть в браузере (включая встроенный браузер IDE) для визуального просмотра и утверждения.

Особенности:

• Прототипы создаются как реальные HTML/CSS файлы, которые можно открыть в браузере
• Прототипы создаются с учетом платформ из концепции - мобильные паттерны для Mobile, десктопные для Desktop, адаптивные для Web
• Создание локального сервера для просмотра прототипов (Go, Python или Node.js)
• Автоматическая валидация дизайна (покрытие функций, логика потоков, соответствие платформам)
• Запись ключевых решений о паттернах UI и структуре навигации

Выходные артефакты:

• .pldf/ui-prototype/ - директория с HTML/CSS прототипами
  • index.html - главный файл с навигацией
  • [screen-name].html - HTML файлы для каждого экрана
  • README.md - инструкция по запуску локального сервера
  • Локальный сервер (если создан)
• .pldf/ui-design.md - описание дизайна с ссылками на прототипы
• .pldf/project-context.md - обновленный контекст проекта

Этап 2: Выбор технологий (/pldf.tech)

Выбор технологического стека с обоснованием и обсуждением со студентом.

Особенности:

• Предложение 2-3 вариантов для каждого компонента стека с детальным обоснованием
• Обсуждение каждого выбора со студентом
• Консультация по структуре проекта
• Автоматическая валидация выбора технологий
• Запись ключевых технологических решений
• Автоматическое обновление прогресса через скрипт

Выходные артефакты:

• .pldf/tech-stack.md - выбранный стек
• .pldf/tech-rationale.md - детальное обоснование
• .pldf/project-context.md - обновленный контекст проекта

Этап 3: Архитектура (/pldf.architecture)

Проектирование архитектуры, структуры проекта, модели данных и API контрактов на основе HTML прототипов.

Выходные артефакты:

• .pldf/architecture.md - архитектура проекта
• .pldf/data-model.md - модель данных
• .pldf/contracts/ - API контракты (создаются на основе элементов из прототипов)

Особенность: API контракты создаются на основе анализа HTML прототипов - если в прототипе нет элемента, для него не создается эндпоинт.

Этап 3.5: Деплой (/pldf.deploy)

Согласование того, где и как будет развернута система: окружения, единицы деплоя, CI/CD, секреты/конфигурация, миграции, бэкапы, наблюдаемость, стратегия релиза и отката.

Выходные артефакты:

• .pldf/deployment.md - план деплоя и эксплуатации (с ключевыми решениями)

Этап 4: План реализации (/pldf.plan)

Разбивка проекта на конкретные шаги с зависимостями и тестами.

Особенности:

• Инкрементальный подход: каждый запуск команды создает только один новый шаг (работа в пределах контекстного окна)
• Автоматическое определение следующего шага на основе зависимостей и приоритетов (P1 → P2 → P3)
• Кэширование контекста планирования (.pldf/planning-context-cache.md) для оптимизации инкрементального режима
• Визуализация прогресса планирования после каждого шага (покрытие функций P1, P2, P3)
• Автоматическое отслеживание метрик покрытия функций по приоритетам
• Запись ключевых решений о подходе к разбивке

Выходные артефакты:

• .pldf/implementation-plan.md - план реализации (обновляется инкрементально)
• .pldf/steps/step-[NN]-[name]/ - директория с описаниями шагов (создается по одному за запуск)
• .pldf/memory/progress.json - файл отслеживания прогресса с метриками планирования
• .pldf/planning-context-cache.md - кэш контекста планирования (создается в initial mode)
• .pldf/project-context.md - обновленный контекст проекта

Этап 5: Реализация (/pldf.implement)

Пошаговая реализация проекта с автоматической валидацией. HTML прототипы используются как референс для реализации.

Особенности:

• Последовательное выполнение шагов с учетом зависимостей
• Использование HTML прототипов из .pldf/ui-prototype/ как визуального гайда при реализации интерфейса
• Автоматическая валидация каждого шага перед переходом к следующему (чек-лист из 7 пунктов)
• Обязательные коммиты в GIT после каждого успешно завершенного шага (только после валидации)
• Ручное обновление .pldf/memory/progress.json после каждого успешно завершенного шага
• Возможность возобновления с любого шага (определение начального шага из .pldf/memory/progress.json)

Выходные артефакты:

• Реализованный код проекта
• Обновленный .pldf/memory/progress.json (после каждого шага)
• История коммитов GIT с коммитом для каждого завершенного шага

КРИТИЧНО!!! После завершения каждого шага реализации вы обязаны самостоятельно запустить все автоматизированные тесты, проследить, чтобы модель исправила ошибки, не упростив при этом код самой системы, а также выполнить все этапы ручного тестирования.

Этап 6: Review и рефлексия (/pldf.review)

Анализ созданных артефактов, выявление сильных и слабых сторон, сравнение с лучшими практиками и проведение рефлексии над процессом разработки.

Выходные артефакты:

• .pldf/review.md - детальный отчет с анализом и рекомендациями
• .pldf/improvements.md - приоритизированный список улучшений

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

Команда тестирования (/pldf.test)

Тестирование студента на основе артефактов текущего и всех предыдущих этапов. Команда может быть вызвана в любой момент для проверки понимания материала.

Особенности:

• Генерирует тесты трех типов: выбор одного варианта, выбор нескольких вариантов, свободный ответ
• Интерактивный режим опроса (вопросы задаются по очереди)
• Учитывает историю предыдущих попыток тестирования
• Адаптивная генерация вопросов: фокус на слабых местах, более сложные вопросы для развития
• Детальный отчет с разбивкой по этапам и темам
• Сохранение истории всех попыток с отслеживанием прогресса

Выходные артефакты:

• .pldf/assessments.json - файл с историей всех попыток тестирования и статистикой

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

Команда подсказок (/pldf.hint)

Получение интеллектуальных подсказок для помощи в процессе разработки.

Особенности:

• Подсказки даются в виде наводящих вопросов, а не прямых ответов
• Контекстные подсказки на основе текущего этапа и ошибок валидации
• Интеграция с библиотекой паттернов (автоматическое предложение релевантных паттернов)
• Предложение дополнительных ресурсов для изучения

Использование:

• /pldf.hint - подсказка для текущего этапа
• /pldf.hint concept - подсказка для этапа концепции
• /pldf.hint design api - подсказка по конкретной теме

Команда проверки безопасности (/pldf.security)

Комплексная проверка безопасности кода проекта на соответствие стандартам OWASP и законодательству по персональным данным.

Особенности:

• Настраиваемый scope проверки:
  • basic (по умолчанию) - OWASP Top 10 + законодательство ПД + зависимости + код
  • full - OWASP ASVS + Mobile/API + законодательство ПД + зависимости + код
  • Выборочные проверки: owasp-top10, asvs, mobile, api, privacy, dependencies, code
• Юрисдикция по умолчанию: 152-ФЗ РФ (настраивается на GDPR или мультиюрисдикцию)
• Security Score (0-100) с разбивкой по категориям
• Детальный отчет с примерами кода и рекомендациями
• Образовательная ценность: разные уровни сложности для начинающих и продвинутых студентов

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

• /pldf.security - базовая проверка (Top 10 + 152-ФЗ + зависимости + код)
• /pldf.security --scope full - полная проверка (ASVS + Mobile/API + 152-ФЗ + зависимости + код)
• /pldf.security --scope owasp-top10 - только OWASP Top 10
• /pldf.security --scope asvs - только OWASP ASVS
• /pldf.security --scope privacy - только законодательство по ПД
• /pldf.security --jurisdiction gdpr - проверка с GDPR вместо 152-ФЗ
• /pldf.security --scope full --jurisdiction 152fz,gdpr - полная проверка с мультиюрисдикцией

Выходные артефакты:

• .pldf/security-audit.md - детальный отчет по безопасности с Security Score

Особенность: Команда может быть вызвана в любой момент после создания кода проекта. Рекомендуется проводить проверку после каждого значимого изменения кода или перед релизом.

Быстрый старт

См. QUICKSTART.md для быстрого старта.

1. Начните с концепции:

   /pldf.concept Описание вашей идеи проекта
   

   Агент создаст концепцию, инициализирует GIT репозиторий с .gitignore и создаст первый коммит.

2. Создайте дизайн UI с HTML прототипами:

   /pldf.design
   

   После создания запустите локальный сервер (инструкция в .pldf/ui-prototype/README.md) и откройте .pldf/ui-prototype/index.html в браузере для просмотра прототипов. Важно: Утвердите дизайн перед продолжением - агент не перейдет к следующему этапу без вашего утверждения.

3. Выберите технологии:

   /pldf.tech
   

4. Спроектируйте архитектуру:

   /pldf.architecture
   

5. Создайте план реализации (инкрементально):

   /pldf.plan
   

   Команда создает один шаг за запуск. Запускайте команду повторно для планирования следующего шага. Система автоматически определит следующий шаг на основе зависимостей и приоритетов.

6. Начните реализацию:

   /pldf.implement
   

7. Проведите review и рефлексию (рекомендуется):

   /pldf.review
   

8. Проверьте безопасность кода (рекомендуется):

   /pldf.security
   

   Команда проверит код на соответствие стандартам OWASP и законодательству по персональным данным.

Просмотр HTML прототипов

После создания прототипов на этапе /pldf.design агент создаст локальный сервер для просмотра прототипов.

Запуск локального сервера

Инструкция по запуску находится в файле .pldf/ui-prototype/README.md. Агент создаст сервер на основе доступных технологий (Go, Python или Node.js).

Просмотр в Cursor

1. Запустите локальный сервер согласно инструкции в .pldf/ui-prototype/README.md
2. Откройте файл .pldf/ui-prototype/index.html
3. Нажмите Ctrl+Shift+P (или Cmd+Shift+P на Mac)
4. Выберите команду Simple Browser: Show
5. Или просто кликните правой кнопкой на файл и выберите "Open with Live Server" (если установлен)

Просмотр в обычном браузере

1. Запустите локальный сервер согласно инструкции в .pldf/ui-prototype/README.md
2. Откройте файл .pldf/ui-prototype/index.html в любом браузере

Структура директорий

Структура директории .pldf/, которая создается в проектах, использующих PLDF:

.pldf/
├── templates/             # Шаблоны для артефактов
│   ├── concept-template.md
│   ├── ui-design-template.md
│   ├── html-prototype-template.html
│   ├── index-prototype-template.html
│   ├── tech-stack-template.md
│   ├── architecture-template.md
│   ├── deployment-template.md
│   ├── implementation-plan-template.md
│   ├── step-template.md
│   ├── step-creation-checklist.md
│   ├── step-validation-template.md
│   ├── review-template.md
│   ├── security-audit-template.md
│   ├── planning-state-template.json
│   ├── planning-context-cache-template.md
│   ├── project-context-template.md
│   ├── assessment-template.json
│   └── hint-template.json
├── scripts/              # Вспомогательные скрипты
│   ├── powershell/
│   │   └── get-hint.ps1          # Получение подсказок (PowerShell)
│   └── bash/
│       └── get-hint.sh           # Получение подсказок (Bash)
├── hints/               # Система подсказок и паттернов
│   ├── hints.json      # Подсказки по этапам
│   ├── resources.json   # Внешние и внутренние ресурсы
│   ├── patterns/        # Библиотека паттернов проектирования
│   │   ├── auth-patterns/
│   │   ├── clean-architecture/
│   │   ├── data-fetching/
│   │   ├── state-management/
│   │   └── error-handling/
│   ├── security/        # База знаний по безопасности
│   │   ├── owasp-top10.md
│   │   ├── owasp-asvs.md
│   │   ├── privacy-laws.md
│   │   └── security-patterns.md
│   └── examples/        # Краткие примеры
├── ui-prototype/         # HTML/CSS прототипы (создается на этапе design)
│   ├── index.html
│   ├── [screen-name].html
│   ├── README.md        # Инструкция по запуску локального сервера
│   └── [local_server]   # Локальный сервер (если создан)
├── steps/                # Шаги реализации (создается на этапе plan)
│   └── step-[NN]-[name]/ # Директория каждого шага
│       ├── description.md        # Описание шага
│       ├── tasks.md              # Задачи шага
│       ├── tests.md              # Тесты шага
│       ├── validation.md         # Критерии валидации
│       ├── planning-context.md   # Контекст планирования с решениями
│       └── implementation-context.md # Контекст реализации с решениями
├── contracts/            # API контракты (создается на этапе architecture)
├── memory/
│   └── progress.json     # Файл отслеживания прогресса
├── planning-context-cache.md # Кэш контекста планирования (создается на этапе plan)
├── assessments.json      # История тестирования (создается командой /pldf.test)
├── concept.md            # Концепция проекта (с ключевыми решениями)
├── ui-design.md          # Описание дизайна (с ключевыми решениями)
├── tech-stack.md         # Выбранный стек технологий (с ключевыми решениями)
├── tech-rationale.md     # Обоснование выбора технологий
├── architecture.md       # Архитектура проекта (с ключевыми решениями)
├── data-model.md         # Модель данных
├── deployment.md         # План деплоя и эксплуатации (создается командой /pldf.deploy)
├── implementation-plan.md # План реализации
├── project-context.md    # 🔄 Навигационный файл (ссылки на решения)
├── security-audit.md     # Отчет по безопасности (с ключевыми решениями)
├── review.md             # Отчет review (с ключевыми решениями)
└── improvements.md       # Список улучшений

Новая система контекстов

PLDF теперь использует модульную систему контекстов:

Неитеративные этапы (concept, design, tech, architecture, security, review):

• Ключевые решения встроены в артефакт этапа (в конце файла)
• Записываются 1-3 самых критичных решения с кратким обоснованием

Итеративные этапы (plan, implement):

• Каждый шаг имеет собственные контексты:
  • planning-context.md - решения, принятые при планировании шага
  • implementation-context.md - решения, проблемы и результаты реализации
• Контексты шагов позволяют отслеживать эволюцию проекта пошагово

Навигационный файл project-context.md:

• Упрощенный файл-навигатор
• Содержит ссылки на все артефакты с решениями
• Показывает текущий статус проекта

Примечание: Команды PLDF находятся в .ххх/commands/ (не в .pldf/), так как они используются такими инструментами, как Cursor, OpenCode или SourceCraft для обработки команд.

Поддержка

Если у вас есть вопросы или предложения по улучшению фреймворка, создайте issue в репозитории проекта.

Удачи в разработке!

С Уважением, Станислав [MADTeacher] Чернышев