AI-системный аналитик: проектирование через спецификацию

«Хочу блог на Astro». Сколько раз вы отдавали AI такую формулировку — и получали обратно код, который переписывает половину проекта каждые два дня?

Проблема не в модели. Проблема в том, что между «хочу блог» и кодом нет контракта. AI угадывает: стек, деплой, i18n, SEO, юристку. И угадывает плохо.

Я закрыл этот зазор двумя документами. Первый — спецификация на самого AI-аналитика: как он должен вести интервью, что покрывать, чего не делать. Второй — выходная спецификация проекта: что именно строим, с MUST/MUST NOT, уникальными ID и проверяемыми условиями. Оба документа рабочие, живут в репозитории и подтягиваются при каждом запуске агента.

В статье — ключевые фрагменты обоих с разбором «почему так». Это чистый how-to: берите шаблоны, адаптируйте под себя.

Почему промпт — плохой контракт

Промпт — это напутствие. «Сделай мне блог, нужен тёмный дизайн и SEO». Модель делает набор скрытых предположений: возьмёт starter template вместо вашей конфигурации, прикрутит Vercel вместо S3, забудет про llms.txt, посчитает cookie-баннер «nice to have». К середине работы проект превращается в клубок компромиссов, которые вы не выбирали. Переписывать дороже, чем начать заново.

Спецификация — это контракт. Если в ней написано «MUST деплой на Yandex S3 + CDN, MUST NOT использовать серверный рендеринг, NFR-COST-001: $0/мес за инфраструктуру» — у модели нет пространства для фантазии. Она делает ровно то, что написано, и вы можете это проверить.

К 2026 году этот подход оформился в методологию Spec-Driven Development (SDD): спецификация предшествует коду, код — расходный артефакт, спека — source of truth. GitHub Spec Kit, AWS Kiro, OpenSpec, BMAD — основные инструменты. У Spec Kit цикл такой: Constitution → Specify → Plan → Tasks → Implement; у остальных названия фаз отличаются, но структура та же.

Birgitta Böckeler на martinfowler.com описывает спектр зрелости SDD-применения: от spec-assisted (спека помогает, код — primary) через spec-anchored (спека — управляющий контракт для ревью и изменений) к spec-as-source (спека — единственный артефакт, код генерируется). Для production оптимален средний.

Но здесь есть неочевидный шаг, который пропускают большинство гайдов. Самого AI-аналитика тоже надо спроектировать. Это рекурсия SDD: вы пишете спеку на агента, который будет писать спеки на проект. Ниже — оба документа.

Документ 1: спецификация на AI-аналитика

У меня это system-analyst.md — 246 строк, лежит в ~/.config/opencode/agents/. Это одновременно system prompt агента и его SDD-спека. Разберём ключевые секции.

Identity — что агент делает и чего не делает

You are a senior System Analyst with 15+ years of experience in requirements
engineering, business analysis, and technical planning. You are proficient in
IREB, IEEE 830, ISO/IEC/IEEE 29148:2018, and Agile methodologies.

Your job is to help the user turn vague product ideas into rigorous,
implementation-ready technical plans. You do NOT write production code —
you think, research, interview, and document.

Почему так. Первое, что должно быть в спеке агента — жёсткая граница зоны ответственности. «Думает, исследует, интервьюирует, документирует» — и явный запрет писать продакшен-код. Без этого аналитик скатывается в «помогу немножко написать функцию» и теряет позицию. Эта же строка потом трассируется в секцию Constraints ниже.

Железные правила интервью

### Iron Laws

1. ONE question at a time — always use the `question` tool. Presenting multiple
   questions simultaneously overwhelms and produces ambiguous answers.
2. Adaptive pacing — adjust depth based on stakeholder engagement and clarity.
3. Confirm before proceeding — every 5 turns, summarize understanding and confirm.
4. Never skip to solutions — elicit requirements first, document, then propose options.

Почему так. Нарушение любого из четырёх превращает интервью в пустую беседу. Самое частое — «один вопрос за раз»: модель норовит выдать стену из пяти вопросов, пользователь отвечает на первый, остальное игнорирует. Второе по частоте — перепрыгивание к решениям: «как реализовать i18n?» вместо «какие языки нужны и какова URL-структура?». Первый вопрос навязывает реализацию, второй выясняет требование.

Закон №3 (подтверждение каждые 5 поворотов) — ловит недопонимания до того, как они уйдут в спеку. Закон №2 — escape hatch: если тема прозрачная, не нужно выкатывать все 25 вопросов.

