docs(agents): контракт скиллов — трекер, метки триажа, доки и нейминг
- Зачем:
- инженерные скиллы (to-tickets, triage, wayfinder, domain-modeling) ждут
репо-локальную настройку; без неё они не знают, чем заводить issues и
какими метками размечать. Дока трекера жила ссылкой на репозиторий
предшественника — внешняя зависимость на месте источника истины.
- Что:
- заведён docs/agents/: issue-tracker.md (Gitea через tea, команды,
wayfinding, отдельный раздел про то, что «Закрывает #NN» issue не
закрывает), triage-labels.md (пять канонических меток без переименований)
и domain.md (один контекст, CONTEXT.md и docs/adr/).
- в AGENTS.md добавлен раздел «Agent skills» со ссылками на эти файлы,
ссылка на доку предшественника заменена локальной.
- в «Структуре» закреплён нейминг: ГГГГ-ММ-ДД-слаг для docs/specs/ и
docs/research/, NNNN-слаг для docs/adr/.
- Проверка:
- tea labels list — все пять меток триажа заведены в репозитории;
- tea api version — Gitea 1.27.0, команды из доки отвечают живьём.
This commit is contained in:
@@ -0,0 +1,54 @@
|
||||
# Доки предметной области
|
||||
|
||||
Как скиллам читать документацию репозитория, прежде чем лезть в код.
|
||||
|
||||
## Что прочитать до разбора кода
|
||||
|
||||
- **`CONTEXT.md`** в корне — словарь понятий проекта.
|
||||
- **`docs/adr/`** — решения. Читать те ADR, что касаются области, в которой
|
||||
сейчас работаешь.
|
||||
- **`docs/specs/`** — спеки фич; для этого репозитория спека и есть источник
|
||||
истины по тому, что строим (см. `docs/agents/issue-tracker.md`).
|
||||
|
||||
Если файла нет — **просто идти дальше молча**. Не сообщать об отсутствии и не
|
||||
предлагать создать заранее. Скилл `/domain-modeling` (через `/grill-with-docs`
|
||||
и `/improve-codebase-architecture`) заводит их лениво, когда термин или решение
|
||||
действительно понадобилось зафиксировать.
|
||||
|
||||
## Разметка: один контекст
|
||||
|
||||
Репозиторий одноконтекстный — один `CONTEXT.md` в корне и один `docs/adr/`:
|
||||
|
||||
```
|
||||
/
|
||||
├── CONTEXT.md ← пока не создан, появится по надобности
|
||||
├── docs/
|
||||
│ ├── adr/ ← 0001-stand-services.md
|
||||
│ ├── specs/
|
||||
│ └── research/
|
||||
├── dags/
|
||||
├── infra/
|
||||
└── scripts/
|
||||
```
|
||||
|
||||
Карта контекстов (`CONTEXT-MAP.md` в корне и по `CONTEXT.md` на контекст) —
|
||||
для больших многопакетных репозиториев; здесь она не нужна. Если репозиторий
|
||||
когда-нибудь разъедется на несколько контекстов, разметку менять здесь.
|
||||
|
||||
## Пользоваться словарём
|
||||
|
||||
Если в выводе называешь понятие предметной области (заголовок issue, гипотеза,
|
||||
имя теста, предложение по рефакторингу) — бери термин ровно в том виде, как он
|
||||
записан в `CONTEXT.md`. Не уходить в синонимы, от которых словарь отказался.
|
||||
|
||||
Понятия нет в словаре — это сигнал: либо выдумываешь язык, которого в проекте
|
||||
нет (стоит передумать), либо нашёл настоящий пробел (отметить для
|
||||
`/domain-modeling`).
|
||||
|
||||
## Спорить с ADR вслух
|
||||
|
||||
Если то, что ты предлагаешь, противоречит принятому ADR — сказать об этом прямо,
|
||||
а не переехать решение молча:
|
||||
|
||||
> _Противоречит ADR-0001 (состав сервисов стенда) — но открыть заново стоит,
|
||||
> потому что…_
|
||||
Reference in New Issue
Block a user