Files

T

ddadmin d3bc2f7c18 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, команды из доки отвечают живьём.

2026-07-31 09:45:19 +03:00

3.0 KiB

Raw Permalink Blame History

Доки предметной области

Как скиллам читать документацию репозитория, прежде чем лезть в код.

Что прочитать до разбора кода

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 (состав сервисов стенда) — но открыть заново стоит, потому что…

3.0 KiB Raw Permalink Blame History Unescape Escape