From 1a422a4ead5115542676129f8a75586eb73f895c Mon Sep 17 00:00:00 2001 From: Dmitry Dementev Date: Sun, 19 Jul 2026 13:50:06 -0400 Subject: [PATCH] =?UTF-8?q?docs(agents):=20=D0=B4=D0=BE=D0=B1=D0=B0=D0=B2?= =?UTF-8?q?=D0=BB=D0=B5=D0=BD=D0=B0=20=D0=BD=D0=B0=D1=81=D1=82=D1=80=D0=BE?= =?UTF-8?q?=D0=B9=D0=BA=D0=B0=20=D0=B8=D0=BD=D0=B6=D0=B5=D0=BD=D0=B5=D1=80?= =?UTF-8?q?=D0=BD=D1=8B=D1=85=20=D0=BD=D0=B0=D0=B2=D1=8B=D0=BA=D0=BE=D0=B2?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Зачем: - инженерным навыкам нужны единые правила хранения задач и документов предметной области. - Что: - настроено локальное хранилище задач с веточным жизненным циклом. - добавлены стандартные состояния triage и схема single-context. - добавлены ссылки на настройки в AGENTS.md. - Проверка: - git diff --cached --check. --- AGENTS.md | 14 +++++++++++ docs/agents/domain.md | 34 ++++++++++++++++++++++++++ docs/agents/issue-tracker.md | 47 ++++++++++++++++++++++++++++++++++++ docs/agents/triage-labels.md | 15 ++++++++++++ 4 files changed, 110 insertions(+) create mode 100644 docs/agents/domain.md create mode 100644 docs/agents/issue-tracker.md create mode 100644 docs/agents/triage-labels.md diff --git a/AGENTS.md b/AGENTS.md index 62ea917..c3d215f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -66,3 +66,17 @@ This repository contains personal dotfiles and configurations for a highly produ Документы, комментарии и объяснения держи короткими и понятными читателю, который их не писал: простые слова, короткие фразы, сложную мысль поясняй при первом упоминании (помни про менти-неспециалиста). Если понятность и буквальная точность спорят — выбирай понятность. Правило касается и текста, и заголовков разделов. Внутренние рассуждения и промежуточные пометки по ходу работы веди на английском — он экономнее по токенам (кириллица занимает примерно в 1,5–2 раза больше). На русском остаётся всё, что видит и хранит проект: итоговые ответы пользователю, документы, комментарии в коде и сообщения коммитов. + +## Agent skills + +### Issue tracker + +Задачи хранятся в отслеживаемых Git Markdown-файлах текущей ветки под `.scratch/`. Перед `merge --no-ff` они удаляются. См. `docs/agents/issue-tracker.md`. + +### Triage labels + +Используются стандартные названия состояний triage. См. `docs/agents/triage-labels.md`. + +### Domain docs + +Используется схема single-context: корневой `CONTEXT.md` и общие ADR в `docs/adr/`. См. `docs/agents/domain.md`. diff --git a/docs/agents/domain.md b/docs/agents/domain.md new file mode 100644 index 0000000..b6596de --- /dev/null +++ b/docs/agents/domain.md @@ -0,0 +1,34 @@ +# Документы предметной области + +Репозиторий использует схему single-context. + +## Что читать перед изучением репозитория + +- Корневой `CONTEXT.md`, если он существует. +- Относящиеся к задаче ADR из `docs/adr/`, если они существуют. + +Отсутствие этих файлов не считается ошибкой. Не нужно предлагать создать их +заранее: навык `/domain-modeling` создаёт их по мере появления устойчивых +терминов и архитектурных решений. + +## Структура + +``` +/ +├── CONTEXT.md +└── docs/ + └── adr/ +``` + +## Термины + +В названиях задач, предложениях по изменению, гипотезах и тестах нужно +использовать термины из `CONTEXT.md`. + +Если нужного понятия нет, сначала следует проверить, не вводится ли лишний +синоним. Настоящий пробел в словаре нужно передать навыку `/domain-modeling`. + +## Противоречия с ADR + +Если предлагаемое изменение противоречит существующему ADR, это нужно явно +указать, а не молча отменять принятое решение. diff --git a/docs/agents/issue-tracker.md b/docs/agents/issue-tracker.md new file mode 100644 index 0000000..6fb8fc7 --- /dev/null +++ b/docs/agents/issue-tracker.md @@ -0,0 +1,47 @@ +# Хранилище задач: локальные Markdown-файлы + +Задачи и спецификации этого репозитория хранятся в `.scratch/`. + +## Структура + +- Одна возможность на каталог: `.scratch//`. +- Спецификация: `.scratch//spec.md`. +- Каждая задача хранится в отдельном файле: + `.scratch//issues/-.md`. +- Нумерация задач начинается с `01`. +- Состояние triage записывается строкой `Status:` в начале файла. +- Обсуждение дописывается в конец файла под заголовком `## Comments`. + +## Жизненный цикл + +- Файлы в `.scratch/` отслеживаются Git. +- Они принадлежат рабочей ветке и считаются эфемерными. +- Перед `merge --no-ff` относящийся к ветке каталог `.scratch//` + удаляется и удаление фиксируется в этой же ветке. +- После слияния содержимое задач остаётся доступно в истории Git. + +## Публикация задачи + +Когда навык просит опубликовать задачу, нужно создать файл внутри +`.scratch//`, при необходимости создав каталог. + +## Получение задачи + +Нужно прочитать файл по переданному пути. Обычно пользователь указывает путь +или номер задачи. + +## Работа `/wayfinder` + +Карта работы хранится отдельно от дочерних задач: + +- Карта: `.scratch//map.md`. +- Дочерняя задача: `.scratch//issues/NN-.md`. +- Строка `Type:` содержит тип: `research`, `prototype`, `grilling` или `task`. +- Строка `Status:` содержит состояние `claimed` или `resolved`. +- Зависимости перечисляются строкой `Blocked by: NN, NN`. +- Задача свободна, если она открыта, не заблокирована и не занята. +- Из нескольких свободных задач первой выбирается задача с меньшим номером. +- При взятии задачи нужно установить `Status: claimed` и сохранить файл. +- При завершении нужно добавить ответ под заголовком `## Answer`, установить + `Status: resolved` и добавить краткий итог со ссылкой в раздел решений + файла `map.md`. diff --git a/docs/agents/triage-labels.md b/docs/agents/triage-labels.md new file mode 100644 index 0000000..98bf50c --- /dev/null +++ b/docs/agents/triage-labels.md @@ -0,0 +1,15 @@ +# Состояния triage + +Навыки используют пять стандартных ролей. Для локального хранилища выбранное +значение записывается в строке `Status:` файла задачи. + +| Роль навыка | Значение `Status:` | Смысл | +| --- | --- | --- | +| `needs-triage` | `needs-triage` | Задачу должен оценить сопровождающий | +| `needs-info` | `needs-info` | Нужна дополнительная информация от автора | +| `ready-for-agent` | `ready-for-agent` | Задача полностью описана и готова для агента | +| `ready-for-human` | `ready-for-human` | Задачу должен выполнить человек | +| `wontfix` | `wontfix` | Задача не будет выполняться | + +Когда навык упоминает роль triage, нужно использовать соответствующее значение +из этой таблицы.