ddadmin
18a55dd640
- Зачем:
- воркфлоу эволюционировал: design-спекам нужен durable-дом, а handoff'ам —
стабильное место вместо эфемерного /tmp.
- Что:
- ADR-0002: design-спеки переезжают в docs/specs/YYYY-MM-DD-*.md (superseding ADR-0001).
- ADR-0003: handoff'ы — одноразовые леса́ в .scratch/handoffs/, коммитятся, уборка best-effort.
- ADR-0001 помечен как частично заменённый; AGENTS.md описывает место handoff'ов.
- Проверка:
- docs/adr/000{1,2,3} согласованы, перекрёстные ссылки рабочие.
44 lines
3.0 KiB
Markdown
44 lines
3.0 KiB
Markdown
# ADR-0001: Раскладка спецификаций, решений и задач
|
|
|
|
Принято: 2026-06-01
|
|
Статус: частично заменён [ADR-0002](./0002-specs-as-durable-design-docs.md) —
|
|
маршрут design-спек переехал из `.scratch/` в `docs/specs/`. Остальные решения
|
|
(ADR, `CONTEXT.md`, issue-tracker) в силе.
|
|
|
|
## Решение
|
|
|
|
Рабочую документацию разносим по времени жизни:
|
|
|
|
- **Транзиентные спеки фич** — markdown в `.scratch/<feature>/PRD.md`, коммитятся
|
|
(`.scratch/` не в `.gitignore`). Снимок понимания на момент работы, не для
|
|
перечитывания. Продюсер — `to-prd`.
|
|
- **Долговечные решения** — ADR в `docs/adr/NNNN-<slug>.md`. Глубина по весу
|
|
решения: однострочник для обратимого, с вариантами и последствиями — для
|
|
необратимого.
|
|
- **Доменный язык** — глоссарий `CONTEXT.md` в корне. ADR и `CONTEXT.md` ведёт
|
|
`grill-with-docs`.
|
|
- **Issue-tracker** — локальный markdown в `.scratch/`, без GitHub Issues. Триаж
|
|
пробуем с дефолтными метками; `to-issues` пока не применяем — для текущего
|
|
объёма работ задачи редко распадаются на независимые вертикальные срезы.
|
|
|
|
## Контекст
|
|
|
|
Раньше и спеку, и решение нёс один громоздкий spec-документ: он плохо заменял
|
|
ADR — слишком объёмен и привязан к фиче. Разделение слоёв: спека — «что строим
|
|
сейчас», ADR — «какое решение приняли и почему», глоссарий — «как называем
|
|
сущности».
|
|
|
|
## Рассмотренные варианты
|
|
|
|
- **`docs/specs/` закоммичено** — спеки среди курируемых доков. Отклонено:
|
|
транзиентные артефакты засоряют `docs/`, который навигирует читатель.
|
|
- **`.scratch/` в `.gitignore`** — спеки эфемерны. Отклонено: по необратимым
|
|
решениям рассуждение за ними надо сохранить, а минимальный ADR его не держит.
|
|
- **GitHub Issues как трекер** — отклонено пока: поток держим локально, файлами.
|
|
|
|
## Последствия
|
|
|
|
- `.scratch/` **не** вносим в `.gitignore` — иначе теряется история спек и задач.
|
|
- Если ADR окажутся самодостаточными, спеки можно будет гитигнорить — переключение
|
|
одной строкой, без слома схемы.
|