Оглавление главы

Приложение C: Процесс разработки и артефакты проекта

Этот документ — практическая “карта местности”: какие документы (артефакты) нужны в нормальном инженерном процессе, зачем они нужны и какие риски закрывают.

Это не про “бумажки ради бумажек”. В книге артефакты — это доказательства: наблюдаемые сигналы, что вы управляете качеством, безопасностью и поставкой изменений.

1) Карта процесса (end-to-end)#

Идея и ставки
    |
    v
Спецификация
    |
    v
План
    |
    v
Архитектура
    |
    v
Реализация (через SOP)
    |
    v
Проверка и верификация
    |
    v
Деплой и откат
    |
    v
Операции и инциденты
    |
    v
Улучшения
    |
    └───────────────> обратно в Спецификацию

См. также: эталонный полный цикл — Глава 10.

2) Артефакты по этапам (что, зачем, кто владелец, критерий “готово”)#

Ниже — минимальный набор. Он может быть “толще”, но не должен быть “пустым”.

Где живут артефакты (Git-first, чтобы работало устойчиво)#

Артефакты процесса должны быть долгоживущими: переживать смену таск‑трекера, быть версионируемыми и ревьюируемыми.

  • Git (GitLab/GitHub) — место правды для артефактов: SOP, промпты, DoD/чеклисты, runbooks, ADR (версионирование, ревью, история, связка с изменениями кода).
  • Таск‑трекер (Kaiten/Jira) — управление работой: карточки/статусы/обсуждения + ссылки на конкретные версии артефактов в Git (commit/tag) + доказательства (PR/CI/результаты проверки).

Дополнение: если вы используете Agent Skills (папки с SKILL.md) как формат переносимых процедур, логика та же — SKILL.md должен жить в Git и проходить ревью, потому что это часть производственного процесса (инструкции, шаблоны, проверки), а не “заметки в чате”.

2.1 Идея / постановка задачи#

  • Краткое резюме (коротко, без воды)

    • Зачем: зафиксировать зачем это делаем, кому больно, что меняется.
    • Владелец: руководитель/инициатор, менеджер продукта/проекта, техлид.
    • Готово, если: есть несколько тезисов “зачем/что/как измерим” и явные ограничения.
    • См. также: Глава 10 (валидация), Приложение A (бизнес‑обоснование).

  • Термины и “контракт исполнения” (коротко, чтобы не путаться)

    • AC (Acceptance Criteria): что должно получиться (ожидаемое поведение/результат).
    • DoD (Definition of Done): какие доказательства считаем достаточными, чтобы назвать результат готовым (несколько проверяемых пунктов).
    • План проверки: как именно получить эти доказательства (тесты/метрики/выборка/крайние случаи).
    • STOP: когда исполнитель обязан остановиться и эскалировать (неясный контекст, высокий риск, нет способа проверить).
    • TRACE: где видно, на чём “стоял” ответ: какие правила/SKILL.md/артефакты реально были использованы. Практика: TRACE кладём рядом с основным артефактом (ответ/пакет решения) и прикладываем в тикет/PR как доказательства.
    • Почему важно: человек иногда “дотягивает” AC контекстом и диалогом; автоматизация — нет, поэтому DoD + план проверки + STOP — обязательный минимум. Ниже AC и DoD перечислены ещё раз как артефакты процесса (с владельцем и критерием “готово”).

  • AC / критерии приёмки

    • Зачем: чтобы “готово” было проверяемым, а не “сделай хорошо”.
    • Владелец: автор изменения + ревьюер (принятие).
    • Готово, если: критерии измеримы/проверяемы, есть негативные сценарии и крайние случаи.
    • См. также: Глава 3, Глава 10.

  • DoD / критерии “готово” для задачи/итерации

    • Зачем: стандартизировать качество поставки (код, тесты, проверка, откат, наблюдаемость).
    • Владелец: команда (процесс), техлид/EM (применение).
    • Готово, если: DoD короткий, обязателен и реально проверяется.
    • См. также: Глава 5 (контрольные точки), Глава 9 (принудительное применение).

2.2 Спецификация#

  • Спецификация (ФТ/НФТ/AC)

    • Зачем: определить границы, компромиссы и критерии успеха до реализации.
    • Владелец: автор изменения (обычно Senior/Staff) + стейкхолдеры.
    • Готово, если: есть ФТ/НФТ, критерии приёмки, ограничения и явные предположения.
    • См. также: Глава 3, Глава 10.

  • Чеклист рисков (внутри спецификации / SOP / PR)

    • Зачем: зафиксировать “что может пойти не так” и митигации без отдельной бюрократии.
    • Владелец: автор изменения + ревьюеры.
    • Готово, если: перечислены top‑риски и для каждого есть митигация + способ проверки/наблюдения.
    • См. также: Глава 3, Глава 5, Глава 7.

