90 lines
8.0 KiB
Markdown
90 lines
8.0 KiB
Markdown
# Работа в репозитории
|
||
|
||
## Граница и порядок работы
|
||
|
||
Репозиторий сам содержит инструкции, исходники, конфигурацию и входы своих
|
||
проверок. Сборка, CI и обязательный маршрут чтения работают без соседних
|
||
checkout. Внешний API задаётся предоставленным публичным контрактом;
|
||
исходники или инструкции его реализации не являются зависимостью разработки.
|
||
При нехватке требования сообщи, какое решение не определено, до его реализации.
|
||
При конфликте с общим шаблоном следуй местным правилам и явному запросу
|
||
пользователя. Выбирай реализацию самостоятельно, но изменение финансовой
|
||
логики, публичного контракта или утверждённой семантики возвращай владельцу
|
||
на согласование до зависимой работы.
|
||
|
||
Начни с результата и affected areas. До edits проследи flow/invariants, найди
|
||
owner и 1–3 примера. Код показывает механизм; случайный аналог не меняет контракт.
|
||
Работай напрямую; OpenSpec/SDD lifecycle — только по явному запросу.
|
||
Перед Node-командами активируй местную `.nvmrc`: если `nvm` не загружен в
|
||
non-interactive shell, загрузи установленный `$HOME/.nvm/nvm.sh`; затем
|
||
выполни `nvm use --silent` из frontend. Если `nvm.sh` недоступен, остановись,
|
||
не используй системный Node.
|
||
Сохраняй чужие staged/unstaged/untracked изменения и read-only архивы.
|
||
|
||
## Change scope
|
||
|
||
Сначала расширь существующего владельца. Иначе используй standard library,
|
||
платформу или установленную dependency; небольшая новая реализация допустима
|
||
при собственной ответственности. Не создавай helper/interface/wrapper ради
|
||
возможного reuse. Общее имя не означает общую бизнес-ответственность.
|
||
Сохраняй validation, authorization, atomicity, accessibility и migration safety.
|
||
|
||
После diff выполни Boy Scout review: проверь новое дублирование, owner, callers,
|
||
небольшие связанные legacy issues и соответствие local conventions. Исправляй
|
||
непосредственно связанные low-risk проблемы; широкий cleanup — отдельная задача.
|
||
|
||
## Domain values
|
||
|
||
Finite business vocabulary принадлежит одному domain/module/entity owner.
|
||
Переиспользуй его symbols; для machine codes и protocol values используй
|
||
строковые `enum`, для структуры с разными payload — discriminated union.
|
||
Сохраняй wire values; generated/external enums не переписывай вручную.
|
||
Numeric policy называй по смыслу и единицам. Индексы, `Math.max(value, 0)` и
|
||
обычные labels не выноси в constants без semantic benefit.
|
||
Локальный TypeScript/lint профиль определяет дополнительные ограничения.
|
||
|
||
## Dependencies
|
||
|
||
Проверь аналоги и direct dependencies в местном manifest до добавления пакета.
|
||
Новая dependency оправдана текущей потребностью и меньшей общей сложностью;
|
||
оцени compatibility, runtime/bundle и maintenance/security. Импортируемый пакет
|
||
объявляется напрямую; транзитивная установка не является контрактом.
|
||
Сохраняй exact versions и lockfile; воспроизводимая установка — `npm ci`.
|
||
Peer-конфликт решай совместимыми версиями без `--force`/`--legacy-peer-deps`.
|
||
Используй существующий analyzer; не добавляй второй для той же проверки.
|
||
|
||
## Test Intent
|
||
|
||
Перед нетривиальным тестом кратко определи наблюдаемый исход, regression risk,
|
||
значимые edge/error/concurrency cases и самую дешёвую надёжную boundary.
|
||
Отдельный artifact не нужен. Проверяй результат, а не private call order,
|
||
декларации, тривиальные wrappers или поведение framework.
|
||
При bug сначала воспроизведи исход. Mock race не доказывает DB atomicity.
|
||
Уровни и runnable commands выбирай по местной testing convention.
|
||
|
||
## Проверки и завершение
|
||
|
||
| Когда | Что проверить |
|
||
| --- | --- |
|
||
| Окружение новое, изменились manifest/lockfile или Node, установка сомнительна | `npm ci` до Node-проверок; одна правка кода переустановки не требует. |
|
||
| Итерация | Адресные тесты, typecheck и lint по затронутому поведению и риску. При изменении поведения добавь/обнови содержательную регрессию, если существующая проверка не ловит её; для косметики не создавай искусственный тест. |
|
||
| Итоговый code/dependency diff | Перед объявлением готовности и передачей к интеграции выполни один полный `npm run verify` на итоговых входах. Дополнительные risk checks из testing convention и явно утверждённые task checks обязательны; CI проверяет независимо. |
|
||
| Только Markdown | Проверь тексты, ссылки/якоря, маршруты чтения и `git diff --check`; application build не нужен. При изменении verification-контура проверь его работу. |
|
||
|
||
Повтори routing по staged/unstaged/new files. В отчёте по задаче/PR запиши
|
||
проверенные входы, команду, exit code, результат и ограничения. Повторяй
|
||
проверку при изменении значимых входов (включая config, dependencies и
|
||
generated artifacts), сомнении в evidence или явном запросе пользователя.
|
||
`lint:fix`/format — edits, не proof; lint не заменяет semantic/security review.
|
||
|
||
## Git и релизы
|
||
|
||
Работа — в `codex/<task>` от актуального `develop`, затем PR в `develop`.
|
||
Сохраняй чужие изменения; перед commit просмотри staged paths и diff.
|
||
Commits и PR titles — Conventional Commits; допустим `spec:`. Каждый commit
|
||
содержит одну связанную задачу. При связанной issue добавь её номер в конец
|
||
заголовка (`fix: … #12`); без issue номер не нужен. Root другого checkout
|
||
не управляет этим repo.
|
||
Прямой push в `main`, force-push и перенос опубликованных тегов не входят в
|
||
обычную работу. Перед release/hotfix прочитай местный README, раздел «Релизы».
|