Восемь категорий нефункциональных требований

Cover ALL eight NFR categories (in order — skip only if already answered):

1. Performance: "How responsive does this need to be?"
2. Security: "What security requirements apply? Sensitive data? Regulations?"
3. Reliability: "How critical is uptime? Acceptable downtime?"
4. Scalability: "How much growth do you expect? Usage spikes?"
5. Usability: "Who are the users? Technical skill level?"
6. Maintainability: "Who will maintain this? How often do you expect changes?"
7. Compliance: "Regulatory requirements? Industry standards?"
8. Integration: "What systems does this connect to? API requirements?"

Почему так. Джуны теряют половину требований именно на NFR. «Быстрый», «надёжный», «безопасный» — это не требования, это сигналы. Восемь категорий заставляют аналитика пройти каждую отдельным вопросом, а не объединять «как с безопасностью и производительностью». Это разные области с разными trade-off. Каждая категория потом становится отдельной секцией в выходной спеке.

Реактивные пути: что делать с размытыми словами

| Trigger                     | Follow-up                                                                                |
| --------------------------- | ---------------------------------------------------------------------------------------- |
| "Fast" / "Quick"            | "What response time are you expecting? A specific number?"                               |
| "Easy to use" / "Intuitive" | "Think of a tool you find easy to use. What makes it easy?"                              |
| "Secure"                    | "What specific security concerns? Data protection, access control, threat prevention?"   |
| "Scalable"                  | "How much growth? From X to Y users? Usage spikes?"                                      |
| "Like [competitor]"         | "What specifically about [competitor] do you want to replicate? What would you improve?" |

Почему так. Стейкхолдер почти всегда говорит абстракциями. Таблица реактивных путей — это скрипт для drill-down: услышал триггер → задал конкретный follow-up. Без неё аналитик примет «быстрый» за требование и запишет в спеку слово «fast». С ней — добьётся числа.

Constraints — что превращает документ в спеку

## Constraints (6 ключевых из 12)

- Do NOT write production application code. Your output is documentation and analysis.
- Do NOT skip the interview process and jump to conclusions — ask first.
- Do NOT assume technical decisions — propose options and let the user choose.
- Do NOT ask more than one question at a time.
- Each requirement must be uniquely identified, testable, and traceable to a
  business objective. Use FR/NFR/US/AC/EC IDs.
- Use RFC 2119 keywords in specs: MUST (absolute), SHOULD (recommended),
  MUST NOT (prohibition), MAY (optional).

Почему так. Это самая важная секция. Заметьте два слоя:

1. Поведенческие запреты — Do NOT ask more than one question at a time переводит «Iron Law» из пожелания в контракт. Если агент нарушит, вы увидите это сразу.
2. Структурные правила для выходного документа — уникальные ID, RFC 2119, трассировка к бизнес-цели. Это и есть граница между «напутствием» и «спекой». Без ID нельзя трассировать; без MUST/MUST NOT нельзя проверить; без трассировки требование висит в воздухе.

RFC 2119 — стандарт из IETF, который взяли на вооружение большинство SDD-тулзов. MUST = абсолютное требование, MUST NOT = явный запрет, SHOULD = рекомендация, MAY = опционально. Эта лексика делает спеку машиночитаемой: и человек, и AI понимают, где твёрдое правило, а где предпочтение.

Документ 2: выходная спецификация проекта

Когда аналитик отработал по своей спеке, на выходе появляется спецификация проекта. Покажу её на реальном примере — спеке этого блога nikonov-dev.online. Она родилась из интервью на 15 вопросов, содержит 80 FR, 26 NFR, 22 edge cases. Вот ключевые фрагменты.

NFR с числами, а не словами

## NFR: Производительность

| ID           | Требование                    | Цель                                 |
| ------------ | ----------------------------- | ------------------------------------ |
| NFR-PERF-001 | Lighthouse Performance score  | ≥ 99 (desktop), ≥ 90 (mobile)        |
| NFR-PERF-005 | TTFB через CDN                | < 100ms (РФ)                         |
| NFR-PERF-006 | FCP (First Contentful Paint)  | < 0.5s (десктоп)                     |
| NFR-PERF-007 | Время сборки (`astro build`)  | < 60s для 100 статей                 |
| NFR-PERF-008 | Размер JS на странице статьи  | < 50KB (без Sandpack), Sandpack lazy |
| NFR-PERF-009 | Время перехода между статьями | < 50ms (View Transitions)            |

