ddadminandClaude Opus 4.8
7e28cf06b9
- Зачем: - кириллица занимает примерно в 1,5–2 раза больше токенов; рассуждения можно вести экономнее. - Что: - добавлено правило: внутренние рассуждения и промежуточные пометки — на английском. - русский остаётся для ответов пользователю, документов, комментариев в коде и сообщений коммитов. - Проверка: - чтение AGENTS.md. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
6.0 KiB
AGENTS.md
Короткий контракт для работы в репозитории мини-демо DWH кликстрима.
Цель репозитория
Данный проект - учебный для менти. Учебная ценность разработок - одна из его базовых ценностей.
Обязательные правила
Пиши на ясном русском языке. Иностранные слова оставляй только там, где у термина нет устоявшегося русского аналога: имена технологий и инструментов (Kafka, ClickHouse, Airflow) и названия из кода. Если для понятия есть обычное русское слово — используй его, не выдумывай транслитерации (пиши «приведение в соответствие», а не «реконсиляция»; «точка отсчёта», а не «origin»).
Документы, комментарии и объяснения держи короткими и понятными читателю, который их не писал: простые слова, короткие фразы, сложную мысль поясняй при первом упоминании (помни про менти-неспециалиста). Если понятность и буквальная точность спорят — выбирай понятность. Правило касается и текста, и заголовков разделов.
Внутренние рассуждения и промежуточные пометки по ходу работы веди на английском — он экономнее по токенам (кириллица занимает примерно в 1,5–2 раза больше). На русском остаётся всё, что видит и хранит проект: итоговые ответы пользователю, документы, комментарии в коде и сообщения коммитов.
Для работы с python использовать uv.
Данные
- Не загружать
*.jsonlцеликом без необходимости: по умолчанию использовать малый срез (head -n 20..50). - Для демо и тестов важнее быстрый и повторяемый прогон, чем полнота данных.
- "Грязные" записи не должны валить пайплайн: ошибки парсинга фиксируются в ODS.
Изменения в коде
- Изменения держать минимальными и в скоупе задания (инфра, ingest, трансформации, витрины, мониторинг).
- Не коммитить секреты. Использовать
.envи.env.example. - При изменении инфраструктуры или DDL обновлять документацию в этом же PR.
- Комментарии в SQL и Bash писать на русском языке.
Проверка API через MCP Context7 (обязательно)
- Для спорных или меняющихся API (особенно Airflow/operators/providers) сначала уточнять актуальную версию через MCP Context7.
- Минимальный порядок:
resolve-library-id->query-docs. - Принятое решение фиксировать в коде и/или документации (кратко: что проверили и почему выбрали именно этот вариант).
Agent skills
Конфигурация для инженерных скиллов (набор Matt Pocock). Подробности — в docs/agents/.
Issue tracker
Локальный markdown: задачи и PRD живут файлами в .scratch/<feature>/ (коммитятся, .scratch/ не в .gitignore). GitHub Issues не используются. См. docs/agents/issue-tracker.md.
Triage labels
Пять канонических ролей, строки совпадают с именами (needs-triage, needs-info, ready-for-agent, ready-for-human, wontfix). См. docs/agents/triage-labels.md.
Domain docs
Single-context: CONTEXT.md и docs/adr/ в корне репозитория. См. docs/agents/domain.md.
Навигация по документации
- README.md — пользовательский quick start и обзор.
- docs/REPO_MAP.md — карта исполняемых артефактов и где что менять.
- docs/OPERATIONS.md — запуск, DAG-параметры, проверки и troubleshooting.
- docs/ARCHITECTURE.md — детали по слоям STG/ODS/DDS/DM.
- docs/COMMIT_RULES.md — правила оформления коммитов.
- docs/course/ — продвинутый учебный курс «со звёздочкой» на базе стенда (PRD, план обучения, стандарт уроков); начинать с docs/course/README.md.
- plans/ — legacy-планы (использовать как исторический контекст, не как источник истины).
.scratch/handoffs/YYYY-MM-DD-<slug>.md— handoff'ы для продолжения работы в новой сессии (одноразовые, коммитятся, уборка best-effort; скиллhandoffпишет сюда). См. docs/adr/0003-handoffs-in-scratch.md.
Ограничения по структуре
- Новые документы создавать в
docs/(или в профильных подпапках), не в корне репозитория.