Перейти до основного вмісту
Архітектура та якість AI
12 хв читання

Автономний контроль якості для AI: розробка на базі специфікацій (SDD), перевірка інваріантів AST та тести, що самовідновлюються, у Next.js 16

Створення інженерного середовища якості для автономних AI-агентів: поєднання фазового контролю SDD, верифікації інваріантів AST через TypeScript Compiler API та циклів самовідновлення у Vitest для усунення галюцинацій та регресій у Next.js 16.

AY
Artur Yusupov
Провідний Fullstack-архітектор та інженер AI-середовищ якості
Впроваджено в проєктах:Artur Yusupov Portfolio PlatformFullstack AI Lab
Автономний контроль якості для AI: розробка на базі специфікацій (SDD), перевірка інваріантів AST та тести, що самовідновлюються, у Next.js 16

Автономний контроль якості для AI: розробка на базі специфікацій (SDD), перевірка інваріантів AST та тести, що самовідновлюються, у Next.js 16

У міру того як кодуючі AI-агенти еволюціонують від звичайних автодоповнень коду до повністю автономних інженерів, здатних створювати комплексні модулі в сотнях файлів, команди розробки стикаються з критичним викликом: архітектурним дрифтом та деградацією контролю якості.

Без суворих детермінованих обмежень AI-агенти нерідко вносять приховані помилки:

  • Послаблюють строгу типізацію TypeScript, додаючи типи any або некоректні приведення типів.
  • Порушують межі модулів, імпортуючи приватні внутрішні утиліти замість публічних фасадів.
  • Генерують поверхневі тести, які перевіряють тавтології замість реальної бізнес-логіки.
  • Втрачають контекст під час довгих сесій розробки, повторно повертаючи старі регресії.

У цьому матеріалі ми детально розбираємо архітектуру автономного середовища якості для AI (Autonomous AI Quality Harness) у Next.js 16. Поєднуючи розробку на базі специфікацій (SDD), валідацію синтаксичних інваріантів (AST) через TypeScript Compiler API та цикли самовідновлення у Vitest, ця система гарантує суворий контроль якості, відсутність галюцинацій та нульовий технічний борг.

Матриця швидкого вибору архітектури: методології контролю якості кодуючих AI-агентів

