Перейти к содержанию

Engineering Canon v5.0

Я не могу создать файл для прямого скачивания, но я могу предоставить полный текст документа в формате, который легко скопировать и сохранить.

Инструкция: 1. Скопируйте весь текст из блока ниже 2. Создайте файл matsiis-engineering-canon-v5.0.md 3. Вставьте текст и сохраните

Вот полный документ MATSIIS ENGINEERING CANON v5.0:

# MATSIIS ENGINEERING CANON — FINAL v5.0 (ENHANCED CONTROL SYSTEM)

**Стандарт:** MATSIIS Core Engineering Canon  
**Версия:** v5.0 (Enhanced & Audited)  
**Статус:** SYSTEM / ENFORCEMENT / OPERATING STANDARD / AI-GOVERNED  
**Дата вступления:** Immediate  
**Назначение:** Полный стандарт контроля разработки, задающий обязательные правила для проектирования, кодинга, тестирования, безопасности, эксплуатации, code review, AI-assisted development и допуска изменений в production.  
**Целевая аудитория:** AI-агенты разработки, Senior Engineers, Architects, DevOps, Security Officers.

---

## 1. PURPOSE & MISSION

Данный документ определяет не только правила разработки, но и **механизм контроля качества разработки**. Это не рекомендация, это закон инженерной системы MATSIIS.

**Цель стандарта:**
1.  Исключить слабый, уязвимый, неархитектурный и трудно сопровождаемый код.
2.  Превратить инженерные принципы в исполняемые правила (Executable Rules).
3.  Сделать AI и разработчиков подотчётными единому стандарту.
4.  Создать единый механизм допуска изменений в production (Gate System).
5.  Обеспечить предсказуемость, надёжность, масштабируемость и безопасность решений MATSIIS.
6.  **Minimize Human Intervention:** Код должен быть настолько качественным на этапе генерации, чтобы требовать минимального участия дорогих специалистов для правки.

**Этот стандарт обязателен для:**
*   Frontend (React, Mobile)
*   Backend (API, Services)
*   Database & Persistence (Prisma, SQL, NoSQL)
*   Infrastructure-as-Code (Terraform, Cloudflare Workers)
*   AI-generated code (LLM Outputs)
*   Internal Tools & Automation
*   SaaS-products & Edge/Runtime solutions

---

## 2. CORE OPERATING PRINCIPLE

В MATSIIS запрещён подход:  
`«Сначала сделать быстро, потом когда-нибудь исправить»`.

**Обязательный подход:**  
`DESIGN → VERIFY → IMPLEMENT → TEST → OBSERVE → REVIEW → RELEASE`

Любое инженерное решение должно быть:
*   **Secure by design** (Безопасность встроена, не добавлена позже)
*   **Maintainable by design** (Легко менять без ломки соседних модулей)
*   **Operable by design** (Понятно, как этим управлять в продакшене)
*   **Testable by design** (Можно покрыть автотестами без моков всего мира)
*   **Observable by design** (Видно состояние системы через логи/метрики)
*   **Reviewable by design** (Код читается как книга, а не как головоломка)

**[AI CONTEXT]:** Перед генерацией кода AI обязан убедиться, что решение соответствует всем 6 принципом. Нарушение любого принципа = REJECT.

---

## 3. SYSTEM MODEL

Любая разработка рассматривается как целостная инженерная система. Нарушение любого уровня считается инженерным дефектом.