2.3 Планирование#

  • План работ (декомпозиция)
    • Зачем: сделать путь к результату управляемым (а не “увидим по ходу”).
    • Владелец: автор изменения + команда.
    • Готово, если: есть этапы, зависимости, критический путь и контрольные точки.
    • См. также: Глава 3.

Практическая ремарка: план — это не “черновик в чате”, а отдельный ревьюируемый артефакт. Его удобно править и переигрывать цикл исполнения: если агент делает “не то”, часто быстрее вернуться к плану, уточнить входы/ограничения/DoD и повторить, чем латать результат перепиской. См. Cursor: Best practices for coding with agents (разделы про планы и «starting over from a plan»).

2.3.1 Усиление по триггерам риска/зрелости (опционально)#

  • Реестр рисков (как отдельный артефакт)
    • Зачем: портфельный контроль рисков, когда риски повторяются и нужен единый обзор.
    • Когда вводить: если класс рисков повторяется регулярно, задействует несколько команд или цена ошибки высока.
    • Владелец: автор изменения + ревьюеры; на уровне портфеля — техлид/EM/владелец практики.
    • Готово, если: у каждого риска есть митигация, триггеры и способ проверки/мониторинга.
    • См. также: Глава 3, Глава 7.

2.4 Архитектура#

  • Архитектурный документ (v1)

    • Зачем: явно задать компоненты, границы ответственности и контракты.
    • Владелец: Staff/Principal (или назначенный архитектор).
    • Готово, если: ясны компоненты/границы, есть компромиссы и “когда пересмотреть”.
    • См. также: Глава 4.

  • ADR / записи архитектурных решений

    • Зачем: сохранить “почему мы так решили”, чтобы не делать реверс‑инжиниринг через год.
    • Владелец: автор решения (обычно Staff/Principal) + ревью.
    • Готово, если: контекст → решение → последствия → триггеры пересмотра.
    • См. также: Глава 4.

2.5 Реализация и проверка (через SOP и контрольные точки)#

  • SOP на изменение

    • Зачем: сделать выполнение воспроизводимым: шаги, условия остановки, проверки, выход.
    • Владелец: автор изменения; применяет — инженер (или автоматизация).
    • Готово, если: есть контрольные точки, план проверки и условия остановки; путь отката определён (обычно revert → redeploy), а план отката — по триггерам риска.
    • См. также: Глава 5.

  • План проверки

    • Зачем: доказать корректность результата (выборка + крайние случаи + метрики).
    • Владелец: автор изменения; подтверждает — ревьюер.
    • Готово, если: проверка повторяема и даёт наблюдаемые результаты.
    • См. также: Глава 5, Глава 10.

  • Роли проверки (верификатор / тест‑раннер)

    • Зачем: сделать качество “реальным”, а не “по обещанию”: один исполнитель делает изменение, другой независимо доказывает, что оно работает.
    • Готово, если: есть отчёт “что проверено и прошло / что сломано / что не проверено” + результаты прогонов тестов/проверок (включая golden tests, если они применимы).
    • См. также: Глава 8.

  • PR + ревью человеком

    • Зачем: контроль качества и совместная ответственность.
    • Владелец: автор PR; ревьюер — человек.
    • Готово, если: описание, план проверки, результаты проверок приложены; путь отката определён (и, если требуется по триггерам риска, приложен/проверен подробный план отката).
    • См. также: Глава 5.

2.6 Деплой и безопасность изменений#

  • Модель угроз

    • Зачем: заранее перечислить угрозы и митигации (особенно для автоматизации и изменений в инфраструктуре/доступах).
    • Владелец: владелец системы + security/ревью.
    • Готово, если: активы/угрозы/векторы/митигации/проверки описаны.
    • См. также: Глава 7.

  • План изменений (деплоя)

    • Зачем: безопасная выкатка, минимизация риска, наблюдаемость.
    • Владелец: инженер/эксплуатация (DevOps/SRE) + ревью.
    • Готово, если: есть шаги, контрольные точки, метрики мониторинга и критерии отката.
    • См. также: Глава 7.

  • Откат (путь отката и план отката)

    • Зачем: быстро вернуться в стабильное состояние при деградации.
    • Владелец: автор изменения.
    • Готово, если:
      • путь отката определён всегда (обычно revert → redeploy по вашему стандарту)
      • план отката (шаги, время, проверка) и тест отката на стейджинге — если требуется по триггерам риска (данные/миграции/безопасность/платежи/доступность/необратимые операции)
    • См. также: Глава 5, Глава 7.

