Робочий процес, орієнтований на специфікацію
Визначайте вимоги до написання коду.
OpenSpecСпецифікаційно-орієнтована розробка для ШІ-помічників
Легка специфікація для створення та управління проєктами з ШІ-помічниками.
Ласкаво просимо. Це головний ресурс усього, що стосується OpenSpec.
OpenSpec допомагає вам та вашому ШІ-помічнику з кодування домовитися про те, що будувати, ще до написання будь-якого коду. Ви описуєте зміну, ШІ створює коротку специфікацію та список завдань, ви обидва переглядаєте один і той же план, і тоді відбувається робота. Більше ніяких несподіванок на середині шляху, коли ШІ побудував не те, що потрібно.
Якщо ви прочитаєте лише дві сторінки, нехай це будуть ці:
/opsx:propose (підказка: у чаті з ШІ, а не в терміналі). Це спантеличує майже кожного хоча б одного разу.Друга сторінка важливіша, ніж здається. OpenSpec має дві частини: інструмент командного рядка, який ви запускаєте в терміналі, та слеш-команди, які ви вводите своєму ШІ-помічнику. Розуміння різниці між ними рятує від найпоширенішого моменту спантеличення.
Найкраща звичка, яку варто винести першою: коли ви не впевнені, що будувати, почніть з
/opsx:explore. Це безпечний партнер для роздумів, який аналізує ваш код, зважує варіанти та перетворює розмиту ідею на конкретний план ще до створення будь-яких артефактів чи коду. Посібник Спочатку дослідіть пояснює, чому це працює.
Я зовсім новачок. Почніть з Початку роботи, потім швидко переглянь Основні концепції одним поглядом. Коли щось здається незрозумілим, FAQ та Глосарій завжди під рукою.
У мене є проблема, але немає плану. Це типовий випадок, і для нього є окрема відповідь: Спочатку дослідіть. Використовуйте /opsx:explore, щоб обдумати все зі ШІ, перш ніж на чомусь наполягати.
У мене велика існуюча кодова база. Вам не потрібно документувати все. Використання OpenSpec в існуючому проєкті показує, як почати роботу з реальним, зрілим кодом, не перевернувши човна.
Я просто хочу, щоб це запрацювало. Встановлення, запустіть openspec init, потім прочитайте Як працюють команди, щоб ваша перша слеш-команда потрапила в правильне місце.
Я вчуся на прикладах. Сторінка Приклади та рецепти проведе вас через реальні зміни від початку до кінця: невелика функція, виправлення помилки, рефакторинг, дослідження.
ШІ щойно створив план — що далі? Прочитайте його. Перегляд зміни показує двохвилинний прохід, який вловлює хибний напрямок, поки це ще дешево, а Написання якісних специфікацій розповідає, з чого складається план, гідний схвалення.
Я працюю в команді. OpenSpec у командній роботі показує, як зміна пов'язується з гілкою та pull request, і як колеги переглядають план до написання коду.
Я переходжу зі старого робочого процесу. Посібник з міграції пояснює, що змінилося та чому, і запевняє, що ваша існуюча робота в безпеці.
Я хочу адаптувати це до процесу своєї команди. Налаштування охоплює конфігурацію проєкту, користувацькі схеми та спільний контекст.
Щось зламалось. Усуння несправностей збирає збої, з якими люди дійсно стикаються, разом із виправленнями.
| Документ | Що ви отримаєте |
|---|---|
| Початок роботи | Встановлення, ініціалізація та виконання вашої першої зміни від початку до кінця |
| Спочатку дослідіть | Використання /opsx:explore для обдумування ідеї перед тим, як на чомусь наполягати |
| Як працюють команди | Де запускаються слеш-команди, що означає «інтерактивний режим», термінал проти чату |
| Основні концепції одним поглядом | Повна ментальна модель на одній сторінці: специфікації, зміни, дельти, архів |
| Встановлення | npm, pnpm, yarn, bun, Nix та як перевірити, що все спрацювало |
| Документ | Що ви отримаєте |
|---|---|
| Робочі процеси | Типові патерни та коли використовувати кожну команду |
| Приклади та рецепти | Повні покрокові інструкції реальних змін, готові для копіювання |
| Написання якісних специфікацій | Як виглядають сильна вимога та сценарій, і як правильно оцінити обсяг зміни |
| Перегляд зміни | Двохвилинний прохід по створеному плану до написання будь-якого коду |
| OpenSpec у командній роботі | Як зміни пов'язуються з гілками, pull request та рев'ю |
| Використання OpenSpec в існуючому проєкті | Впровадження OpenSpec у великій зрілій кодовій базі |
| Редагування та ітерація зміни | Оновлення артефактів, повернення назад, узгодження ручних правок |
| Команди | Довідник для кожної слеш-команди /opsx:* |
| CLI | Довідник для кожної термінальної команди openspec |
| Документ | Що ви отримаєте |
|---|---|
| Концепції | Розгорнуте пояснення специфікацій, змін, артефактів, схем та архіву |
| Робочий процес OPSX | Чому робочий процес гнучкий, а не прив'язаний до фаз, плюс глибокий розбір архітектури |
| Глосарій | Кожен термін визначений в одному місці |
| Документ | Що ви отримаєте |
|---|---|
| Налаштування | Конфігурація проєкту, користувацькі схеми, спільний контекст |
| Багатомовність | Генерація артефактів мовами, відмінними від англійської |
| Підтримувані інструменти | Понад 25 ШІ-інструментів, з якими інтегрується OpenSpec, та де розташовуються файли |
| Документ | Що ви отримаєте |
|---|---|
| FAQ | Швидкі відповіді на питання, які люди задають найчастіше |
| Усуння несправностей | Конкретні виправлення для конкретних збоїв |
| Посібник з міграції | Перехід від застарілого робочого процесу до OPSX |
| Документ | Що ви отримаєте |
|---|---|
| Stores: Посібник користувача | Планування в окремому репозиторії, коли ваша робота охоплює кілька репозиторіїв або команд |
| Контракт агента | Машиночитаний CLI-інтерфейс, яким керують агенти |
1. Встановлення npm install -g @fission-ai/openspec@latest
2. Ініціалізація cd your-project && openspec init
3. Дослідження (у чаті з ШІ) /opsx:explore ← необов'язково, але чудова звичка
4. Пропозиція (у чаті з ШІ) /opsx:propose add-dark-mode
5. Збірка (у чаті з ШІ) /opsx:apply
6. Архівація (у чаті з ШІ) /opsx:archive```
Кроки 1 та 2 виконуються у вашому терміналі. Решта відбуваються у чаті з вашим ШІ-помічником. Цей поділ — єдина річ, яку варто запам'ятати, і [Як працюють команди](how-commands-work.md) пояснює точно чому. Крок 3 необов'язковий, але починати з `/opsx:explore`, коли ви не впевнені, — це звичка, яку варто винести найбільше.
## Де ще отримати допомогу
- **Discord:** [discord.gg/YctCnvvshC](https://discord.gg/YctCnvvshC) для питань, ідей та допомоги.
- **GitHub Issues:** [github.com/Fission-AI/OpenSpec/issues](https://github.com/Fission-AI/OpenSpec/issues) для повідомлень про помилки та запитів нових функцій.
- **`openspec feedback "your message"`** надсилає відгук прямо з вашого терміналу (відкриває GitHub issue).
Знайшли щось у цій документації, що неправильне, застаріле або незрозуміле? Це помилка. Створіть issue або PR. Покращення документації — один із найцінніших внесків, які ви можете зробити.