docs(agents): добавлена конфигурация инженерных навыков

- Зачем:
  - инженерным навыкам нужна единая конфигурация трекера задач и доменных документов.
- Что:
  - задокументированы Gitea workflow через tea и стандартные triage-метки.
  - добавлены доменный словарь и правила работы с ADR, research и specs.
- Проверка:
  - git diff --cached --check.
  - tea --version: 0.15.1.
This commit is contained in:
Dmitriy Dementiev
2026-08-11 11:34:18 +03:00
parent f8c6a4fc7e
commit b302e3dbb2
5 changed files with 174 additions and 0 deletions
+13
View File
@@ -75,3 +75,16 @@ All tests mock backends — no real model downloads or transcription. Key test p
- `docs/gpu.md` — GPU benchmarks, platform compatibility details - `docs/gpu.md` — GPU benchmarks, platform compatibility details
- `docs/adr/` — architecture decision records (CUDA bootstrap, batch mode, pluggable backends, compute-type defaults, ONNX-ASR evaluation) - `docs/adr/` — architecture decision records (CUDA bootstrap, batch mode, pluggable backends, compute-type defaults, ONNX-ASR evaluation)
## Agent skills
### Issue tracker
Задачи ведутся в Gitea через `tea`; GitHub используется только как зеркало, внешние PR не входят в triage. См. `docs/agents/issue-tracker.md`.
### Triage labels
Используются стандартные пять triage-меток. См. `docs/agents/triage-labels.md`.
### Domain docs
Репозиторий использует single-context layout. См. `docs/agents/domain.md`.
+33
View File
@@ -0,0 +1,33 @@
# Локальная транскрипция
Контекст описывает язык проекта для локального распознавания аудио и видео и оценки моделей распознавания.
## Language
**Движок распознавания**:
Программная среда, которая загружает и исполняет модели распознавания. Обновление движка само по себе не означает изменение выбранной модели или рекомендаций пользователю.
_Avoid_: Модель, ASR-модель
**Кандидатная модель**:
Модель распознавания, проходящая сравнительную оценку до включения в поддерживаемый каталог или рекомендации проекта. В текущей работе кандидатные модели — GigaAM Multilingual CTC, GigaAM v3 E2E CTC и GigaAM v3 E2E RNN-T.
_Avoid_: Новая модель, новый дефолт
**Сравнительная оценка**:
Эксперимент, который сопоставляет кандидатную модель с существующими моделями на репрезентативных записях и собирает данные для отдельного решения о дальнейшем использовании.
_Avoid_: Внедрение, смена дефолта
**Контрольная модель**:
Существующая модель, относительно которой оцениваются качество и скорость кандидатных моделей. В текущем эксперименте основная контрольная модель — OpenVINO Whisper medium.
_Avoid_: Старая модель, текущая модель
**Поддерживаемая модель**:
Модель, которую пользователь может выбрать явно и для которой проект обеспечивает работоспособный путь транскрипции. Этот статус не означает автоматический выбор или рекомендацию для большинства пользователей.
_Avoid_: Доступная модель, дефолт
**Модель по умолчанию**:
Поддерживаемая модель, которую проект выбирает без явного указания модели пользователем для определённого пути выполнения.
_Avoid_: Рекомендуемая модель, поддерживаемая модель
**Интеграционный smoke-тест**:
Минимальный сквозной прогон с реальным движком и моделью, подтверждающий загрузку модели и создание непустых сегментов с корректными таймкодами на короткой записи. Такой тест не является оценкой качества распознавания.
_Avoid_: Проверка качества, бенчмарк
+47
View File
@@ -0,0 +1,47 @@
# Domain Docs
Репозиторий использует single-context layout.
## Перед исследованием кода
- Прочитать корневой `CONTEXT.md`.
- Прочитать относящиеся к задаче решения из `docs/adr/`.
- Проверить относящиеся к задаче исследования в `docs/research/`.
- Проверить относящиеся к задаче спецификации в `docs/specs/`.
- Если документа нет, продолжить молча: доменные документы создаются лениво
соответствующими навыками.
## Структура
```text
/
├── CONTEXT.md
├── docs/
│ ├── adr/
│ ├── research/
│ │ └── YYYY-MM-DD-slug.md
│ └── specs/
│ └── YYYY-MM-DD-slug.md
└── src/
```
## Назначение документов
- `CONTEXT.md` — каноническая терминология предметной области.
- `docs/adr/` — принятые архитектурные решения и их обоснование.
- `docs/research/YYYY-MM-DD-slug.md` — результаты исследований, основанные на
источниках и экспериментах.
- `docs/specs/YYYY-MM-DD-slug.md` — согласованные спецификации изменений.
## Терминология
В задачах, тестах, предложениях и документации использовать термины из
`CONTEXT.md`. Не заменять их синонимами, перечисленными в `_Avoid_`.
Если нужного понятия нет, проверить, действительно ли это доменный термин.
Существенный пробел передать в `domain-modeling`.
## Конфликты с ADR
Если предлагаемое изменение противоречит существующему ADR, указать конфликт
явно и объяснить, почему решение стоит пересмотреть.
+66
View File
@@ -0,0 +1,66 @@
# Issue Tracker
Задачи проекта ведутся в Gitea-репозитории `ddmitry/local-transcriber`.
- Основной remote: `origin`
- Gitea: `https://git.dementev.space`
- CLI: `tea`
- Remote `github` является зеркалом и не используется для управления задачами
- Внешние pull request не входят в очередь triage
## Доступ
Перед операциями с задачами проверить наличие `tea`.
Если команда недоступна, остановиться и предложить пользователю установку:
```powershell
winget install --id Gitea.tea --exact
```
Не переключаться автоматически на GitHub Issues или локальные markdown-задачи.
Проверить настроенные подключения:
```powershell
tea login list
```
Если подходящего подключения нет, предложить пользователю настроить его через
`tea login add`. Не запрашивать и не выводить токены в переписке или логах.
## Прокси
Рабочее окружение использует корпоративный прокси (`HTTP_PROXY` и `HTTPS_PROXY`),
через который `git.dementev.space` недоступен: запрос к API завершается ошибкой
`EOF`. Хост нужно добавить в `NO_PROXY`.
Разделитель — **запятая**, не точка с запятой: `tea` написан на Go, а Go
разбирает `NO_PROXY` по запятым, и хост после `;` не распознаётся.
На текущую сессию:
```powershell
$env:NO_PROXY = "$env:NO_PROXY,git.dementev.space"
```
Постоянно, в пользовательских переменных окружения (значение подхватят только
новые процессы):
```powershell
[Environment]::SetEnvironmentVariable("NO_PROXY", "$env:NO_PROXY,git.dementev.space", "User")
```
## Работа с задачами
Из рабочего дерева использовать Gitea remote `origin`:
```powershell
tea issues list --remote origin
tea issues create --remote origin
tea issues edit <index> --remote origin
tea labels list --remote origin
```
За пределами рабочего дерева явно указывать репозиторий
`ddmitry/local-transcriber` и настроенный Gitea login.
+15
View File
@@ -0,0 +1,15 @@
# Triage Labels
Инженерные навыки используют пять канонических triage-ролей. В Gitea им
соответствуют одноимённые метки.
| Роль навыка | Метка Gitea | Значение |
| --- | --- | --- |
| `needs-triage` | `needs-triage` | Требует оценки сопровождающим |
| `needs-info` | `needs-info` | Ожидает дополнительной информации от автора |
| `ready-for-agent` | `ready-for-agent` | Полностью описана и готова для автономного агента |
| `ready-for-human` | `ready-for-human` | Требует реализации человеком |
| `wontfix` | `wontfix` | Выполняться не будет |
Когда навык упоминает triage-роль, следует использовать соответствующую метку
из этой таблицы.