2.7 Операции и инциденты#

  • runbook для инцидента

    • Зачем: воспроизводимое реагирование: шаги, окна, проверки, эскалация.
    • Владелец: SRE/дежурная команда; применяет — инженер (или автоматизация).
    • Готово, если: есть шаги триажа, исправления, проверки результата и пост‑действия.
    • См. также: Глава 6.

  • Отладчик (Debugger) как роль RCA

    • Зачем: отделить поиск первопричины от рискованных действий; вернуть проверяемый вклад в пакет решения (доказательства, локализация, проверка).
    • См. также: Глава 6, Глава 9.

  • Отчёт по инциденту

    • Зачем: фиксировать факты, первопричину, действия и “что улучшим”, а не терять знания.
    • Владелец: команда сервиса + SRE.
    • Готово, если: есть хронология, первопричина, исправление, дальнейшие действия и проверка, что действия выполнены.
    • См. также: Глава 6.

2.8 Качество изменений (измеримость)#

  • eval-набор + golden tests
    • Зачем: измерять качество изменений и ловить регрессии до продакшена.
    • Владелец: владелец практики/системы.
    • Готово, если: eval-набор репрезентативен, golden tests стабильны и запускаются регулярно.
    • См. также: Глава 8.

2.9 Управление практикой (чтобы работало “по умолчанию”)#

  • Базовый уровень + контрольные точки качества
    • Зачем: сделать качество и безопасность обязательными, а не “по желанию”.
    • Владелец: владелец практики/платформы (обычно Staff/Principal) + руководство.
    • Готово, если: есть правила, где контрольные точки обязательны, и механизм принудительного применения (например, через CI/CD).
    • См. также: Глава 9.

3) Мини‑шаблоны (минимально достаточные)#

3.1 DoD (минимальный)#

## DoD (критерии “готово”)

- [ ] Критерии приёмки (AC) выполнены и проверены
- [ ] План проверки выполнен: выборка + крайние случаи
- [ ] Нет новых предупреждений линтера
- [ ] Путь отката определён (обычно revert → redeploy); план отката и тест отката — если требуется по триггерам риска
- [ ] Обновлён `runbook` (если изменение влияет на операции)
- [ ] Описаны риски/компромиссы (и зафиксированы решения, если нужно)

3.2 ADR (минимальный)#

# ADR: <DECISION_SHORT_NAME>

## Контекст
- <CONTEXT>

## Решение
- <DECISION_AND_RATIONALE>

## Последствия
- <что стало проще/сложнее, какой долг/риски появляются>

## Когда пересмотреть
- <триггеры: рост нагрузки, новые требования, инциденты, SLO и т.п.>

3.3 Пакет решения (decision packet): минимальный контракт#

Пакет решения (decision packet) — это артефакт, который делает решение проверяемым: отделяет факты от гипотез, фиксирует риск и явно показывает, что требует подтверждения человека.

Минимально достаточные поля (смысл важнее имён полей):

  • summary: 1–3 предложения «что случилось / что делаем дальше».
  • timeline[]: ключевые события с временем (что произошло и когда).
  • hypotheses[]: гипотезы с уровнем уверенности + почему (на каких фактах основано).
  • evidence[]: доказательства (логи/метрики/ссылки на дашборды/PR) — без “кажется”.
  • next_checks[]: следующие безопасные проверки (безопасные по умолчанию).
  • risk: что может пойти не так (данные/безопасность/радиус поражения) и почему это важно.
  • rollback: как откатываем/останавливаем ухудшение (если применимо).
  • verification: как проверим, что стало лучше (метрики/тесты/выборка).
  • requires_approval: что именно требует подтверждения человека и почему.
  • unknowns[]: что мы не знаем (и что нужно, чтобы узнать).

Пример (JSON):

