Files
crank/_bmad-output/project-context.md
T

36 KiB
Raw Blame History

project_name, user_name, date, sections_completed, existing_patterns_found, status, rule_count, optimized_for_llm
project_name user_name date sections_completed existing_patterns_found status rule_count optimized_for_llm
crank Bsodfather 2026-08-02
technology_stack
language_specific_rules
framework_specific_rules
testing_rules
code_quality_style_rules
development_workflow_rules
critical_dont_miss_rules
14 complete 152 true

Project Context for AI Agents

Этот файл содержит критические правила и паттерны, которым AI-агенты должны следовать при реализации кода в этом проекте. Основное внимание уделяется неочевидным деталям, которые иначе легко упустить.


Технологический стек и версии

Контрактная платформа

  • Crank workspace 0.3.1; Rust Edition 2024, Cargo resolver 3.
  • MSRV: Rust 1.96; закреплённый toolchain разработки и сборки: 1.96.1.
  • Backend: Axum 0.8, Tokio 1, SQLx 0.9, Reqwest 0.12, Serde 1, thiserror 2.
  • Observability: metrics 0.24.6, OpenTelemetry 0.32.x, tracing 0.1, Sentry 0.49.0.
  • Storage: PostgreSQL 16-alpine; опционально Valkey 8-alpine через Redis client 0.29.
  • UI: Node.js 22-alpine, vanilla JavaScript + Alpine.js 3.15.12, js-yaml 5.2.2, esbuild 0.28.1; runtime image — nginx 1.27-alpine.
  • E2E: Playwright 1.61.1, Chromium; Rust integration tests — Testcontainers 0.27.

Воспроизводимость версий

  • Cargo.toml задаёт поддерживаемые диапазоны прямых зависимостей; Cargo.lock фиксирует точную Rust-сборку.
  • apps/ui/package.json и package-lock.json совместно задают точную frontend-сборку; использовать npm ci, а не npm install.
  • Не менять Rust toolchain, MSRV, Edition, Docker base images или зависимости попутно с функциональной задачей.
  • Dependency update оформлять отдельным изменением с обновлёнными lock-файлами и успешным just verify.
  • Не пытаться автоматически устранять несколько major-версий транзитивных crates: сначала определить владельца dependency path и проверить совместимость.
  • Проверки зависимостей требуют cargo-deny 0.20.2, cargo deny --locked и npm audit --audit-level=high.
  • Локальная версия Node.js отдельно не закреплена; до появления engines или toolchain-файла использовать Node.js 22.

Критические правила реализации

Языковые правила

Rust

  • Соблюдать Rust Edition 2024 и MSRV 1.96; более новые возможности языка требуют отдельного обновления MSRV и toolchain.
  • Возвращать ошибки через Result и типизированные enum на thiserror; сохранять стадию отказа: schema, mapping, adapter, persistence, external service или runtime.
  • В production-коде не использовать unwrap, expect, todo!, unimplemented!, dbg! и panic на путях, зависящих от пользовательского ввода, I/O или внешнего состояния.
  • Panic допустим только для внутреннего инварианта, который невозможно нарушить через публичный API; исключение должно быть локальным, объяснимым и покрытым тестом. Существующие исключения не считать прецедентом.
  • unsafe запрещён по умолчанию. Его добавление требует отдельного архитектурного решения, минимального блока и тестов вокруг границы безопасности.
  • Идентификаторы моделировать отдельными типами (OperationId, WorkspaceId и т. п.), а не String.
  • По умолчанию сохранять элементы приватными; предпочитать pub(crate) перед pub. Публичные re-export перечислять явно и не расширять API ради удобства соседнего модуля.
  • Использовать async только на I/O-границах. Schema validation, mapping и чистая доменная логика остаются синхронными; production-код crank-core не должен зависеть от Tokio.
  • Не применять лишние clone и Arc<Mutex<_>> как способ обойти проектирование ownership.
  • Использовать new() для простого гарантированно валидного создания, try_new() — когда возможна ошибка валидации.
  • JSON и YAML должны сериализовать одну доменную модель. Изменения serde names/tags, discriminator kind, defaults, timestamp format или skip_serializing_if считать изменениями wire-контракта и сопровождать contract/roundtrip tests.
  • #[allow(...)] задавать в минимальной области и только для конкретного lint; не использовать crate-wide suppressions для обхода -D warnings.

