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.