c491b5fad1
* fix(issue): align headings with create-issue validation and add SDD sections * docs(issue): add handoff, ADR, and fix CI for SDD validation * docs(pr-169): fix handoff sections --------- Co-authored-by: opencode-agent <agent@opencode.local>
43 lines
3.8 KiB
Markdown
43 lines
3.8 KiB
Markdown
# ADR-071: 7 mandatory SDD sections for all issues
|
||
|
||
## Статус
|
||
Accepted (2026-07-31)
|
||
|
||
## Контекст
|
||
|
||
Шаблоны issue body в `issue/SKILL.md` и `spec/SKILL.md` использовали заголовки (`## Что сделать`, `## Проверка`, `## Acceptance criteria`), не совпадающие с валидацией `create-issue.ts` (`## Контекст`, `## Задача`, `## Критерии приемки`). Issues, созданные по шаблону скилла, проваливали валидацию tool'а — агент получал ошибку вместо создания issue.
|
||
|
||
Кроме того, 3 обязательные секции (Контекст, Задача, Критерии приемки) не покрывали SDD-аспекты: контракты (ожидаемое поведение/API), инварианты (правила без исключений), граничные случаи (что при ошибках), out-of-scope (что НЕ делаем). Без этих секций агент угадывает границы задачи, что приводит к scope creep и неполным результатам.
|
||
|
||
## Решение
|
||
|
||
Унифицировать все шаблоны и валидацию на 7 обязательных SDD-секций — всегда, без флагов и режимов:
|
||
|
||
1. `## Контекст` — зачем + текущее состояние
|
||
2. `## Задача` — что делаем
|
||
3. `## Контракты` — ожидаемое поведение / API
|
||
4. `## Инварианты` — правила без исключений
|
||
5. `## Граничные случаи` — что при ошибках
|
||
6. `## Вне scope` — что НЕ делаем
|
||
7. `## Критерии приемки` — как проверяем
|
||
|
||
Изменения:
|
||
- `create-issue.ts`: 4 новые проверки заголовков (всегда, без флагов).
|
||
- `issue/SKILL.md`: шаблон 7 секций, обновлённые примеры.
|
||
- `spec/SKILL.md`: шаблон issue body обновлён до 7 секций.
|
||
- `bug-discovery/SKILL.md`: описание заголовков обновлено.
|
||
- Тесты (Python + TS): `VALID_BODY` 7 секций, 4 новых missing-heading теста.
|
||
|
||
## Альтернативы
|
||
|
||
1. **Двухрежимный подход (sdd flag)** — `create-issue` принимает `sdd?: boolean`, при `true` проверяет 7 секций, при `false` — 3. Отклонено: флаги создают два стандарта, агенты путаются какой режим выбрать, SDD-секции полезны для всех задач (даже кратко).
|
||
|
||
2. **Оставить 3 секции** — отклонено: не покрывает контракты, инварианты, edge cases, out-of-scope. Агент угадывает границы → scope creep.
|
||
|
||
3. **Опциональные SDD-секции (предупреждение, не error)** — отклонено: предупреждения игнорируются агентами. Только жёсткая валидация гарантирует качество.
|
||
|
||
## Последствия
|
||
|
||
- Все новые issues должны содержать 7 секций — включая баг-репорты (bug-discovery скилл обновлён).
|
||
- Существующие issues в репо не соответствуют новому формату — это не влияет на функциональность, только на создание новых.
|
||
- SDD-секции можно заполнять кратко (1-2 строки) — главное наличие заголовка.
|