JavaScript

  • Работать в рамках текущего vanilla-JS pipeline: scripts/build.js конкатенирует файлы в упорядоченные bundles и компилирует их с target es2019.
  • Внедрение TypeScript, ESM или другого bundler/module model требует отдельного архитектурного изменения; не смешивать такую миграцию с функциональной задачей.
  • Перед добавлением top-level const, let, class или функции проверять все файлы того же bundle: после конкатенации они разделяют lexical scope и могут конфликтовать.
  • Порядок файлов в BUNDLES является зависимостью выполнения. Между bundles обмениваться только через явно именованные window.Crank* API и DOM events.
  • Общие browser API изолировать в IIFE и публиковать через согласованное пространство window.Crank*; не создавать случайные globals.
  • Playwright-тесты и Node build scripts используют CommonJS (require, module.exports); не переносить этот формат в browser-код.
  • HTTP-вызовы выполнять через window.CrankApi: dynamic path segments кодировать через encodeURIComponent, query собирать через URLSearchParams.
  • Сохранять API error contract (error.status, error.payload) и централизованную обработку 401; async UI-операции должны явно обновлять loading/error state.
  • Внешние значения выводить через textContent/DOM API. innerHTML допустим только для контролируемого шаблона при явном экранировании каждого внешнего значения.

Framework-specific правила