## NFR: Стоимость

| ID           | Требование                                                                 |
| ------------ | -------------------------------------------------------------------------- |
| NFR-COST-001 | Инфраструктура: $0/мес (free tier: 1 GB storage, 100K GET, 100 GB traffic) |
| NFR-COST-002 | CI/CD: SourceCraft (уже оплачен)                                           |

Почему так. «Сайт должен быть быстрым» — не требование. NFR-PERF-001: Lighthouse ≥ 99 (desktop) — требование. Без числа AI-кодер выберет случайный порог и будет формально прав. С числом он выбирает конкретную реализацию: статику на S3+CDN, content-hash в именах бандлов, lazy-loading для тяжёлых компонентов.

Обратите внимание на NFR-COST-001: $0/мес. Это не «дёшево», это конкретный free tier с конкретными лимитами. Когда AI-кодер увидит это требование, он не предложит Vercel Pro — он сразу возьмёт S3.

Каждое NFR имеет уникальный ID. Когда через полгода вы захотите ослабить порог производительности, вы меняете NFR-PERF-008, и по ID находите все места в коде и тестах, которые на него ссылаются. Без ID это ручная археология.

Edge cases — что ломается в нештатных ситуациях

| ID     | Сценарий                                | Ожидаемое поведение                           |
| ------ | --------------------------------------- | --------------------------------------------- |
| EC-006 | Изменился slug статьи                   | 301 редирект (файл `_redirects` или S3 rules) |
| EC-011 | EN-версии статьи нет                    | 404 с предложением перейти на RU              |
| EC-014 | Cookie отклонены                        | Сайт работает без Метрики                     |
| EC-015 | Запрос РКН об обработке ПД              | Ответ в течение 30 дней (152-ФЗ)              |
| EC-017 | Отсутствует ключ в i18n-словаре         | TypeScript compile error                      |
| EC-022 | Lighthouse на статье с Sandpack (>50KB) | NFR-PERF-008 разрешает; порог ≥99 остаётся    |

Почему так. Edge cases — это где спека зарабатывает деньги. Львиная доля переделок возникает не на основном сценарии, а на нештатных ситуациях, о которых AI не знал. Спека принуждает аналитика (и вас) продумать их заранее.

EC-017 — мой любимый пример: отсутствие ключа в i18n-словаре должно быть compile error, а не runtime warning. Это решение принято в спеке, а не на код-ревью. EC-022 — разрешение конфликта: Sandpack тянет >50KB JS, но NFR-PERF-008 это разрешает; общий порог Lighthouse ≥99 остаётся. Конфликт зафиксирован, решение явно.

Ключевые дизайн-решения — явные, а не подразумеваемые

1. Статика, не сервер. Astro SSG → S3 + CDN. Ноль серверных затрат.
2. MDX в коде, не в CMS. Статьи — часть репозитория, version-controlled.
3. Content-hash в именах бандлов. CSS/JS кешируются на год (immutable), HTML — 5 минут.
4. i18n через TypeScript-словари. Интерфейс UIStrings → пропущенный ключ = compile error.
5. GEO: двойная оптимизация. llms.txt для AI-краулеров + Schema.org для поисковиков.

Выборка из 8 дизайн-решений спеки; нумерация сохранена.

Почему так. Это блок Constraints выходной спеки — те решения, которые AI не должен перевыбирать. «Статика, не сервер» — MUST NOT серверный рендеринг. «MDX в коде, не CMS» — MUST хранить статьи в репозитории. Каждое решение принято один раз в спеке, а не переоткрывается на каждой задаче.

Рекурсия: спека, которая делает спеки

Связка двух документов выглядит так:

spec на аналитика (system-analyst.md)
        │
        ▼
   интервью 15–25 вопросов
        │
        ▼
spec на проект (nikonov-dev-blog-spec.md)
        │
        ▼
   AI-кодер реализует по спеке

Аналитик ведёт интервью по своим Iron Laws, покрывает 8 категорий NFR, drill-down’ит размытые слова по реактивной таблице. На выходе — спецификация проекта с MUST/MUST NOT, ID и edge cases. Эту спецификацию скармливают AI-кодеру, который реализует её по задачам без ваших уточнений в процессе.

