8.3 KiB
Работа в репозитории
Граница и порядок работы
Репозиторий сам содержит инструкции, исходники, конфигурацию и входы своих проверок. Сборка, CI и обязательный маршрут чтения работают без соседних checkout. Внешний API задаётся предоставленным публичным контрактом; исходники или инструкции его реализации не являются зависимостью разработки. При нехватке требования сообщи, какое решение не определено, до его реализации. При конфликте с общим шаблоном следуй местным правилам и явному запросу пользователя. Выбирай реализацию самостоятельно, но изменение финансовой логики, публичного контракта или утверждённой семантики возвращай владельцу на согласование до зависимой работы.
Начни с результата и affected areas. До edits проследи flow/invariants, найди
owner и 1–3 примера. Код показывает механизм; случайный аналог не меняет контракт.
Выбери lightweight или SDD по Engineering Workflow из AGENTS; OpenSpec lifecycle
начинай после явного решения Change Owner.
Перед Node-командами активируй местную .nvmrc: если nvm не загружен в
non-interactive shell, загрузи установленный $HOME/.nvm/nvm.sh; затем
выполни nvm use --silent из backend. Если 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 и релизы
Работа — в ветке <type>/<issue-number>-<slug> от актуального develop,
затем PR в develop; для cross-repo ссылки укажи owner/repo#number.
Имя ветки и связь PR с реальной Issue проверяются вручную: commitlint
проверяет синтаксис commit/PR title, но не существование и соответствие Issue.
Сохраняй чужие изменения; перед commit просмотри staged paths и diff.
Commits и PR titles — Conventional Commits с parser-recognized Issue reference; допустим
spec:. Каждый commit содержит одну задачу. Исключения release и правила
ссылки — в Engineering Workflow из AGENTS. Root другого checkout не управляет этим repo.
Прямой push в main, force-push и перенос опубликованных тегов не входят в
обычную работу. Перед release/hotfix прочитай местный README, раздел «Релизы».