Backend и архитектурные слои

  • Соблюдать направление workspace-зависимостей, проверяемое scripts/check-rust-boundaries.sh: apps собирают crates, но crates не зависят от apps; crank-core находится ниже registry, runtime и adapters.
  • Boundary scripts — исполняемые guardrails, а не лазейка: не обходить их через aliases, fully-qualified paths, re-exports или перенос запрещённого вызова в helper.
  • Осознанное изменение архитектурной границы оформлять отдельным change: одновременно обновлять код, docs/architecture.md, boundary checks и их tests.
  • crank-core::domain содержит доменные типы, crank-core::ports — контракты внешних зависимостей. Core не импортирует Axum, SQLx, Reqwest, Tokio или tracing в production-коде.
  • Apps являются composition roots: они выбирают конкретные implementations ports и связывают registry, runtime, adapters и transport; не переносить это wiring в domain crates.
  • В admin-api routes владеют Axum extractors и HTTP responses; service/* владеют use cases и не импортируют Axum; routes не вызывают crank-runtime напрямую.
  • HTTP payloads и view models размещать в apps/admin-api/src/dto.rs; не протаскивать transport DTO в service/domain.
  • crank-registry владеет persistence records, requests, PostgreSQL facade и migrations; он не импортирует HTTP framework/client и не зависит от runtime/adapters.
  • crank-runtime оркестрирует execution и не зависит от registry, Axum или SQLx. Apps передают ему уже разрешённые зависимости и context.
  • Новые execution parameters добавлять в RuntimeExecutionRequest; не создавать семейство методов execute_with_*.
  • REST request/response behavior размещать в crank-adapter-rest, а не в runtime или registry.
  • MCP headers, Accept negotiation, session id и JSON/SSE semantics изменять в crank-community-mcp/src/transport.rs; изменение сопровождать transport protocol integration tests.
  • Product-код записывает метрики только через типизированный crank-metrics; имена и labels не объявлять напрямую в других crates.
  • crank-observability может зависеть от crank-metrics, но domain/runtime crates не должны зависеть от observability implementation.

UI и Alpine.js

  • Текущая UI-модель: Alpine.data(...) для локального состояния страницы/feature; общие auth, API, workspace, i18n и diagnostics находятся в window.Crank* сервисах.
  • Переход на другую модель frontend state/framework требует отдельного migration change; не смешивать две модели состояния внутри функциональной задачи.
  • Перед workspace-зависимыми запросами ожидать window.whenWorkspacesReady() и реагировать на crank:workspacechange.
  • Async response не должен обновлять экран, если workspace или request generation изменились после начала запроса; использовать identity/version guard против stale responses.
  • Сессионные и языковые изменения распространять через crank:sessionchange и crank:langchange; новые межкомпонентные события именовать crank:*, а их detail считать внутренним контрактом.
  • Event listeners регистрировать один раз на жизненный цикл страницы либо явно снимать при уничтожении повторно создаваемого компонента.
  • Protected pages загружают protected-core и проходят window.CrankAuth.guardProtectedPage(); не копировать auth guard локально.
  • Новые страницы/scripts подключать через BUNDLES и placeholders в scripts/build.js; не ссылаться из HTML на unhashed source-файлы.
  • Для async экранов поддерживать loading, error и empty states; после workspace/language change обновлять данные без полной перезагрузки.
  • Новый пользовательский текст проводить через i18n helpers и добавлять одновременно для ru и en; существующий hardcoded текст считать legacy, а не образцом.

Правила тестирования

  • Каждый тест должен доказывать наблюдаемый контракт или конкретный риск, а не повторять внутренний алгоритм реализации.
  • Исправление бага начинать с теста, воспроизводящего регрессию; затем исправлять код и подтверждать прохождение нового и существующих тестов.
  • Короткие pure unit tests приватной логики допустимы рядом с модулем. PostgreSQL, HTTP servers, fake upstreams и multi-module flows размещать в tests/.
  • Unit tests покрывают schema validation, JSONPath/mapping и чистые части crank-core; не поднимать transport/storage для проверки доменной функции.
  • Registry integration tests используют реальный PostgreSQL 16-alpine через crank-test-support/Testcontainers.
  • Получать test database через postgres_schema_url(...): общий container допустим, но каждый тест/suite использует уникальную schema. Не вводить фиксированную shared schema или внешнюю вручную настроенную test DB.
  • Runtime и adapters тестировать отдельно: request preparation, mapping stages, normalized responses, errors, confirmation, idempotency, cache/Valkey и execution metrics.
  • Admin API тестировать на поднятом Axum application с реальными service/registry boundaries; MCP transport — через Streamable HTTP contract tests.
  • Обязательные regression areas: schema validation, invalid JSONPath, YAML import/export roundtrip, version increment, publish semantics, auth profile resolution, generated draft application и полный MCP execution path.
  • Workspace/authz изменения включают negative tests на cross-workspace access, отсутствующую/неверную credential и недостаточный scope.
  • Изменения observability проверяют redaction, correlation propagation, bounded metric labels и отсутствие секретов в logs/events.
  • Изменение UI async/workspace logic должно моделировать перестановку ответов и доказывать, что stale response не перезаписывает состояние нового workspace.
  • Для readiness/eventual consistency использовать assertions или bounded polling с диагностируемым timeout. Фиксированный sleep сам по себе не является синхронизацией.
  • Fixtures хранить рядом с suite (tests/fixtures/ при повторном использовании); секреты и реальные credentials не помещать в fixtures, snapshots или failure output.
  • Не вводить глобальный процент coverage без отдельного решения: критерий — доказательство перечисленных контрактов и рисков.
  • Для Rust сначала запускать целевой suite, затем just test; перед завершением значимого backend/change — just verify. Полный Rust suite требует доступный Docker.
  • just verify не запускает UI build или Playwright. UI change требует npm ci, npm run build и Playwright:
    • изолированный экран — его spec плюс затронутые shared smoke scenarios;
    • shared auth/API/workspace/bundle code — полный npm run e2e.
  • Playwright использует существующие helpers (login, browserJson, getCurrentWorkspace, uniqueName, localized), запускается с одним worker и не зависит от порядка spec-файлов.
  • Локальный Playwright stack использует фиксированные default ports/container name; не запускать несколько default E2E stacks параллельно в одном окружении.
  • При изменении SQLx macros/schema сначала обновлять offline metadata через just sqlx-prepare <DATABASE_URL>, затем выполнять just sqlx-check и migration/integration tests.

Правила качества и стиля кода

  • Process environment читается один раз только leaf crate crank-config до observability, DB, workers и listeners. Reusable crates принимают validated values; новый runtime field добавляется через registry, generated contract, examples и just config-contract-check.

Автоматические проверки

  • Rust-код форматировать через cargo fmt --all; перед завершением выполнять just fmt-check.
  • Clippy запускается для всего workspace, всех targets и features с -D warnings. Новый warning исправлять либо подавлять минимальным обоснованным #[allow].
  • scripts/check-rust-code-health.sh проверяет все Rust-файлы, включая tests: новый файл — не более 1000 строк, inline test module — не более 500.
  • Лимиты являются верхним guardrail, а не целевым размером. Декомпозировать по ответственности раньше, если модуль становится трудно обозримым.
  • Legacy-файлы из debt baseline не должны расти выше закреплённого потолка. При изменении выделять service/route/runtime helper или переносить integration tests в tests/.
  • Не смешивать функциональное изменение с массовым форматированием, переименованием или unrelated cleanup.

Именование и организация

  • Rust modules/files/functions/variables — snake_case; types/traits — PascalCase; constants — SCREAMING_SNAKE_CASE.
  • Доменные ID оканчивать на Id, типизированные ошибки — на Error; persistence inputs/outputs сохранять в requests/records, HTTP models — в DTO layer.
  • JavaScript source files именовать lower kebab-case; browser namespaces — window.Crank*; DOM events — crank:*; Playwright specs — *.spec.js.
  • Новую логику размещать в минимальном владеющем слое. Не создавать catch-all utils/helpers, если у кода есть явный domain, transport, registry или UI owner.
  • Комментарии объясняют причину, invariant, безопасность или внешний контракт; не пересказывают очевидный код.
  • При изменении API, runtime config, deployment behavior, schema или operational procedure обновлять соответствующий документ в docs/ тем же change.

JavaScript style

  • В UI нет ESLint/Prettier-конфигурации. Следовать локальному стилю соседнего файла и проверять результат через build/E2E.
  • Не вводить новые локальные style conventions и не модернизировать legacy var/function syntax без функциональной или отдельной migration-задачи.
  • Успешный esbuild не заменяет lint/security review: отдельно проверять globals, bundle ordering, DOM sinks и async state.
  • Повторяемую browser-логику сначала искать в CrankApi, CrankAuth, CrankDom, CrankUi, i18n и других существующих window.Crank* модулях.

Зависимости и generated artifacts

  • Выбирать сначала std, затем существующие внутренние abstractions и только после этого новый внешний crate/package.
  • Не добавлять wildcard versions или дублирующую библиотеку без подтверждённого use case.
  • Rust dependency проходит cargo deny --locked; лицензия и точечные exceptions регулируются deny.toml. Не добавлять глобальные license exceptions.
  • npm dependency проходит npm audit --audit-level=high; лицензионную совместимость проверять отдельно, поскольку npm audit её не подтверждает.
  • .sqlx/query-*.json — единый generated metadata set: обновлять через just sqlx-prepare, просматривать добавленные и удалённые файлы и не редактировать их вручную.
  • Не коммитить target, apps/ui/dist, node_modules, Playwright reports/results, .tmp, .env и runtime logs; .env.example остаётся документированным шаблоном без секретов.

Правила процесса разработки

Git и pull requests

  • До изменения и перед handoff проверять git status, git diff и staged diff; сохранять существующие пользовательские правки и не включать unrelated files.
  • В репозитории нет обязательного commit-message schema. Использовать короткий предметный imperative subject в стиле соседних commits; не вводить Conventional Commits или обязательный язык без отдельного решения.
  • Не переписывать историю, не force-push и не отправлять изменения в remote без явного запроса пользователя.
  • Запрос на commit сам по себе не разрешает push, merge, создание tag, release или deployment.
  • Перед pull request выполнять just verify; для UI дополнительно npm ci, npm run build и требуемый Playwright suite.
  • Pull request contributor должен выполнить требования CLA.md; агент не должен утверждать принятие CLA от имени человека.
  • Gitea CI запускается для любого pull request и для push в main/feat/**. Это trigger configuration, а не общая branch naming policy.
  • Push feature-ветки вне feat/** не запускает push-trigger CI, но CI всё равно запустится после открытия pull request.

Границы Community

  • Не добавлять функциональность за пределами Community scope: текущая реализация — REST как источник MCP tools, простая admin auth, agent keys, single self-hosted deployment, PostgreSQL и optional Valkey/Redis. Resources, Prompts, Tasks и Load Runs являются разрешённым planned расширением, но до реализации имеют только planned, gap или blocked в docs/capability-inventory.json; только implemented считается pass.
  • scripts/check-community-scope.sh по умолчанию сканирует только git ls-files и не видит untracked files.
  • Перед handoff убедиться, что новые файлы tracked/staged, либо проверить их напрямую: python3 scripts/check-community-scope.py --root . --files <paths...>.
  • Capability baseline использует три независимые оси: implementation status, execution verdict и evidence mode. Полный pass — только implemented + automated + pass; retry-pass остаётся flaky, а skipped/not-run/manual-only не повышаются до pass.
  • Изменение canonical baseline artifact требует нового baseline_version и lowercase SHA-256 exact bytes в docs/capability-baseline/manifest.json. Raw browser reports, credentials, payloads и host paths не являются canonical evidence.
  • Не обходить forbidden markers переносом текста, aliases или переименованием.
  • community-scope: allow=<marker> использовать только для необходимого упоминания; исключение не разрешает out-of-scope реализацию и должно быть очевидно обосновано в diff.
  • Не коммитить AGENTS.md, TASKS.md, .env, secrets, private addresses или локальные настройки.

CI, deployment и release

  • Изменение CI проверять относительно .gitea/workflows/*.yml и Gitea Actions runner; не добавлять GitHub-only assumptions без проверки совместимости.
  • Push в main после Rust, UI, E2E и image-smoke jobs автоматически запускает production Deploy. Merge/push в main требует явного разрешения пользователя с пониманием этого side effect.
  • Создание tag v* запускает Community Release с публикацией artifacts/images. Commit или push authorization не включает разрешение создавать release tag.
  • Release pipeline включает quality gates, release builds, UI E2E, Compose validation, image scan, SBOM и публикацию artifacts/images.
  • Source of truth для Community deployment находится в deploy/community/; изменения проверять через Compose validation, image build и authenticated product smoke.
  • Миграции Community должны быть обратно совместимы с предыдущей версией приложения; schema/deploy change включает readiness, backup и rollback considerations.
  • После deployment-sensitive изменений выполнять соответствующий staging smoke из docs/deploy-and-staging-smoke.md.
  • Результаты фиксировать в docs/staging-regression-notes.md без credentials, tokens, private payloads или secret-bearing raw logs.
  • CI/CD secrets загружаются через OpenBao. Не печатать secret values, не переносить их в workflow files и не заменять secret storage committed .env.

Критические правила, которые нельзя упустить

Изоляция workspace и секреты

  • Для workspace-зависимого запроса получать WorkspaceId только из проверенного auth/request context. Отсутствующий или чужой workspace не заменять default workspace.
  • Проверять принадлежность каждой сущности workspace, а не только существование её ID. Чужая сущность должна давать безопасный not found/denied, без раскрытия метаданных.
  • Любое состояние, результат или разрешение, зависящие от workspace, agent или auth context, кэшировать с полным security scope. Глобальный кэш допустим только для доказанно инвариантных данных.
  • В operation/config/YAML/static headers хранить только auth_profile_ref или ссылку на secret, но не credential в открытом виде.
  • Stored secret после передачи шифруется и не возвращается через create/get/list/rotate. Raw API key разрешено показать только в ответе создания; сохранять только безопасный prefix/hash.
  • Один и тот же master key должен использоваться admin-api и MCP. Его смена без процедуры re-encryption/migration делает сохранённые secrets недоступными.
  • До сериализации логов и ошибок удалять authorization, cookies, tokens, secret values и чувствительные payload/query fields. Не логировать произвольные структуры через Debug.

Outbound execution и safety controls

  • SSRF-policy применять к фактическому адресу каждого соединения после DNS resolution. Блокировать loopback, private, link-local и service addresses; redirects и system proxy оставлять выключенными.
  • Deny rules имеют приоритет над allow rules. Семантика outbound policy должна совпадать в admin-api и MCP.
  • Timeout, response-byte limit и concurrency limit применять до неограниченного ожидания или накопления response body.
  • В MCP публиковать и исполнять только опубликованные версии operations; draft не должен становиться доступным через обходной lookup.
  • Confirmation token привязывать к workspace, agent, operation, version и fingerprint входа; соблюдать TTL и single-use consumption.
  • Approval проверяет workspace/agent/operation/version, status, expiry и полномочия approval key. Переходы состояния должны быть атомарными; bypass safety flow недопустим.
  • Idempotency key scope включает workspace, agent, operation и version; fingerprint входа обязателен. Повтор того же key с другим входом является конфликтом.
  • IdempotencyOutcomeUnknown не ретраить автоматически: внешний side effect мог уже произойти.
  • Если обязательное coordination/cache/approval store недоступно, safety-механизм должен fail closed, а не молча отключаться.

Observability без утечек и cardinality explosion

  • Имена log events и наборы metric labels должны быть статическими и низкокардинальными. Не помещать ID, URL, имена, request text или error text в labels.
  • Входящий x-request-id валидировать и ограничивать; недопустимое значение заменять UUIDv7. Request ID распространять отдельно от trace identity.
  • Системные correlation headers должны переопределять mapped/static пользовательские headers.
  • При публикации Prometheus не только на loopback требовать отдельный bearer token.
  • Недоступность OTLP/Sentry после успешного startup не должна менять product response или readiness. Явно заданная некорректная конфигурация должна завершать startup безопасной ошибкой.
  • Events, previews и JSON-поля ограничивать по размеру с сохранением корректного UTF-8/JSON; не обрезать сериализованные данные произвольным byte slice.

Миграции и восстановление данных

  • crank-registry::MigrationAuthority — единственный владелец runtime DDL и append-only migration sequence. Не изменять смысл, statement order или ledger checksum immutable baseline v1; новое изменение схемы всегда получает следующую contiguous i64 version и lowercase SHA-256 exact source bytes.
  • Admin API и MCP startup выполняют только read-only compatibility preflight. Схему изменяет исключительно controlled crank-migrate apply; Community Compose обязан завершить one-shot migration job до запуска обоих сервисов.
  • Каждая migration должна быть transactional, иметь owner/phase/compatibility/backfill metadata и выполняться под canonical transaction-level PostgreSQL advisory lock. Никаких down, force, implicit repair или локальных ledger/runner в runtime crates.
  • Schema changes должны поддерживать rolling update и rollback предыдущей версии; destructive change проводить поэтапно через expand/migrate/contract.
  • PostgreSQL и artifact storage считать единым backup set; процедура restore должна восстанавливать согласованную пару.
  • Изменение любого правила этого раздела требует negative regression tests на соответствующую границу безопасности или целостности.

Правила использования

Для AI-агентов:

  • Прочитать этот файл до начала реализации или ревью кода.
  • Следовать всем применимым правилам; при сомнении в security/safety выбирать fail-closed вариант.
  • Не менять описанные границы или контракты попутно с функциональной задачей.
  • Обновлять файл, когда в проекте появляется новый неочевидный и устойчивый паттерн.

Для людей:

  • Сохранять файл компактным и ориентированным на практические решения агентов.
  • Обновлять версии и правила вместе с изменением соответствующих контрактов проекта.
  • Периодически удалять устаревшие правила и сведения, ставшие очевидными из автоматических guardrails.

Последнее обновление: 2026-08-02