Files

T

ddadminandClaude Opus 5 316c3ed68d docs(agents): линии ревью назначаются по разным основаниям

Зачем.
Правило склеивало два разных требования. Различие родословных нужно для
покрытия классов ошибок, свежая сессия — для независимости от рассуждений
автора; из склейки следовал вывод, что линию уместности надо отдавать
просто тому, кто не писал код. На вкусовой линии это ломается: если писал
Opus, вторым оказывается Codex, у которого вкуса нет. В прогоне #18 он вёл
линию по коду с полными руками и вернул пустой вердикт по коду
неправильной формы.

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

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

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

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

8.5 KiB

Raw Blame History

AGENTS.md

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

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

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

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

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

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

Ревью держит две линии, и назначаются они по разным основаниям. Линию дефектов ведёт тот, кто код не писал: здесь работает различие — разные родословные промахиваются по-разному. Линию уместности назначает не различие, а умение: её ведёт модель со вкусом, даже если она же писала код. Отдать её «второму исполнителю» ради независимости заманчиво, но модель без вкуса на этой линии бесполезна.

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

Язык

Пиши на ясном русском языке. Иностранные слова оставляй только там, где у термина нет устоявшегося русского аналога: имена технологий (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). Решения нумеруются подряд, дата в имени не нужна.

8.5 KiB Raw Blame History