Project Autopilot требует чёткой структуры — ai/backlog.md, ai/features/, ai/diary/ — но ни один инструмент не проверял это автоматически: файл мог случайно исчезнуть, статус в таблице оказаться невалидным, spec — потерять связь с feature-файлом. Решение — PA-check, read-only skill и агент, который сканирует проект и выдаёт структурированный отчёт, не модифицируя ни одного файла.
Стек AI-инструментов
Работал с Project Autopilot — системой автономной разработки с AI-агентами, постоянно проверял состояние проекта вручную. Это отнимало время и создавало риск пропустить критическую ошибку до того, как она попадёт в реализацию.
Что такое PA-проект
Project Autopilot (PA) — это система автономной разработки с AI агентами. PA-проект — это проект, который управляется через специальные AI команды, где AI агенты выполняют задачи на основе спецификаций и контролируются через backlog.
PA умеет: автоматически планировать задачи на основе идей, создавать детальные спецификации, запускать AI агентов для реализации кода, проверять качество через review агентов, и автоматически коммитить изменения.
Структура PA-проекта:
- ai/backlog.md — таблица с задачами, статусы (NEW, SPARKED, READY, IN_PROGRESS, BLOCKED, DONE), ссылки на спецификации
- ai/features/ — директория с спецификациями в Markdown формате
- ai/diary/ — записи о проблемах и выводах для улучшения системы
PA работает через команды: /spark для создания спецификаций, /planner для планирования реализации, /coder для написания кода, /review для проверки качества, /check для валидации состояния проекта.
Решение
Я создал PA-check — skill и агент для OpenCode, который проверяет состояние PA-проекта в read-only режиме. Сканирует только ai/backlog.md и ai/features/, не модифицирует файлы, выводит отчёт: OK/WARNINGS/BROKEN.
Структура проверок
- Structure: наличие ai/, ai/backlog.md, ai/features/, ai/diary/
- Backlog: парсинг markdown таблицы, валидация колонок (ID, Title, Type, Status, Spec, Updated)
- Status validation: NEW, SPARKED, READY, IN_PROGRESS, BLOCKED, DONE
- Spec validation: связь с ai/features/
- Git: read-only проверки (uncommitted changes, sync status)
- Safety: проверка на secrets (.env*, keys, tokens)
// Пример валидации статусов
const VALID_STATUSES = ["NEW", "SPARKED", "READY", "IN_PROGRESS", "BLOCKED", "DONE"]
function validateStatus(status: string): boolean {
return VALID_STATUSES.includes(status)
}Вывод отчёта
PA-check выводит структурированный отчёт с детализацией по секциям:
> PA CHECK REPORT
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
>> STRUCTURE: OK
✓ ai/
✓ ai/backlog.md
✓ ai/features/
✓ ai/diary/
>> BACKLOG: WARNINGS
⚠ Invalid status in row 5: "IN_REVIEW" (expected: NEW/SPARKED/READY/IN_PROGRESS/BLOCKED/DONE)
>> SPECS: OK
✓ All specs linked to features
>> GIT: BROKEN
✗ Uncommitted changes detected (12 files)
✗ Branch is behind remote by 3 commits
>> SAFETY: OK
✓ No secrets detected
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
STATUS: BROKEN (2 broken, 1 warning)
Read-only валидация — это ключевой принцип. PA-check проверяет проект, но не модифицирует файлы. Это предотвращает случайные изменения и сохраняет целостность данных.
PA-check ловит нарушения структуры проекта, но не следит за стилем кода, который пишут AI-агенты — для этого нужен отдельный слой правил. Про то, как заставить агентов реально соблюдать конвенции проекта, — в посте про AGENTS.md.
Pro Tips: Как получить максимум
- Используйте PA-check перед коммитами — это предотвратит попадание сломанного кода в репозиторий.
- Интегрируйте в CI/CD — автоматическая проверка при каждом push'е гарантирует целостность проекта.
- Следуйте рекомендациям — PA-check выводит next actions для исправления найденных проблем.
- Проверяйте Safety секцию — случайно закоммиченные секреты — это критическая уязвимость.
Common Pitfalls: Где люди ошибаются
- Игнорируют WARNINGS — предупреждения не критичны сейчас, но превратятся в BROKEN в будущем.
- Не проверяют Git статус — uncommitted изменения создают конфликт между spec и реализацией.
- Проверяют вручную вместо PA-check — автоматический валидатор никогда не пропустит то, что упустит человек.
- Модифицируют файлы во время проверки — PA-check работает в read-only режиме, но если вы измените файлы параллельно, результаты будут некорректны.