36 KiB
36 KiB
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 |
|
14 | complete | 152 | true |
Project Context for AI Agents
Этот файл содержит критические правила и паттерны, которым AI-агенты должны следовать при реализации кода в этом проекте. Основное внимание уделяется неочевидным деталям, которые иначе легко упустить.
Технологический стек и версии
Контрактная платформа
- Crank workspace
0.3.1; Rust Edition2024, Cargo resolver3. - MSRV: Rust
1.96; закреплённый toolchain разработки и сборки:1.96.1. - Backend: Axum
0.8, Tokio1, SQLx0.9, Reqwest0.12, Serde1, thiserror2. - Observability: metrics
0.24.6, OpenTelemetry0.32.x, tracing0.1, Sentry0.49.0. - Storage: PostgreSQL
16-alpine; опционально Valkey8-alpineчерез Redis client0.29. - UI: Node.js
22-alpine, vanilla JavaScript + Alpine.js3.15.12, js-yaml5.2.2, esbuild0.28.1; runtime image — nginx1.27-alpine. - E2E: Playwright
1.61.1, Chromium; Rust integration tests — Testcontainers0.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и MSRV1.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 должны сериализовать одну доменную модель. Изменения
serdenames/tags, discriminatorkind, 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 и компилирует их с targetes2019. - Внедрение 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-apiroutes владеют 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; новое изменение схемы всегда получает следующую contiguousi64version и 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