Метод одинаково работает на разных масштабах. На одном конце — этот блог (80 FR, 26 NFR, 22 edge cases). На другом — платформа из 10 микросервисов EdTech (200+ FR, 50+ NFR, 40+ edge cases) и оркестратор автономной разработки AutoDev V3 (36 FR, 20 NFR). Цикл «интервью → спека → кодер» один и тот же, меняется только число вопросов и сессий.

И вот ключевое: спека на аналитика — это не магия конкретной модели. Это обычный Markdown-файл. Её не обязательно зашивать в system prompt. Для агентов с доступом к файловой системе (OpenCode, Claude Code, Cursor) — положите рядом и сошлитесь в задании, AI откроет и прочитает, когда ему нужно. Для чат-ботов без доступа к файлам (ChatGPT, Claude.ai) — вставляйте несущие части прямо в промпт. Меняете тул — спека остаётся.

Что превращает документ в спеку

Чеклист. Если в вашем документе нет этих четырёх вещей — это не спека, это напутствие.

1. Уникальные ID. Каждое требование имеет ID (FR-PUB-001, NFR-PERF-008, EC-011). По ID трассируется код, тесты, коммиты. Меняется требование — вы находите затронутый код за секунды.
2. RFC 2119. MUST (абсолютное), SHOULD (рекомендация), MUST NOT (запрет), MAY (опционально). Лексика делает спеку машиночитаемой: и человек, и AI видят твёрдость правила.
3. Проверяемые условия. Принимаемый критерий должен быть тестом: «Lighthouse ≥ 99», «TTFB < 100ms», «$0/мес». Не «быстрый», не «дешёвый», не «удобный».
4. Out of scope. Что НЕ делаем. Без этого scope creep неизбежен — AI добавит «полезные» фичи, которых вы не просили.

Триггер-правило для себя: пиши спеку, когда тебя разозлит, если AI интерпретирует требование иначе. Пропускай спеку, когда можешь исправить одним follow-up промптом.

Что вы получаете на выходе

После interview + spec у вас документ, который:

1. Скармливается AI-кодеру без потерь. Кодер читает спеку, разбивает на задачи по 15 минут, реализует функциональность и тут же пишет под неё тесты — критерии приёмки из спеки превращаются в тест-кейсы. Без ваших уточнений в процессе.
2. Служит валидационным гейтом. Когда кодер говорит «готово», вы сверяете со спекой, а не с воспоминаниями о разговоре.
3. Выживает амнезию сессии. Если сессия упала, новая начинает со спеки, а не с нуля.
4. Трассируется. Меняется NFR-PERF-008 → по ID находится код и тесты → правите. Минуты вместо часов археологии.

Минимальный шаблон аналитика

Выше — фрагменты моего рабочего агента с OpenCode-спецификой. Ниже — вычищенный шаблон, который работает с любым AI-тулом. Скопируйте, заполните плейсхолдеры в блоке «Project context», запустите.

# System Analyst Agent

You are a senior system analyst. Your job: turn vague product ideas into
rigorous, implementation-ready specifications. You do NOT write production
code — you interview, research, and document.

## Interview protocol

### Iron Laws

1. ONE question at a time. Never dump multiple questions in one turn.
2. Adaptive pacing — if the topic is clear, move on; if vague, drill down.
3. Every 5 turns, summarize what you've captured and confirm with the user.
4. Never skip to solutions — elicit requirements first, then propose options.

### Coverage (walk in this order)

1. Stakeholders & usage scenario
2. Functional requirements — core features, user workflows
3. Edge cases — "what happens when X fails / is missing / takes an extreme value?"
4. Non-functional requirements — cover ALL eight categories:
   Performance, Security, Reliability, Scalability, Usability,
   Maintainability, Compliance, Integration
5. Data model hints — key entities, relationships
6. UX/style preferences

### Drill-down on vague words

| Trigger ("fast", "secure", "scalable"...) | Follow up with a specific question                |
| ----------------------------------------- | ------------------------------------------------- |
| Speed claim                               | "What response time, in numbers?"                 |
| Security claim                            | "Which specific concerns: data, access, threats?" |
| Growth claim                              | "From X to Y users? Spikes?"                      |
| "Like [competitor]"                       | "What exactly to replicate? What to improve?"     |

### Anti-patterns (avoid)

| Don't ask                                         | Ask instead                  |
| ------------------------------------------------- | ---------------------------- |
| "Don't you think X is important?" (leading)       | "How important is X to you?" |
| "How would you implement X?" (premature solution) | "What should X accomplish?"  |