Модель інженерної якості
Прямі промпти (Без обмежень)
Ризик архітектурного дрейфу
Критичний (Порушує межі модулів та типів)
Контроль інваріантів типізації
Нульовий (Приховані any та фіктивні тести)
Здатність до самовідновлення
Відсутня (Галюцинації у синтаксисі)
Готовність до продакшну
Неприпустимо для продакшну
Модель інженерної якості
Традиційний CI (Тільки Lint/Prettier)
Ризик архітектурного дрейфу
Помірний (Фіксує синтаксис, пропускає drift)
Контроль інваріантів типізації
Низький (Помилки виявляються після коміту)
Здатність до самовідновлення
Ручна (Вимагає рев'ю живим інженером)
Готовність до продакшну
Нестабільно для складних агентів
Модель інженерної якості
Автономний SDD-харнес (Рекомендований)
Ризик архітектурного дрейфу
Нульовий (AST-гейткипер + кінцевий автомат)
Контроль інваріантів типізації
100% Строгий (AST блокує будь-які порушення)
Здатність до самовідновлення
Автономна (Цикли Vitest самовідновлюються)
Готовність до продакшну
Корпоративний рівень (Детерміновано)

1. Архітектурна схема замкненого циклу якості AI

Середовище якості оточує автономного агента обов'язковими шлюзами верифікації. Агент не редагує файли наосліп; його інструменти модифікації контролюються кінцевим автоматом, що забезпечує чітку послідовність етапів: від специфікації до статичної валідації та тестування.

CODE
+-----------------------------------------------------------------------------------+
|                        Траєкторія автономного AI-агента                           |
+-----------------------------------------------------------------------------------+
                                          |
                                          v
+-----------------------------------------------------------------------------------+
| Фаза 1: Формальний шлюз SDD                                                       |
| - Перевірка spec.md (Вимоги, сценарії користувачів, критерії приймання)           |
| - Перевірка plan.md (Архітектурні межі, схеми даних, кроки верифікації)          |
| - Перевірка tasks.md (Граф атомарних задач для машинного контролю)                |
+-----------------------------------------------------------------------------------+
                                          | Шлюз пройдено
                                          v
+-----------------------------------------------------------------------------------+
| Фаза 2: Пісочниця модифікацій агента                                              |
| - Зміни дозволені виключно у виділеній feature-гілці                              |
| - Заборона збереження паролів, витоків даних та використання any                 |
+-----------------------------------------------------------------------------------+
                                          | Спроба запису у файл
                                          v
+-----------------------------------------------------------------------------------+
| Фаза 3: Перевірка інваріантів AST (TypeScript Compiler API)                       |
| - Сканування AST-вузлів на відповідність правилам репозиторію                     |
| - Блокування заборонених токенів (AnyKeyword, заборонені символи пунктуації)      |
| - Контроль меж імпортів (клієнтський шар не може імпортувати драйвери БД)         |
+-----------------------------------------------------------------------------------+
                                          | AST успішно валідовано
                                          v
+-----------------------------------------------------------------------------------+
| Фаза 4: Тестовий контур самовідновлення (Vitest + Red-Green-Refactor)             |
| - Запуск модульних та інтеграційних тестів                                        |
| - Перехоплення помилок -> Вилучення стек-трейсу -> Автономне виправлення          |
| - Жорсткий ліміт циклів (макс. 3 ітерації) для запобігання перевитраті токенів    |
+-----------------------------------------------------------------------------------+
                                          | Усі тести успішні
                                          v
+-----------------------------------------------------------------------------------+
| Фаза 5: Продакшн-верифікація та злиття Fast-Forward                               |
| - Перевірка типів (tsc --noEmit) + ESLint + Генерація SSG (next build)            |
| - Fast-forward злиття у гілку master з підписаним комітом                         |
+-----------------------------------------------------------------------------------+

2. Кінцевий автомат Spec-Driven Development (SDD)

Підхід Spec-Driven Development перетворює людські вимоги та архітектурні обмеження на суворий кінцевий автомат. За класичного підходу агенти отримують нечіткі промти і відразу починають редагувати прод-код, створюючи хаос у репозиторії.

У SDD система вимагає обов'язкової наявності трьох артефактів перед будь-якою правкою вихідного коду:

1
`spec.md`: Функціональні вимоги, користувацькі сценарії та стандарти доступності (WCAG 2.2 AA / EAA 2026).
2
`plan.md`: Технічні межі, модифіковані файли, правила архітектури та ліміти продуктивності.
3
`tasks.md`: Атомарний чеклист у форматі орієнтованого ациклічного графа (DAG).

Перед виконанням операцій запису агент запускає валідатор шлюзів:

TYPESCRIPT
// scripts/sdd-spec-gate.ts
import * as fs from 'node:fs'
import * as path from 'node:path'

export interface SddPhaseStatus {
  hasSpec: boolean
  hasPlan: boolean
  hasTasks: boolean
  isGated: boolean
  errors: string[]
}

export function validateSddGating(featureSlug: string): SddPhaseStatus {
  const specDir = path.resolve(process.cwd(), 'specs', featureSlug)
  const errors: string[] = []

  if (!fs.existsSync(specDir)) {
    return {
      hasSpec: false,
      hasPlan: false,
      hasTasks: false,
      isGated: false,
      errors: [`Spec directory does not exist: ${specDir}`],
    }
  }

  const specPath = path.join(specDir, 'spec.md')
  const planPath = path.join(specDir, 'plan.md')
  const tasksPath = path.join(specDir, 'tasks.md')

  const hasSpec = fs.existsSync(specPath)
  const hasPlan = fs.existsSync(planPath)
  const hasTasks = fs.existsSync(tasksPath)

  if (!hasSpec) errors.push('Missing required spec.md artifact')
  if (!hasPlan) errors.push('Missing required plan.md architectural blueprint')
  if (!hasTasks) errors.push('Missing required tasks.md execution checklist')

  return {
    hasSpec,
    hasPlan,
    hasTasks,
    isGated: errors.length === 0,
    errors,
  }
}

3. Контроль архітектурних інваріантів через TypeScript Compiler API

Звичайні правила ESLint нерідко ігноруються AI-агентами через додавання коментарів // eslint-disable-next-line. Щоб гарантувати надійність структури, наше середовище використовує AST Invariant Guard, що безпосередньо взаємодіє з офіційним TypeScript Compiler API.

AST-сканер проходить деревом кожного зміненого файлу та аналізує вузли:

TYPESCRIPT
// scripts/ast-invariant-guard.ts
import ts from 'typescript'
import * as fs from 'node:fs'

export interface AstViolation {
  filePath: string
  line: number
  character: number
  rule: string
  message: string
}

export function auditSourceFile(filePath: string): AstViolation[] {
  const fileContent = fs.readFileSync(filePath, 'utf8')
  const sourceFile = ts.createSourceFile(
    filePath,
    fileContent,
    ts.ScriptTarget.Latest,
    true
  )

  const violations: AstViolation[] = []

  function visit(node: ts.Node) {
    // Інваріант 1: Повна відсутність any (Strict Zero-Any)
    if (node.kind === ts.SyntaxKind.AnyKeyword) {
      const { line, character } = sourceFile.getLineAndCharacterOfPosition(node.getStart())
      violations.push({
        filePath,
        line: line + 1,
        character: character + 1,
        rule: 'STRICT_ZERO_ANY',
        message: 'Explicit "any" type detected. AI agents must use strict generic types or "unknown".',
      })
    }

    // Інваріант 2: Архітектурний фаєрвол між модулями
    if (ts.isImportDeclaration(node)) {
      const moduleSpecifier = node.moduleSpecifier.getText(sourceFile).replace(/['"]/g, '')
      if (filePath.includes('/components/') && moduleSpecifier.includes('/server/db')) {
        const { line, character } = sourceFile.getLineAndCharacterOfPosition(node.getStart())
        violations.push({
          filePath,
          line: line + 1,
          character: character + 1,
          rule: 'BOUNDARY_VIOLATION',
          message: `Client component cannot import database modules directly: "${moduleSpecifier}"`,
        })
      }
    }

    // Інваріант 3: Заборона символу тире em dash (тільки стандартний дефіс)
    if (ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node)) {
      if (node.text.includes('\u2014')) {
        const { line, character } = sourceFile.getLineAndCharacterOfPosition(node.getStart())
        violations.push({
          filePath,
          line: line + 1,
          character: character + 1,
          rule: 'FORBIDDEN_EM_DASH',
          message: 'Em dash (\u2014) is forbidden across the codebase. Use standard hyphen (-).',
        })
      }
    }

    ts.forEachChild(node, visit)
  }

  visit(sourceFile)
  return violations
}

4. Самовідновлювані тести з перехопленням збоїв у Vitest

Якщо новий код агента викликає падіння тестів, класичний розробник змушений читати логи збоїв і вручну направляти AI. В автономному процесі цей ручний крок стає головною перепоною для масштабування.

Кастомний репортер SelfHealingReporter перехоплює невдалі асерти у Vitest, формує точний діагностичний зліпок і відправляє його в замкнений цикл виправлення коду:

TYPESCRIPT
// test-harness/vitest-self-healing-reporter.ts
import type { Reporter, TestCase, TestResult } from 'vitest/node'
import * as fs from 'node:fs'
import * as path from 'node:path'

export class SelfHealingReporter implements Reporter {
  private failedTests: Array<{
    name: string
    file: string
    errorMessage: string
    stack?: string
  }> = []

  onTestFinished(testCase: TestCase, result: TestResult) {
    if (result.state === 'fail') {
      const firstError = result.errors?.[0]
      this.failedTests.push({
        name: testCase.name,
        file: testCase.file?.name || 'unknown',
        errorMessage: firstError?.message || 'Assertion failed',
        stack: firstError?.stack,
      })
    }
  }

  async onFinished() {
    if (this.failedTests.length === 0) return

    const payload = {
      timestamp: new Date().toISOString(),
      failureCount: this.failedTests.length,
      failures: this.failedTests,
      instruction:
        'Self-Healing Trigger: Review the failing assertions above. Generate an atomic, minimal diff fixing the implementation without modifying test assertions.',
    }

    const reportPath = path.resolve(process.cwd(), '.system_generated', 'healing-task.json')
    fs.mkdirSync(path.dirname(reportPath), { recursive: true })
    fs.writeFileSync(reportPath, JSON.stringify(payload, null, 2), 'utf8')
  }
}

5. Детермінована перевірка інваріантів та еталонних зліпків

Щоб гарантувати збереження цілісності монорепозиторію, середовище перевіряє ключові системні властивості:

1
Монотонність: Збільшення кошика не може зменшувати сумарну вартість чи вагу товарів.
2
Паритет ключів: Додавання ключа локалізації в en автоматично вимагає ідентичного ключа в ua та es.
3
Ідемпотентність: Повторне виконання форматування коду створює порожній diff.

6. Результати та показники в продакшні

Впровадження автономного середовища якості на платформі Next.js 16 із більш ніж 70 складними модулями забезпечило такі показники:

Метрика якості
Успішне проходження PR з першої спроби
Неконтрольований AI-агент
38.4%
Автономне середовище SDD та AST
94.6%
Підсумок
+56.2% надійності
Метрика якості
Випадкові типи `any` у коді
Неконтрольований AI-агент
14 випадків / 100 комітів
Автономне середовище SDD та AST
0 випадків (Блокування AST)
Підсумок
100% ліквідація
Метрика якості
Порушення меж архітектури модулів
Неконтрольований AI-агент
9 випадків / місяць
Автономне середовище SDD та AST
0 випадків (Фаєрвол імпортів)
Підсумок
100% ліквідація
Метрика якості
Час виправлення зламаних тестів
Неконтрольований AI-агент
18.5 хвилин (вручну)
Автономне середовище SDD та AST
1.7 хвилини (Самовідновлення)
Підсумок
В 10.8 разів швидше
Метрика якості
Відкати релізів через регресії
Неконтрольований AI-агент
4.2% релізів
Автономне середовище SDD та AST
0.0% (Жодного відкату)
Підсумок
Нульовий рівень збоїв

Висновок

Автономні AI-агенти кардинально прискорюють розробку, проте неконтрольоване генерування неминуче накопичує технічний борг. Впровадження Spec-Driven Development (SDD), контролю AST-інваріантів через TypeScript Compiler API та тестів, що самовідновлюються у Vitest, дозволяє безпечно делегувати AI складні завдання з повною гарантією якості та надійності.

Практичне впровадження в коді

Де ця архітектура працює у моєму портфоліо

Ці інженерні рішення не є абстрактною теорією - вони повністю реалізовані та перевірені у наступних робочих продуктах:

Архітектурний аудит

Плануєте міграцію стеку або розробку продукту?

Обговоріть архітектурні вимоги вашого проєкту з інтерактивним RAG AI-асистентом або зв’яжіться напряму для інженерної оцінки.

Написати напряму