Files

T

2026-10-08 15:40:35 +03:00

10 KiB

Raw Blame History

MetaAgent GUIDE v3.0

MetaAgent — набор инструкций для AI-агента. Задача: превратить хаотичное общение с агентом в структурированный процесс, в котором состояние проекта переживает любую сессию.

Два слоя

Цикл (всегда, по необходимости) — последовательность фаз, которую агент проходит при работе с проектом.
Команды (по запросу пользователя) — on-demand инструкции, которые не привязаны к фазе.

Состояние проекта живёт в .agent/ целевого репозитория. Следующий агент читает .agent/ и не лезет в исходники.

Цикл

                    .agent/checkpoints.json
                              │
                              ▼
        ┌─────────────────────────────────────┐
        │          PROJECT LOOP (разово)        │
        │                                     │
        │  INIT → ANALYSE → ROADMAP →         │
        │  → [DESIGN] → DECOMPOSITION         │
        │                                     │
        │  Выход: .agent/tasks/manifest.json  │
        └──────────────────┬──────────────────┘
                           │
                           ▼
        ┌─────────────────────────────────────┐
        │          WORK LOOP (циклически)      │
        │                                     │
        │  EXECUTION → (request) →            │
        │  → METASTATE (по команде)           │
        │                                     │
        │  Беру задачу → делаю → request →    │
        │  накопилось → METASTATE             │
        └──────────────────┬──────────────────┘
                           │
                           ▼
                  HANDOFF (завершение)

Фазы выполняются строго последовательно внутри PROJECT LOOP. WORK LOOP повторяется многократно.

Ветвление

Тип проекта	Цикл
existing	INIT → ANALYSE → ROADMAP → DECOMPOSITION → EXECUTION → METASTATE → HANDOFF
greenfield / scaffold	+ фаза DESIGN между ROADMAP и DECOMPOSITION

Тип проекта определяется автоматически в фазе ANALYSE. Никакого интервью с пользователем, никакой шкалы глубины.

Фазы

#	Фаза	Протокол	Что делает
0	INIT	`PROTOCOLS/00_INIT.md`	Создаёт `.agent/`, ставит исходники, инициализирует checkpoints
1	ANALYSE	`PROTOCOLS/01_ANALYSE.md`	Сканирует проект, создаёт `analysis-report.md` + начальный `project-state.md`
2	ROADMAP	`PROTOCOLS/02_ROADMAP.md`	Собирает источники задач (FUTURE, ADR, user-запросы) → `roadmap/sources.md`
3	DESIGN	`PROTOCOLS/03_DESIGN.md`	Только greenfield. Архитектура, модули, API, модели
4	DECOMPOSITION	`PROTOCOLS/04_DECOMPOSITION.md`	Разбивает цель на атомарные задачи → `tasks/manifest.json`
5	EXECUTION	`PROTOCOLS/05_EXECUTION.md`	Цикл: берёт задачу → код → тесты → коммит → request
6	METASTATE	`PROTOCOLS/06_METASTATE.md`	По команде. Ревью requests, обновление project-state, handoff-summary
7	HANDOFF	`PROTOCOLS/07_HANDOFF.md`	Валидация `.agent/`, финализация checkpoints, session-summary

Команды

Эти инструкции выполняются по явной просьбе пользователя в любой момент сессии. Они не привязаны к фазе.

Команда	Файл	Что делает
«запиши ADR» / «/adr»	`COMMANDS/adr.md`	Создаёт `.agent/decisions/NNN-slug.md`
«red team» / «/red-team»	`COMMANDS/red-team.md`	Создаёт `.agent/context/red-team-report.md` — попытка сломать дизайн
«risk register» / «/risk-register»	`COMMANDS/risk-register.md`	Создаёт `.agent/context/risk-register.md`
«альтернативная архитектура» / «/alt-arch»	`COMMANDS/alt-arch.md`	Описывает альтернативу текущему дизайну
«invariant-тесты» / «/invariant-tests»	`COMMANDS/invariant-tests.md`	Создаёт задачи-инварианты для ADR

Когда вызывать

ADR — после архитектурного решения, которое нужно зафиксировать. Типично во время DESIGN или при появлении неочевидного выбора в EXECUTION.
Red Team — после готового дизайна, чтобы найти слабые места до реализации.
Risk Register — в начале проекта или при появлении новых допущений.
Alt Arch — если сомневаетесь в выбранном подходе, хотите сравнить варианты.
Invariant Tests — после ADR, чтобы зафиксировать «что не должно сломаться».

Команды не обязательны. Если не вызваны — не выполняются. Состояние проекта от них не зависит.

Структура `.agent/`

.agent/
  checkpoints.json                  # состояние сессии (ядро)
  session-summary.md                # краткая сводка сессии
  handoff-summary.md                # сводка для следующего агента (создаётся METASTATE)

  src/                              # исходники MetaAgent (всегда)
    GUIDE.md
    BOUNDARIES.md
    CHANGELOG.md
    PROTOCOLS/
    COMMANDS/
    TEMPLATES/
    VERSION
    install.sh / install.ps1

  rules/
    project-rules.md                # ваши правила — читать перед каждой фазой

  roadmap/                          # источники задач
    sources.md
    archive/

  decisions/                        # ADR
    index.json
    001-*.md

  tasks/                            # задачи
    manifest.json + manifest.md
    backlog/

  requests/                         # результаты выполненных задач
    active/                         #   ready_for_review
    archive/                        #   approved / rejected

  context/
    analysis-report.md
    project-state.md                # обновляется в METASTATE
    design-report.md                # только greenfield
    red-team-report.md              # если вызывали /red-team
    risk-register.md                # если вызывали /risk-register
    baseline-test-report.log

  archive/
    index.json
    tasks/
    decisions/
    requests/
    checkpoints/

.temp/ в корне проекта — для временных файлов агента. Всегда в .gitignore.

Checkpoints

checkpoints.json обновляется после каждой фазы:

{
  "metaagent_version": "3.0.0",
  "session_id": "<uuid>",
  "target_repo": "<path>",
  "goal": "<цель>",
  "project_type": "existing | greenfield | scaffold",
  "phases": {
    "init": "completed",
    "analyse": "completed",
    "roadmap": "completed",
    "design": "skipped",
    "decomposition": "completed",
    "execution": "in_progress",
    "metastate": "pending",
    "handoff": "pending"
  },
  "tasks": [
    { "id": "T1", "title": "...", "status": "in_progress", "origin": "user:direct" }
  ],
  "last_updated": "<timestamp>"
}

Секции config больше нет. Параметры, которые раньше были в config (depth, adr, red_team и т.п.), теперь либо не существуют, либо живут в отдельных командах.

Принципы

Цикл vs команды

Цикл — это «что агент делает по умолчанию». Команды — «что агент делает по явной просьбе». Не путать: ADR не запускается автоматически в DESIGN, а только когда пользователь скажет «запиши это как решение».

`.agent/` как слепок проекта

После METASTATE .agent/ содержит всю картину. Следующий агент читает только .agent/, не исходники.

Request — единица результата

Каждая выполненная задача в EXECUTION завершается созданием request (.agent/requests/active/req-{id}.json). Request содержит суть изменений, коммиты, верификацию, закрытые acceptance criteria. Ревью request-ов происходит в METASTATE.

Правила выше протоколов

Перед каждой фазой читать .agent/rules/project-rules.md. Если правило пользователя противоречит протоколу — следовать правилу.

Контекст бесконечно не растёт

Завершённые задачи архивируются в .agent/archive/tasks/, request-ы — в .agent/requests/archive/. Текущий manifest остаётся lean.

10 KiB Raw Blame History