## Output format (write after the interview)

A specification document with:

- **User Stories** (US-1, US-2...) — each with testable acceptance criteria
- **Functional Requirements** (FR-XXX-001) — uniquely identified
- **Non-Functional Requirements** (NFR-XXX-001) — with concrete numbers
- **Edge Cases** (EC-XXX-001) — non-standard scenarios + expected behavior
- **Constraints** — using RFC 2119 keywords: MUST / MUST NOT / SHOULD / MAY
- **Out of Scope** — what we are NOT building

XXX в ID — доменный префикс (PERF, SEC, COST, PUB, AUTH...). Главное — уникальность и постоянство внутри проекта.

## Project context (fill in before first run)

- Stack: <your-stack-here>
- Repository layout: <your-path-conventions>
- Task tracker: <tool> or "none, write spec to a markdown file"
- Regulations: <GDPR / 152-ФЗ / HIPAA / none>
- Out of scope: <what the analyst must NOT do>

Что заменить под себя: блок Project context внизу — это единственное, что зависит от вашего стека. Всё остальное (Iron Laws, покрытие, drill-down, выходной формат) — универсальное.

Куда положить и как вызвать

Спека — это Markdown-файл. Где он живёт и как на него сослаться, зависит от тула.

Для чат-ботов без файлового доступа (последние две строки) — вставляйте спеку в каждый новый диалог. Для агентов с файловым доступом (первые три) — один раз положили, работает во всех сессиях в этом проекте.

Заключение

AI не заменяет аналитика. Он масштабирует его — но только когда сам аналитик спроектирован. Два документа решают это: спека на агента (как он работает) и спека на проект (что он выдаёт). Оба — контракты с MUST/MUST NOT, ID и проверяемыми условиями.

Метод не требует специфической модели или платформы. Возьмите структуру из статьи выше, подставьте свой контекст, загрузите в любого AI-агента. На следующей фиче задайте первый вопрос «опишите типичный сценарий использования» — и не давайте агенту перепрыгивать к решениям. Через 15–25 вопросов у вас будет документ, на котором можно строить.

В статье — несущие фрагменты обоих документов. Остальное в system-analyst.md — сантехника: пути к wiki, команды SourceCraft, проектные конвенции. Восстановите по структуре, показанной здесь, плюс вашему стеку инструментов.

FAQ

Зачем спека на аналитика, если есть готовые SDD-тулзы типа GitHub Spec Kit?

Spec Kit даёт цикл Constitution → Specify → Plan → Tasks → Implement и шаблоны. Но он не определяет, как аналитик ведёт интервью, какие категории покрывает, как drill-down’ит размытые слова. Спека на агента — это слой поведения поверх SDD-цикла. Spec Kit совместим: constitution = мой блок Constraints, specify/plan/tasks = выходная спека.

Можно использовать обычный ChatGPT вместо агента со спекой?

Можно, но результат хуже. Обычный чат не держит дисциплину «один вопрос за раз», не покрывает 8 категорий NFR систематически, склонен перепрыгивать к решениям. Если используете ChatGPT — скопируйте туда Iron Laws и Constraints из спеки агента и напоминайте соблюдать.

Чем спека отличается от ТЗ?

ТЗ часто написано прозой, без ID, без MUST/MUST NOT, без edge cases, без out-of-scope. Спека — структурированный, машиночитаемый контракт, заточенный под AI-агента. Формально пересекается с IEEE 830 / ISO 29148, но прагматичнее: меньше бюрократии, больше проверяемости.

Подойдёт ли метод для маленькой задачи?

Для тривиальных правок спека избыточна. Правило: пишите спеку, когда вас разозлит, если AI интерпретирует требование иначе. Пропускайте, когда можете исправить одним follow-up промптом. Однофункциональная задача — чаще всего без спеки.

Сколько времени занимает цикл?

15–25 вопросов интервью = 30–60 минут диалога. Плюс 15–30 минут на сборку выходной спеки аналитиком. Итого полтора часа на спецификацию, которая сэкономит дни переделок. Для крупных проектов (платформа из 10 сервисов) — 60+ вопросов и несколько сессий, но и масштаб иной.

Где посмотреть примеры реальных спек?

Спека блога (80 FR, 26 NFR, 22 edge cases) и спека AutoDev V3 (36 FR, 20 NFR) родились из этого метода. Оба документа — рабочие, по ним реализован production-код. Метод работает не в теории, а в продакшене.