{
  "summary": "INC-...: payroll деградировал после деплоя. Гипотеза: миграция/схема. Дальше — безопасные проверки, затем эскалация.",
  "timeline": [
    {"time": "02:10", "event": "deploy payroll-service v1.2.3"},
    {"time": "02:12", "event": "5xx spike started"}
  ],
  "hypotheses": [
    {
      "id": "H1",
      "summary": "failed DB migration / schema mismatch",
      "confidence": "MEDIUM",
      "why": ["errors mention missing column", "deploy shortly before incident"]
    }
  ],
  "evidence": [
    {"source": "logs", "snippet": "ERROR: column \"new_field\" does not exist"},
    {"source": "dashboard", "link": "<URL>"}
  ],
  "next_checks": [
    {"id": "C1", "description": "confirm migration status", "safe": true}
  ],
  "risk": {"data_risk": "unknown", "blast_radius": "payroll"},
  "rollback": {"plan": "revert deploy (approval required)"},
  "verification": {"success_criteria": ["5xx back to baseline", "latency p95 < <WINDOW>"]},
  "requires_approval": {"required": true, "reason": "prod change / insufficient evidence"},
  "unknowns": ["migration status", "rollback readiness"]
}

3.4 Skill Router: протокол маршрутизации ролей (копируемый)#

Этот протокол — “рабочая дисциплина” для агента: перед любым ответом агент обязан выбрать одну базовую роль (исполнитель) и 0..N проверяющих ролей (по рискам/точкам касания), затем явно зафиксировать TRACE (что реально прочитано).

ROLE ROUTING (MANDATORY)

Before ANY answer you MUST:
1) Run Skill Router and select roles:
   - base role: exactly 1 main role
   - checker roles: 0..N validating roles (based on risks/touchpoints)
2) Immediately print markers (Markdown):
   - **[ROUTER]:** selected skills = <LIST> (base=<BASE>, checkers=<CHECKERS_OR_NONE>)
   - **[TRACE]** read: rules=[...]; skills=[...]; refs=[...]
     TRACE rules:
     - list only actually read files (rules/skills/references)
     - use workspace-relative paths for readability
     - if there are many files: first N + “+X more”
3) Then write the answer using role markers only:
   - **[<ROLE>]:** ...
   - **--- [SWITCHING TO <ROLE>] ---**
   - **--- [RETURNING TO <ROLE>] ---**

IF THE ROLE IS NOT DEFINED
A role is “not defined” when:
- no skill from the catalog matches the task/expected behavior
- or the user explicitly requests behavior/style not covered by available skills/project roles

Then you MUST:
- NOT perform the task
- ask the user to provide a Role Spec (template below)
- after receiving Role Spec, treat it as a “project role” and route to it alongside skills

PROJECT ROLES (sticky, per-project)
If this system prompt (or the conversation) contains Role Specs, treat them as available project roles and use them for routing.

ROLE SPEC TEMPLATE (user must provide)
ROLE: <ROLE_NAME>
WhoIAm: <WHO_I_AM>
Goal: <GOAL>
Tone: <TONE>
Format: <FORMAT>
Constraints: <CONSTRAINTS>
QualityBar: <QUALITY_BAR>

3.5 Масштабирование автономной работы: planners / workers / judge (паттерн)#

Если один агент “тонет” в большом проекте, естественный шаг — параллелить. Практика показывает, что плоская само‑координация через общий список задач и блокировки часто деградирует в bottleneck и хрупкость. Более устойчивый паттерн — разделение ролей:

  • Planners (планировщики): непрерывно исследуют систему и нарезают задачи.
  • Workers (исполнители): берут конкретные задачи и доводят до результата, не пытаясь удерживать “большую картину”.
  • Judge (арбитр итерации): на конце цикла решает, продолжать ли итерацию, и когда делать “fresh start”, чтобы сдерживать drift/tunnel vision.

Источник/пруф (доп. чтение): Cursor: Scaling long-running autonomous coding.

Ремарка: на практике “fresh start” чаще всего реализуется как возврат к плану (plan‑first): уточнить требования/ограничения, обновить план и перезапустить выполнение по нему, вместо того чтобы чинить результат цепочкой уточнений. См. Cursor: Best practices for coding with agents.

4) Типовые ошибки (анти‑паттерны)#

  • Нет DoD: “готово” становится мнением, качество плавает.
  • Нет ADR: спустя время решения приходится восстанавливать по следам.
  • Нет пути отката (и нет плана, когда он нужен): любой сбой превращается в инцидент с высоким MTTR.
  • Нет runbook: реагирование “на героизме”, знания не воспроизводимы.
  • Нет eval/регрессионного набора перед деплоем изменений: регрессии уезжают в продакшен.