ddadmin
d3bc2f7c18
- Зачем:
- инженерные скиллы (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, команды из доки отвечают живьём.
55 lines
3.0 KiB
Markdown
55 lines
3.0 KiB
Markdown
# Доки предметной области
|
|
|
|
Как скиллам читать документацию репозитория, прежде чем лезть в код.
|
|
|
|
## Что прочитать до разбора кода
|
|
|
|
- **`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 (состав сервисов стенда) — но открыть заново стоит,
|
|
> потому что…_
|