Files

T

ddadminandClaude Opus 5 903b483eb1 docs(agents): контракт — кому поручать вкусовую работу, кому техническую

Зачем.
Учебная ценность записана как базовая, но вывода о выборе исполнителя из
неё не делалось. Прогон #18 показал цену пропуска: код технически
безупречен и при этом неправильной формы — монолитная задача в DAG, ручная
машинерия там, где у Airflow есть свой механизм, ноль комментариев к самому
неочевидному решению.

Что.
Новый раздел «Кому что поручать»: то, что человек будет читать и разбирать,
пишет модель с чувством меры; техническая работа без вкусовых решений — за
Codex; делить работу по подзадачам при планировании, вкусовая часть первой.
Про ревью сказано прямо: когда вкусовую линию ведёт та же родословная, что
писала код, независимость частично теряется — это плата за вкус, и гасится
она свежей сессией и другой линзой.

Проверка.
make config-test — пройдено 3, 3 и 6, ошибок 0.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

2026-07-31 15:31:16 +03:00

7.8 KiB

Raw Blame History

AGENTS.md

Короткий контракт для работы в репозитории учебной дата-платформы кликстрима.

Цель репозитория

Проект учебный: учебная ценность разработок — одна из его базовых ценностей. Стенд строится по спеке «Боевой реализм стенда (v2)».

Кому что поручать

Читатель здесь не побочный потребитель, а тот, ради кого стенд существует: код, комментарии и документы и есть продукт. Поэтому всё, что человек будет читать и разбирать, пишет модель с чувством меры — сейчас это Opus. Codex берёт техническую работу без вкусовых решений: миграции, разбор журналов и объёмного вывода, обход репозитория, повторяющиеся правки. Там его запас лимитов работает на нас, а экономить их на читаемом коде — экономия ложная: переписывать выйдет дороже, чем сразу написать хорошо.

Делить работу между ними стоит не целыми задачами, а подзадачами, и решать это при планировании. Вкусовая часть идёт первой: она задаёт форму, имена и границы, под которые механическая потом подстраивается.

Ревью держит две линии разных родословных: линию уместности ведёт Opus, линию дефектов — Codex. Когда Opus писал и код, его линия теряет часть независимости — это осознанная плата за вкус, и она гасится тем, что ревью идёт свежей сессией без общего контекста и с явно другой линзой.

Язык

Пиши на ясном русском языке. Иностранные слова оставляй только там, где у термина нет устоявшегося русского аналога: имена технологий (Kafka, ClickHouse, Airflow) и названия из кода. Если для понятия есть обычное русское слово — используй его, не выдумывай транслитерации.

Документы и комментарии держи короткими и понятными читателю, который их не писал: простые слова, короткие фразы, сложную мысль поясняй при первом упоминании. Если понятность и буквальная точность спорят — выбирай понятность.

Внутренние рассуждения и промежуточные пометки по ходу работы веди на английском — он экономнее по токенам. На русском остаётся всё, что видит и хранит проект: итоговые ответы, документы, комментарии в коде и SQL, сообщения коммитов.

Код и данные

Python — только через uv.
Изменения держать минимальными и в границах задания.
Секреты не коммитить: настройки — через .env, образец — .env.example.
При изменении инфраструктуры или DDL обновлять документацию тем же PR.
Коммиты — Conventional Commits: заголовок type(scope): результат, тело на русском по схеме Зачем / Что / Проверка.
«Грязные» записи не должны валить пайплайн: ошибки разбора уходят в таблицы *_errors.
Данные не читать целиком без необходимости: по умолчанию малый срез. Для демо и тестов быстрый повторяемый прогон важнее полноты данных.

Проверка API через MCP Context7 (обязательно)

Для спорных или меняющихся API (Airflow и провайдеры, DDL ClickHouse) сначала уточнять актуальную версию: resolve-library-id -> query-docs. Принятое решение кратко фиксировать в коде или документации: что проверили и почему выбрали этот вариант.

Задачи

Трекер — Gitea на git.dementev.space, работа через CLI tea (логин по умолчанию настроен, репозиторий определяется по git remote). Команды и подводные камни — в docs/agents/issue-tracker.md.

Спека фичи — файл в docs/specs/, источник истины, версионируется с кодом.
Корневой issue фичи — тонкий: ссылка на спеку и чек-лист дочерних issues (- [ ] #NN). Содержание спеки в issue не дублируется.
Дочерние issues — самодостаточные постановки: цель, критерии приёмки чекбоксами, границы, «сначала прочитать», команды проверки.
Итоговые решения переносятся в спеку или ADR тем же PR.
Метки триажа — пять ролей: needs-triage, needs-info, ready-for-agent, ready-for-human, wontfix. Карта и её тикеты — метки wayfinder:*.

Agent skills

Issue tracker

Задачи — в Gitea на git.dementev.space, все операции через CLI tea. См. docs/agents/issue-tracker.md.

Triage labels

Пять канонических меток триажа без переименований, уже заведены в трекере. См. docs/agents/triage-labels.md.

Domain docs

Один контекст: CONTEXT.md в корне и docs/adr/. См. docs/agents/domain.md.

Структура

Новые документы — в docs/ или в профильных подпапках, не в корне.
Состав доков v2 определяется по ходу этапов, набор предшественника не копируется (спека, раздел 12).
Имена файлов в docs/specs/ и docs/research/ — ГГГГ-ММ-ДД-краткое-имя.md: дата создания документа и слаг строчными латинскими буквами через дефис (2026-07-30-stand-v2-realism.md). Дата фиксирует, когда документ появился, и при правках не меняется: файлы сортируются по времени, а история живёт в git.
Имена файлов в docs/adr/ — NNNN-краткое-имя.md: сквозной номер из четырёх цифр и слаг (0001-stand-services.md). Решения нумеруются подряд, дата в имени не нужна.

7.8 KiB Raw Blame History