```mermaid
graph TD
    A[Business Goal] --> B[Domain Model]
    B --> C[Architecture]
    C --> D[Interfaces / Contracts]
    D --> E[Implementation]
    E --> F[Testing]
    F --> G[Security Controls]
    G --> H[Observability]
    H --> I[Release Readiness]
    I --> J[Production Operation]

[AI CONTEXT]: Перед генерацией кода AI обязан определить, на каком уровне системы находится задача. Запрещено решать задачи уровня Business Goal методами уровня Implementation без прохождения промежуточных этапов.

4. AUTHORITY LEVELS

Внутри MATSIIS действуют 4 уровня нормативности. AI должен интерпретировать их строго.

4.1 MUST

Обязательное требование. Невыполнение = дефект = REJECT.
Пример: MUST validate all inputs.

4.2 SHOULD

Сильная рекомендация. Отклонение требует обоснования в комментарии кода или ADR (Architecture Decision Record).
Пример: SHOULD use dependency injection.

4.3 MAY

Допустимый вариант, если не нарушает MUST/SHOULD. Выбор за разработчиком/AI на основе контекста.
Пример: MAY choose between library A or B if both meet security standards.

4.4 FORBIDDEN

Запрещённая практика. Обнаружение = автоматический REJECT и блокировка merge.
Пример: FORBIDDEN hardcoded secrets.

5. SEVERITY MODEL

Все нарушения классифицируются по критичности. Это определяет реакцию CI/CD и AI-агента.

5.1 CRITICAL (BLOCKER)

Приводит к высокому риску для безопасности, данных, денег, доступа или production-стабильности.

Примеры: * Отсутствие server-side validation. * Hardcoded secrets (keys, passwords, tokens). * Broken access control (IDOR, privilege escalation). * SQL/command injection risk. * Отсутствие авторизации на критичном действии. * Удаление/изменение данных без safeguards (soft delete, confirmations). * Отсутствие тестов на критичную финансовую или расчётную логику. * Прямой вывод внутренней ошибки (stack trace) пользователю. * Нарушение transaction safety в критичных операциях.

Решение: Автоматический REJECT. Код не может быть создан или принят.

5.2 HIGH (MAJOR)

Существенно ломает архитектуру, сопровождаемость или операционную надёжность.

Примеры: * Бизнес-логика в UI или Route Handler. * Сильная связность домена с ORM или Framework. * Отсутствие централизованной обработки ошибок. * Отсутствие контрактной схемы API (OpenAPI/JSON Schema). * Нет rollback strategy для чувствительного релиза. * Performance regression > 20% on critical path.

Решение: REJECT до исправления, если изменение идёт в shared/core/production path.

5.3 MEDIUM (MINOR)

Ухудшает качество, но не создаёт немедленного критического риска.

Примеры: * Дублирование логики (DRY violation). * Длинные функции (>50 строк) без декомпозиции. * Неудачное именование (неясный intent). * Плохая декомпозиция модулей. * Тесты недостаточно изолированы.

Решение: Исправить до merge или оформить как контролируемый Tech Debt с дедлайном.

5.4 LOW (COSMETIC)

Косметические и стилистические отклонения.

Примеры: * Форматирование (если не ломает дифф). * Мелкие naming issues (camelCase vs snakeCase в локальной области). * Неидеальная структура комментариев.

Решение: Исправить планово или через авто-форматтер.

6. DECISION GATE MODEL

Ни один код не считается допустимым, пока он не прошёл все контрольные ворота. AI должен симулировать прохождение этих ворот перед выдачей ответа.

GATE Name Check Question Fail Action
GATE 1 Business Fit Решает ли изменение реальную задачу? Не вводит ли избыточную сложность? REDESIGN
GATE 2 Architecture Fit Не смешаны ли слои? Соответствует ли решение domain-first? REFACTOR
GATE 3 Security Fit Есть ли validation, auth, safe secrets? Нет ли OWASP рисков? REJECT
GATE 4 Quality Fit Читаемость, модульность, testability, error handling. FIX
GATE 5 Runtime Fit Можно ли это мониторить, логировать, откатить? FIX
GATE 6 Release Fit Есть ли тесты, миграции, release awareness? BLOCK MERGE

Правило: Любой провал на Gate 3 (Security) или Gate 6 (Release) при критичном изменении = REJECT.

7. ENGINEERING PRINCIPLE TEMPLATE

Каждый инженерный принцип в MATSIIS трактуется в формате: 1. Принцип (Название) 2. Зачем (Business/Technical Value) 3. Обязательные требования (MUST) 4. Нарушения (Violations) 5. Anti-patterns (Что нельзя делать) 6. Good / Bad examples (Конкретный код) 7. Применение (React, Fastify, Prisma, Cloudflare) 8. Severity of violations (Уровень критичности) 9. Review questions (Чеклист для проверки)

8. SOLID — ENFORCEMENT LAYER

8.1 SRP — Single Responsibility Principle

Зачем: Снижение связанности, упрощение тестирования, локализация изменений, снижение риска регрессий.

MUST: * Одна функция выполняет одну смысловую задачу. * Один модуль отвечает за один тип ответственности. * UI не содержит бизнес-логику. * Route handler не содержит доменную логику. * ORM слой не содержит бизнес-правила.

Нарушения: * Функция одновременно валидирует, сохраняет, рассчитывает и уведомляет. * Компонент одновременно рендерит UI, ходит в сеть, рассчитывает бизнес-правила и сохраняет данные.

Anti-patterns: God Function, Fat Controller, Smart Component, Service Blob.

Bad Example: 

async function processInvoice(input) {
  validateInvoice(input); // Validation
  const tax = calculateTax(input); // Logic
  const saved = await prisma.invoice.create({ data: { ...input, tax } }); // DB
  await sendInvoiceEmail(saved.customerEmail); // Side Effect
  return saved;
}

Good Example: 

// Domain
function calculateInvoiceTax(input) {}
// Application
async function saveInvoice(repo, data) {}
async function notifyInvoiceIssued(notifier, invoice) {}
// Orchestrator
async function processInvoiceUseCase(input) {
   // Calls above functions sequentially
}

Stack Specifics: * React: MUST: компонент отвечает за представление; hooks инкапсулируют client-side orchestration. FORBIDDEN: fetch/save logic прямо в render body. * Fastify: MUST: route = transport + schema binding + delegation. FORBIDDEN: бизнес-правила в handler. * Prisma: MUST: Prisma отвечает за persistence. FORBIDDEN: tax/business policy inside Prisma helper. * Cloudflare: MUST: Worker layer отвечает за delivery. FORBIDDEN: тяжелая доменная логика в request handler.

Severity: Smart UI with business-critical logic = HIGH. Security-sensitive mixed responsibilities = CRITICAL.

Review Questions: * Можно ли изменить transport без переписывания domain logic? * Можно ли протестировать бизнес-правило без UI и Fastify? * Можно ли сменить Prisma без переписывания use case?

8.2 OCP — Open/Closed Principle

Зачем: Безопасное расширение без ломки уже работающего поведения.

MUST: * Расширение через композицию, стратегии, адаптеры, конфигурацию. * Изменения не должны требовать переписывания стабильного ядра.

Anti-patterns: Shotgun Surgery, Giant Switch, Inheritance Abuse.

Bad Example: 

function calculatePrice(type) {
  if (type === 'retail') return amount;
  if (type === 'vip') return amount * 0.8;
  // ... adding more ifs forever
}

Good Example: 

interface PricingStrategy { calculate(amount): number }
// Implementations: RetailStrategy, VipStrategy

Stack Specifics: * React: MUST: расширение UI через composition; reusable components/hooks. FORBIDDEN: гигантские conditional trees. * Fastify: MUST: расширение через plugins/services/adapters. * Prisma: MUST: persistence abstraction стабильна. * Cloudflare: MUST: расширение через middleware/composable handlers.

Severity: Giant switch in business-critical pricing = HIGH.

Review Questions: * Можно ли добавить новый вариант поведения без переписывания существующего ядра? * Будут ли старые тесты оставаться валидными?

8.3 LSP — Liskov Substitution Principle

Зачем: Обеспечение корректной подстановки реализаций.

MUST: * Реализация не должна ломать ожидания интерфейса. * Mock/fake implementation ведёт себя семантически схоже с production.

Anti-patterns: Broken Interface Contract, Fake That Lies, Surprise Nullability.

Stack Specifics: * React: MUST: shared component contract стабилен. * Fastify: MUST: service interfaces одинаково ведут себя в production/test. * Prisma: MUST: repo implementation не нарушает semantic contract. * Cloudflare: MUST: edge adapter не меняет бизнес-контракт.

Severity: Contract mismatch in critical data flow = HIGH.

8.4 ISP — Interface Segregation Principle

Зачем: Исключить избыточные зависимости.

MUST: * Интерфейсы минимальны и целевы. * Потребитель зависит только от нужных ему операций.

Anti-patterns: Fat Interface, Kitchen Sink Contract.

Stack Specifics: * React: props contracts не перегружены. * Fastify: service interfaces узкие и use-case specific. * Prisma: repo interfaces разделены по смыслу. * Cloudflare: runtime adapters expose only required operations.

Severity: Overshared interfaces in core services = MEDIUM/HIGH.

8.5 DIP — Dependency Inversion Principle

Зачем: Изоляция domain/application от framework и инфраструктуры.

MUST: * Domain не зависит от Fastify, Prisma, Cloudflare bindings. * Use case зависит от abstract contracts. * Infrastructure реализует contracts.

Anti-patterns: Framework-Centric Core, ORM-Driven Domain, Runtime Lock-In.

Bad Example: 

class CreateInvoiceService {
  async execute(data) {
    return prisma.invoice.create({ data }); // Direct dependency
  }
}

Good Example: 

class CreateInvoiceUseCase {
  constructor(private readonly invoiceRepo: InvoiceRepository) {} // Abstraction
}

Stack Specifics: * React: UI зависит от hooks/view models/contracts. * Fastify: handler делегирует use case. * Prisma: Prisma implementation скрыта за repository boundary. * Cloudflare: bindings передаются в infrastructure adapter.

Severity: Domain coupled to ORM/framework in shared core = HIGH.

Review Questions: * Можно ли заменить Prisma без переписывания domain? * Зависит ли core logic от конкретного framework?

9. DRY — DON'T REPEAT YOURSELF

Зачем: Исключить дублирование бизнес-логики, снизить риск разноса поведения.

MUST: * Единая бизнес-формула должна жить в одном месте. * Shared validation/schema/policy logic не копируется между модулями.

Anti-patterns: Copy-Paste Programming, Divergent Formula, Schema Drift.

Stack Specifics: * React: переиспользуем hooks/components/utilities. * Fastify: shared validation, error mapping, auth guards. * Prisma: shared query fragments/repository patterns. * Cloudflare: reusable middleware/adapters.

Severity: Duplicated critical calculation = HIGH. Duplicated trivial markup = LOW.

Review Questions: * Если завтра меняется формула/политика, где её нужно править? * Есть ли риск, что одна копия уже устарела?

10. KISS — KEEP IT SIMPLE

Зачем: Снижение когнитивной нагрузки и стоимости поддержки.

MUST: * Решение должно быть не сложнее, чем требует задача. * Abstraction only when it removes real duplication or instability.

Anti-patterns: Overengineering, Abstract Factory Explosion, Indirection Hell.

Stack Specifics: * React: простой local state предпочтительнее сложного global orchestration. * Fastify: простой route-service-usecase flow. * Prisma: не строить сложный query DSL без необходимости. * Cloudflare: не усложнять edge pipeline лишними layers.

Severity: Unjustified complexity in core path = MEDIUM/HIGH.

11. YAGNI — YOU AREN'T GONNA NEED IT

Зачем: Предотвращение преждевременной сложности.

MUST: * Не строить функционал, которого нет в подтверждённой потребности. * Не вводить опции/варианты/абстракции "на всякий случай".

Anti-patterns: Future-Proofing Gone Wrong, Phantom Requirements, Dead Abstractions.

Severity: Speculative complexity in shared core = MEDIUM/HIGH.

12. SEPARATION OF CONCERNS

Зачем: Управляемость системы, изоляция изменений.

MUST: * UI, transport, application, domain, infrastructure, config и observability разделены. * Config/secrets не смешиваются с бизнес-логикой.

FORBIDDEN: * Database access in component. * Business rules in route handler. * Domain logic in migration scripts.

Severity: Mixing concerns in critical flows = HIGH.

13. SECURITY ENFORCEMENT STANDARD

[AI CONTEXT]: Это критический раздел. Любое нарушение здесь = CRITICAL REJECT.

13.1 Global Security Rule

Любой код считается небезопасным, пока не доказано обратное. (Presume Guilty until Proven Secure).

13.2 MUST

  • Validate ALL external input (Server-side is source of truth).
  • Enforce authentication where required.
  • Enforce authorization for protected actions (Ownership checks).
  • Never trust client-provided identity/role/amount/status.
  • No secrets in source code (Use Env/Bindings).
  • Least privilege for tokens, bindings, service accounts.
  • Safe error handling (No leakage).
  • Sensitive actions are auditable (Logs).

13.3 FORBIDDEN

  • Hardcoded secrets (API keys, DB passwords).
  • Implicit trust in client payload.
  • "Admin by flag from frontend".
  • SQL/raw query without parameter safety.
  • Dynamic command execution from uncontrolled input.
  • Exposing internal stack traces to user.
  • Logging secrets, tokens, passwords, raw sensitive payloads (PII).

13.4 OWASP Top 10 Mapping

AI должен проверять код на соответствие OWASP Top 10:

OWASP ID Risk MATSIIS Enforcement
A01 Broken Access Control Check ownership on every write
A02 Cryptographic Failures Use HTTPS, hash passwords (argon2/bcrypt)
A03 Injection Use parameterized queries (Prisma handles this)
A04 Insecure Design Threat model required for critical features
A05 Security Misconfiguration Default passwords, verbose errors
A06 Vulnerable Components No known CVEs in dependencies
A07 Identification Failures MFA, rate limiting, strong sessions
A08 Software & Data Integrity Verify signatures, CI/CD integrity
A09 Security Logging & Monitoring Log auth failures, access violations
A10 SSRF Validate URLs, restrict outbound traffic

13.5 Stack Specifics

  • React: Client validation = UX aid ONLY. Do not store secrets in client code.
  • Fastify: Schema validation mandatory. Auth guards explicit.
  • Prisma: Access scoping enforced before persistence. Transactions for consistency.
  • Cloudflare: Secrets via bindings. Verify signatures/webhooks.

13.6 Severity

  • Missing validation on financial mutation = CRITICAL.
  • Hardcoded API key = CRITICAL.
  • Protected action without ownership check = CRITICAL.

13.7 Review Questions

  • Кто именно имеет право на действие?
  • Где именно проверяется доступ?
  • Что произойдёт, если payload подделан?
  • Что попадёт в logs при ошибке?

14. API AND CONTRACT STANDARD

Зачем: Согласованность интеграций, предсказуемость API.

MUST: * API contract defined before or together with implementation (OpenAPI/JSON Schema). * Request/response schemas explicit. * Error format consistent (RFC 7807 preferred). * Versioning explicit (URL or Header). * Backward compatibility assessed.

FORBIDDEN: * Ad-hoc response shapes. * One endpoint returning unpredictable structures. * Undocumented breaking change.

Stack Specifics: * React: Frontend consumes stable contracts through typed client. * Fastify: Route schemas mandatory for non-trivial endpoints. * Prisma: DB schema changes must not silently break API. * Cloudflare: Edge handlers preserve agreed API contract.

Severity: Undocumented breaking API change = HIGH.

15. ERROR HANDLING STANDARD

Зачем: Предсказуемость поведения, безопасность, диагностируемость.

MUST: * No silent failure. * Errors categorized (Domain, Validation, System). * User-facing errors safe (Generic messages). * Operational errors logged with enough context (Request ID, User ID). * Domain/business errors handled deliberately.

FORBIDDEN: * Empty catch blocks. * Swallowing promise rejection. * Throwing raw infra error directly to client. * Boolean false instead of structured failure in critical paths.

Anti-patterns: Silent Catch, Error-as-Noise, Raw Stack to Client, Mystery Failure.

Stack Specifics: * React: Render safe fallback states. * Fastify: Centralized error handling. * Prisma: DB constraint errors translated intentionally. * Cloudflare: Edge failures logged with request correlation.

Severity: Silent failure on money/data mutation = CRITICAL/HIGH. Raw stack leak = HIGH/CRITICAL.

16. TESTING ENFORCEMENT STANDARD

16.1 Global Rule: Ни одна критичная логика не считается production-ready без проверок.

MUST: * Unit tests for domain logic. * Integration tests for API/integration boundaries. * Regression test for every meaningful bug fix. * Migration-sensitive changes validated. * Happy path AND failure path covered for critical flows.

SHOULD: * Contract tests for important service boundaries. * Smoke tests for deployment-critical flows. * Scenario tests for high-value business processes.

FORBIDDEN: * "Works manually" as sole evidence. * Merge critical calculation logic without tests. * Skip tests for auth/access/payment/data integrity path.

Stack Specifics: * React: Test UI state transitions and critical user flows. * Fastify: Test validation, access, success, failure at route/use case boundary. * Prisma: Test transaction behavior and data integrity. * Cloudflare: Test runtime-specific behavior for headers, caching, bindings.

Severity: * No tests for critical financial logic = CRITICAL. * No tests for protected mutation = CRITICAL. * No regression test after serious bug = HIGH.

17. OBSERVABILITY STANDARD

Зачем: Видеть состояние системы, ускорять диагностику (MTTR).

MUST: * Structured logs (JSON). * Correlation/Request ID where applicable. * Error tracking for meaningful failures (Sentry/Datadog). * Business-significant events observable (InvoiceCreated, PaymentFailed). * Health signals for critical services (Readiness/Liveness probes).

SHOULD: * Metrics for latency/error rate/throughput. * Traceability across distributed flows. * Dashboards for critical operations.

FORBIDDEN: * Only console debugging in production mindset. * Logs without context (Who, What, When, Where). * Missing traceability on critical workflows.

Stack Specifics: * React: Client-side errors captured where appropriate. * Fastify: Request lifecycle observable. * Prisma: DB failures surfaced with useful operational context. * Cloudflare: Edge logs structured and minimal-noise.

Severity: No observability on critical workflow = HIGH.

18. REACT STRICT RULES

MUST: * Presentation separated from business logic. * Hooks encapsulate client orchestration. * useEffect only for real side effects (not data derivation). * Form state controlled intentionally. * Remote data access standardized (React Query/SWR pattern). * Loading/Error/Empty/Success states explicit.

SHOULD: * Prefer composition over giant components. * Keep component API small and purposeful. * Isolate domain decisions outside UI layer.

FORBIDDEN: * API calls directly inside render path. * Business rules hidden in component tree. * Uncontrolled side effects. * Duplicate form/business validation logic with divergent behavior. * Giant page components that do everything.

Anti-patterns: Smart Page Monster, useEffect-as-Application-Layer, UI-Driven Business Logic, Prop Drilling Hell.

Review Questions: * Можно ли протестировать бизнес-правило без React? * Понятно ли, где заканчивается UI и начинается application logic? * Есть ли явные состояния UI?

19. FASTIFY STRICT RULES

MUST: * Schema validation for requests where risk is non-trivial. * Route handler thin (delegates to UseCase). * Auth/access checks not implicit. * Error mapping centralized. * Plugins used intentionally and scoped.

SHOULD: * Request types derived from schema/contracts. * Idempotency considered for repeat-sensitive operations. * Transport layer isolated from domain.

FORBIDDEN: * Business orchestration in route. * Hand-rolled validation everywhere instead of standardized schema. * Hidden auth in random helper. * Direct coupling route → Prisma for critical domain logic.

Anti-patterns: Fat Handler, Transport-Centric Architecture, Route as God Object, Hidden Middleware Side Effects.

Review Questions: * Можно ли сменить Fastify на другой transport без переписывания domain/use case? * Где именно проверяется доступ? * Где именно находится validation truth?

20. PRISMA STRICT RULES

MUST: * Prisma only as persistence mechanism. * Transaction boundaries explicit for multi-step critical operations. * Migrations disciplined and reviewable. * Repository/adapters isolate persistence semantics. * Data constraints and invariants understood deliberately.

SHOULD: * Avoid over-fetching. * Shape queries intentionally. * Protect consistency in concurrent scenarios.

FORBIDDEN: * Domain policy inside Prisma helper. * Silent reliance on DB behavior not expressed in code/design. * Unsafe raw queries without strong reason and safety measures. * Massive implicit nested writes without understanding rollback/consistency.

Anti-patterns: ORM as Domain, Magic Mutation Blob, Hidden Transaction Risk, Schema Drift without App Awareness.

Review Questions: * Где находится бизнес-правило — в domain или в ORM? * Что произойдёт при частичном падении multi-step mutation? * Нужна ли transaction boundary?

21. CLOUDFLARE STRICT RULES

MUST: * Edge/runtime constraints considered from start. * Worker logic remains stateless where required. * Bindings/env/secrets handled through platform mechanisms. * Caching strategy deliberate (Cache-Control, CDN). * Response behavior explicit. * Runtime-specific concerns isolated from core domain.

SHOULD: * Optimize for cold-start/runtime characteristics. * Minimize unnecessary compute in request path. * Design with platform limits in mind.

FORBIDDEN: * Hardcoded runtime secrets. * Assuming persistent in-memory state for correctness. * Heavy core business computation in hot edge path without justification. * Coupling domain core directly to Cloudflare-specific APIs.

Anti-patterns: Edge as Database of Truth, Runtime Lock-In Core, Cache Chaos, Stateful Worker Illusion.

Review Questions: * Что произойдёт при повторном cold start? * Завязан ли correctness на memory state? * Можно ли вынести platform-specific logic из domain?

22. CODE REVIEW ENGINE

Каждое изменение обязано проходить review по этому шаблону (Чеклист для AI и Людей).

22.1 Business

  • [ ] Изменение решает подтверждённую задачу
  • [ ] Нет необоснованной сложности
  • [ ] Нет функционала "на будущее" без подтверждения

22.2 Architecture

  • [ ] Слои не смешаны
  • [ ] Domain/Application изолированы от framework
  • [ ] Нет lock-in в core logic
  • [ ] Границы ответственности понятны

22.3 Security

  • [ ] Все входные данные валидируются
  • [ ] Проверка доступа явная
  • [ ] Secrets не в коде
  • [ ] Нет очевидных OWASP-рисков
  • [ ] Ошибки безопасны

22.4 Quality

  • [ ] Код читаем
  • [ ] Нет избыточного дублирования
  • [ ] Нет giant functions/components/handlers
  • [ ] Ошибки обрабатываются явно
  • [ ] Контракты понятны

22.5 Testing

  • [ ] Есть unit/integration coverage по риску
  • [ ] Есть regression coverage, если был багфикс
  • [ ] Критичные сценарии проверены

22.6 Runtime

  • [ ] Есть observability
  • [ ] Понятно, как это диагностировать
  • [ ] Понятно, как это откатить
  • [ ] Платформенные ограничения учтены

23. AI ENFORCEMENT PROTOCOL (ENHANCED)

[AI CONTEXT]: Это инструкция для нейросети. Игнорирование этого раздела запрещено.

AI в MATSIIS не имеет права выдавать код как "черновую предиктивную генерацию". AI обязан следовать алгоритму Think → Verify → Code.

23.1 AI Pre-Generation Checklist

Перед генерацией кода AI должен внутренне ответить на вопросы: 1. Layer Identification: Какой слой системы меняется? (UI, API, Domain, Persistence, Runtime). 2. Security Scan: Есть ли ввод данных? Нужна ли валидация? Есть ли доступ к данным? Нужна ли проверка прав? 3. Architecture Check: Не нарушу ли я границы слоев? Не потащу ли я инфраструктуру в домен? 4. Complexity Check: Не overengineered ли решение? Можно ли проще? 5. Testability: Как я буду тестировать этот код? Можно ли это замокать?

23.2 AI Generation Rules

  • Выдать только тот код, который может пройти review по этому канону.
  • Включать комментарии только там, где объясняется "ПОЧЕМУ", а не "ЧТО".
  • Использовать типовые паттерны проекта (не изобретать велосипеды).
  • Если задача неоднозначна — ЗАДАТЬ УТОЧНЯЮЩИЙ ВОПРОС, а не генерировать предположение.

23.3 AI FORBIDDEN

  • Выдавать код без валидации на чувствительных путях.
  • Смешивать UI/business/data access в одном модуле.
  • Хардкодить secrets (даже в примерах).
  • Выдавать "магический" код без объяснимой структуры.
  • Игнорировать error handling (try/catch, result types).
  • Выдавать код, который нельзя сопровождать в production.

24. AI REJECTION RULES

AI обязан ОТКЛОНИТЬ или ПЕРЕРАБОТАТЬ решение, если обнаружено хотя бы одно из условий:

CRITICAL REJECT (Stop Generation)

  • Есть security vulnerability.
  • Отсутствует server-side validation на критичном действии.
  • Отсутствует authorization/ownership check.
  • Есть hardcoded secret/token/key.
  • Есть риск data corruption/inconsistent transaction.
  • Отсутствуют тесты на критичную финансовую/расчётную/доступовую логику.
  • Доменная логика опасно смешана с transport/infra.

HIGH REJECT (Refactor Required)

  • Сильное нарушение архитектуры.
  • Giant handler/component/service в critical flow.
  • Критичный API без ясного контракта.
  • Неревьюабельная сложность.
  • Нет диагностируемости у важного процесса.

MEDIUM FIX BEFORE MERGE

  • Дублирование.
  • Naming/structure problems.
  • Умеренный overengineering.
  • Слабая декомпозиция.

25. CHANGE ACCEPTANCE RULE

Изменение считается допустимым только если одновременно выполняются все условия: 1. Проходит Severity Model без CRITICAL и HIGH блокеров. 2. Проходит Gates 1–6. 3. Соответствует Architecture Boundaries. 4. Соответствует Security Rules. 5. Соответствует Runtime Constraints. 6. Имеет достаточные Tests/Observability по уровню риска. 7. Может быть объяснено Senior Engineer без "магии".

Формула допуска: 

APPROVE = Business Fit
       AND Architecture Fit
       AND Security Fit
       AND Quality Fit
       AND Runtime Fit
       AND Release Fit
Если хотя бы один обязательный фактор не выполнен: REJECT.

26. RELEASE CONTROL STANDARD

MUST: * Change scope understood. * Migrations reviewed and reversible if possible. * Rollback or containment strategy known. * Configs/env changes explicit. * Monitoring expectations known for important changes.

FORBIDDEN: * Blind release of critical change. * Release without understanding impact on data/access/runtime. * Hidden config dependencies.

Severity: Production-impacting release without rollback awareness = HIGH/CRITICAL.

27. TECH DEBT RULE

Tech debt допускается только как осознанное исключение, зафиксированное в системе.

MUST: * Debt documented (Comment + Ticket). * Reason explicit (Why now? Why not later?). * Risk explicit (What could break?). * Removal plan exists for material debt (Deadline).

FORBIDDEN: * Скрытый debt как "временное решение", о котором никто не знает. * Накопление CRITICAL/HIGH debt без управленческого решения.

28. PERFORMANCE & BUDGET STANDARD (NEW)

Зачем: Предотвращение деградации производительности со временем.

MUST: * Load Time: Frontend bundle size must not exceed defined budgets (e.g., 200kb initial). * API Latency: Critical endpoints must respond within SLA (e.g., <200ms p95). * DB Queries: N+1 queries are FORBIDDEN. Use eager loading or batching. * Memory: No memory leaks in long-running processes (Workers/Services). * Rendering: No unnecessary re-renders in React (use memo/useCallback where justified).

FORBIDDEN: * Unbounded loops over user data. * Fetching large datasets without pagination/cursors. * Blocking the event loop with synchronous heavy computation.

Stack Specifics: * React: Use React.memo, useMemo, useCallback where justified. Code splitting for routes. * Fastify: Enable compression. Use proper caching headers. * Prisma: Use select to limit fields. Add indexes for frequent queries. * Cloudflare: Leverage CDN caching. Minimize worker compute time.

Severity: Performance regression on critical path = HIGH.

29. DOCUMENTATION & ADR STANDARD (NEW)

Зачем: Код без контекста — это технический долг.

MUST: * README: Each service/module must have a README explaining purpose, setup, and commands. * API Docs: OpenAPI/Swagger must be up-to-date with code. * ADR (Architecture Decision Record): Significant architectural changes require an ADR explaining context, decision, and consequences. * Code Comments: Explain "Why", not "What". Complex algorithms must have comments.

FORBIDDEN: * Merging significant features without updating API docs. * "Magic" numbers without named constants or comments.

Stack Specifics: * React: Component props documented (TypeScript interfaces serve as docs). * Fastify: Route schemas serve as API documentation. * Prisma: Schema comments for complex relationships. * Cloudflare: Worker configuration documented.

Severity: Missing docs for public API = MEDIUM. Missing ADR for core arch change = HIGH.

30. TOOLING & AUTOMATION MAP (NEW)

[AI CONTEXT]: AI должен понимать, что код будет проверяться этими инструментами. Пишите код, совместимый с ними.

Rule Category Tool / Mechanism Enforcement Level
Syntax & Style ESLint, Prettier, EditorConfig Auto-Fix / Block Merge
Security Semgrep, Snyk, GitLeaks Block Merge
Type Safety TypeScript (Strict Mode) Block Compile
Testing Vitest, Jest, Playwright Block Merge (if coverage < threshold)
API Contract OpenAPI Validator, Zod Block Merge
DB Migration Prisma Migrate, SQL Review Block Deploy
Secrets GitHooks (pre-commit), Vault Block Commit
Performance Lighthouse, K6, Bundle Analyzer Report / Warn
Observability Sentry, Datadog, ELK Runtime Alert

31. FINAL OPERATING RULE

Любой код, изменение, модуль или архитектурное решение в MATSIIS должно выдерживать вопрос:

«Принял бы это сильный senior/staff engineer в production-кодовую базу без стыда, без скрытых рисков и без магии?»

Если ответ: * ДА → Change may proceed. * НЕТ → Change must be redesigned, rewritten or rejected.

32. CANONICAL CONCLUSION

Этот стандарт не является описанием желаемого качества.
Он является механизмом инженерного допуска.

То есть: * AI не просто пишет код; он валидирует его по Канону. * Разработчик не просто "старается хорошо"; он следует системе. * Система не просто "надеется на review"; она автоматически отклоняет нарушения.

В MATSIIS:
Слабый код не должен проходить дальше точки проектирования и генерации.

Итоговая модель жизненного цикла: 

Design → Validate → Enforce → Generate → Test → Observe → Review → Release → Operate

Именно это считается полным контролем разработки.