From 18a55dd6409ed566766633aed9d36c720c6fff43 Mon Sep 17 00:00:00 2001 From: Dmitry Dementev Date: Sat, 6 Jun 2026 16:12:10 +0300 Subject: [PATCH] =?UTF-8?q?docs(adr):=20=D1=81=D0=BF=D0=B5=D0=BA=D0=B8=20?= =?UTF-8?q?=D0=B2=20docs/specs,=20handoff'=D1=8B=20=D0=B2=20.scratch/hando?= =?UTF-8?q?ffs?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Зачем: - воркфлоу эволюционировал: 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} согласованы, перекрёстные ссылки рабочие. --- AGENTS.md | 1 + docs/adr/0001-spec-adr-issue-layout.md | 3 ++ docs/adr/0002-specs-as-durable-design-docs.md | 48 +++++++++++++++++++ docs/adr/0003-handoffs-in-scratch.md | 33 +++++++++++++ 4 files changed, 85 insertions(+) create mode 100644 docs/adr/0002-specs-as-durable-design-docs.md create mode 100644 docs/adr/0003-handoffs-in-scratch.md diff --git a/AGENTS.md b/AGENTS.md index ca3d65f..6cc9fc1 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -52,6 +52,7 @@ Single-context: `CONTEXT.md` и `docs/adr/` в корне репозитория - [docs/COMMIT_RULES.md](./docs/COMMIT_RULES.md) — правила оформления коммитов. - [docs/course/](./docs/course/) — продвинутый учебный курс «со звёздочкой» на базе стенда (PRD, план обучения, стандарт уроков); начинать с [docs/course/README.md](./docs/course/README.md). - [plans/](./plans/) — legacy-планы (использовать как исторический контекст, не как источник истины). +- `.scratch/handoffs/YYYY-MM-DD-.md` — handoff'ы для продолжения работы в новой сессии (одноразовые, коммитятся, уборка best-effort; скилл `handoff` пишет сюда). См. [docs/adr/0003-handoffs-in-scratch.md](./docs/adr/0003-handoffs-in-scratch.md). ## Ограничения по структуре diff --git a/docs/adr/0001-spec-adr-issue-layout.md b/docs/adr/0001-spec-adr-issue-layout.md index 3376196..9dd540a 100644 --- a/docs/adr/0001-spec-adr-issue-layout.md +++ b/docs/adr/0001-spec-adr-issue-layout.md @@ -1,6 +1,9 @@ # ADR-0001: Раскладка спецификаций, решений и задач Принято: 2026-06-01 +Статус: частично заменён [ADR-0002](./0002-specs-as-durable-design-docs.md) — +маршрут design-спек переехал из `.scratch/` в `docs/specs/`. Остальные решения +(ADR, `CONTEXT.md`, issue-tracker) в силе. ## Решение diff --git a/docs/adr/0002-specs-as-durable-design-docs.md b/docs/adr/0002-specs-as-durable-design-docs.md new file mode 100644 index 0000000..8ccb31e --- /dev/null +++ b/docs/adr/0002-specs-as-durable-design-docs.md @@ -0,0 +1,48 @@ +# ADR-0002: Спеки как durable design-доки в `docs/specs/` + +Принято: 2026-06-06 +Статус: accepted; заменяет маршрут спек из [ADR-0001](./0001-spec-adr-issue-layout.md) +(остальные решения ADR-0001 — ADR, `CONTEXT.md`, issue-tracker — в силе). + +## Решение + +Design-спеки (инженерная аргументация «что строим и почему», без реализации) +живут в `docs/specs/YYYY-MM-DD-.md` — датированные, с статус-заголовком +(`Draft | Accepted | Implemented | Superseded`). `.scratch/` остаётся для +по-настоящему эфемерного (todo, черновые заметки), а не для курируемых спек. +ADR — для кратких durable-решений; `CONTEXT.md` — словарь. + +## Контекст + +ADR-0001 (2026-06-01) маршрутизировал все спеки в `.scratch/` как транзиентные +снимки «не для перечитывания» — таким был грилл-поток Мэтта Покока, который тогда +осваивался. С тех пор воркфлоу эволюционировал: появился гибридный скилл +`brainstorm-with-docs` (Покок + obra/superpowers), и выделился **второй жанр** — +спека как durable-аргументация архитектуры, которую перечитывают. ADR-0001 этот +жанр не предусматривал. Репозиторий учебный (и для студентов, и для собственного +исследовательского трека владельца), поэтому design-доки сами по себе — +учебный материал, а следы принятия решений ценны: отсюда отдельный +superseding-ADR, а не правка ADR-0001 на месте. + +## Рассмотренные варианты + +- **Оставить `.scratch/` для всех спек (status quo ADR-0001).** Отклонено: + durable-аргументацию перечитывают, а каталог «не для перечитывания» её прячет — + ровно та боль, что привела к пересмотру. +- **`docs/specs/` для durable-спек (принято).** Реверс отклонения из ADR-0001. + Тогда спека считалась только транзиентной, и `docs/specs/` отклонили как + «засорение курируемых доков». Страх clutter снимается датой в имени (снимок на + момент) + статус-заголовком + правилом «кристаллизовавшееся решение выносим + короткой ADR». +- **Два уровня (`.scratch/` транзиентные + `docs/specs/` durable, по каждой + спеке).** Отклонено: требует суждения «durable?» на каждую спеку и двух домов; + для репо такого размера overhead не окупается, граница плывёт. + +## Последствия + +- `docs/specs/` создаётся лениво; первая спека — редизайн Superset-дашборда. +- Дисциплина: статус-заголовок в каждой спеке; краткое решение дублируется + короткой ADR, если переживёт спеку. +- ADR-0001 получает forward-pointer на этот ADR (история не стирается). +- `to-prd`/`.scratch/PRD.md` остаётся для продуктовых требований; инженерные + design-решения идут спекой, не PRD. diff --git a/docs/adr/0003-handoffs-in-scratch.md b/docs/adr/0003-handoffs-in-scratch.md new file mode 100644 index 0000000..63186c7 --- /dev/null +++ b/docs/adr/0003-handoffs-in-scratch.md @@ -0,0 +1,33 @@ +# ADR-0003: Handoff'ы — одноразовые леса́ в `.scratch/handoffs/` + +Принято: 2026-06-06 +Статус: accepted + +## Решение + +Handoff (документ «где остановился и как продолжить» для следующей сессии/агента) +кладём в `.scratch/handoffs/YYYY-MM-DD-.md` и **коммитим**. Это одноразовые +леса́, а не след решения: durable-рассуждение живёт в спеке (`docs/specs/`), ADR и +истории коммитов, поэтому handoff можно удалять без потери трассы. Уборка — +**best-effort** (`git rm`, когда вспомнил или перед важным мержем), без +обязательной дисциплины и пост-процессов. + +## Контекст + +Раньше handoff жил в `/tmp` — слишком эфемерно (не переживает ребут/смену машины). +Рассматривали гитигнор `.scratch/handoffs/`, но он отпал по двум причинам +владельца: разработка **на нескольких машинах** (гитигнор не синхронизируется) и +планируемые **git worktrees** (untracked-файл виден только в одном worktree). +Оба требования требуют коммита. «Закоммичено на ветке, но автоматически не в +master» git без машинерии (CI-гейт) не даёт; засорение `.scratch/` считаем мягким, +т.к. это некурируемый «ящик» (читатель туда не ходит — см. ADR-0001). + +## Последствия + +- Carve-out из ADR-0001 «`.scratch/` коммитим целиком»: гитигнор не вводим, но и не + обязаны вычищать handoff'ы — они одноразовые. Курируемый скретч (если будет) + по-прежнему коммитится. +- Расположение зафиксировано в `AGENTS.md`, чтобы скилл `handoff` писал туда. +- Решение проекто-зависимое: для строгих/шаренных проектов без мультимашинности + допустим opt-in на гитигнор или CI-гейт, блокирующий `.scratch/handoffs/` в PR в + master. Здесь — коммит + best-effort.