ORCH-9 — Принципы подготовки промптов агентов (методичка онбординга)

Репозиторий onboard2orch — методология онбординга (ORCH-9). Это принципы и инструкции, КАК готовить промпты агентов для ЛЮБОГО проекта. enduro-trails (ET) используется как пример-референс — НЕ как шаблон для копирования. Каждый проект пишет СВОИ промпты под свою специфику.

1. Базовый принцип: изоляция

Промпты живут в репо проекта: .openclaw/agents/<role>.md. Launcher читает их в рабочем дереве задачи (cat {system_prompt} внутри work_path).
Промпты СПЕЦИФИЧНЫ для проекта. Стек, домен, ограничения — свои у каждого. НЕ копировать чужие промпты дословно — копировать СТРУКТУРУ и ПРИНЦИПЫ.
Полный набор ролей: analyst, architect, developer, reviewer, tester, deployer.

2. Обязательная структура промпта (каркас)

Каждый промпт роли строится по единому каркасу (референс — enduro-trails/.openclaw/agents/architect.md):

---
name: <role>
description: <одна строка — роль и зона ответственности>
model: <модель — сверить с src/agents/launcher.py AGENT_CONFIGS>
tools:
  - <разрешённые инструменты, напр. Filesystem Read везде / Write только docs|src>
---

# System prompt: <Role>
<кто ты в этом проекте, твоя задача>

## Контекст проекта
<стек, среды, ключевая специфика — КОРОТКО, детали в CLAUDE.md>

## Что прочесть в начале
1. CLAUDE.md (паспорт проекта)
2. docs/architecture/README.md
3. <релевантные артефакты задачи: docs/work-items/<id>/...>
4. <глобальные ADR: docs/architecture/adr/ — для architect/developer>

## Что произвести
<точные имена артефактов, которые роль ПИШЕТ — по канону проекта>

## Принципы
<доменные принципы проекта — из BRD/архитектуры>

## Запрещено
<анти-паттерны для этого проекта>

## Эскалация
<когда возврат на предыдущую стадию / нужен approve Owner>

3. Что ОБЯЗАНО быть в КАЖДОМ промпте (инварианты канона)

Независимо от проекта:

«Прочти CLAUDE.md и docs/architecture/README.md перед работой» — в разделе «Что прочесть в начале».
Точные имена артефактов проекта в «Что произвести» (берутся из CLAUDE.md проекта; у каждого проекта свой набор — см. п.5).
Golden source: «изменил функционал → обнови документацию В ТОМ ЖЕ изменении».
Не править артефакты других стадий.
Не закрывать задачу самостоятельно — это делает CI / финальная стадия.
Машинные вердикты — только YAML-frontmatter (verdict:, deploy_status:, staging_status:), никогда проза. Это читают Quality Gates.

4. Роль-специфичные инварианты

analyst → производит BRD/ТЗ/AC/Test-Plan; НЕ проектирует решения.
architect → заводит ADR (per-work-item + сквозные в docs/architecture/adr/); обновляет docs/architecture/README.md при изменении состава компонентов; эскалирует крупные изменения (лейбл arch:major-change, approve Owner).
developer → код+тесты+PR; обновляет CHANGELOG и релевантную доку; не закрывает задачу.
reviewer → пишет 12-review.md с verdict:. Reviewer-gate: если PR меняет функционал, а документация (docs/, CHANGELOG, ADR) НЕ обновлена → verdict: REQUEST_CHANGES с указанием, что обновить. Это держит канон автоматически.
tester → прогон по test-plan → 13-test-report.md с машинным PASS/FAIL.
deployer → деплой/проверка; пишет 14-deploy-log.md (+ 15-staging-log.md если у проекта есть staging-гейт). Знает инфра-риски проекта (см. docs/operations/INFRA.md если есть).

5. Откуда брать значения для конкретного проекта

Что	Источник
Имена артефактов	`CLAUDE.md` проекта (раздел «Артефакты задачи»)
Модель роли	`src/agents/launcher.py` → `AGENT_CONFIGS` (НЕ выдумывать)
Стек / домен / ограничения	`CLAUDE.md` + `docs/architecture/README.md` проекта
Цепочка стадий и QG	`src/stages.py` / `docs/architecture/README.md`
Инфра-риски (для deployer)	`docs/operations/INFRA.md` проекта (если есть)

6. Пример-референс: enduro-trails

Готовый, обкатанный в бою набор: enduro-trails (эталонный репо) .openclaw/agents/*.md. Изучать как ОБРАЗЕЦ структуры и тона:

architect.md — эталон каркаса (frontmatter → контекст → что прочесть → что произвести → принципы → запрещено → эскалация).
Видно, как доменная специфика (MapLibre/OSRM/terrain, «всё в Docker», «vanilla JS > React») зашита в «Принципы» и «Запрещено».
При онбординге нового проекта: взять этот каркас, заменить ВСЁ доменное содержимое на специфику нового проекта. Не тащить enduro-специфику в чужой проект.

7. Чеклист готовности набора промптов проекта

Все 6 ролей заведены в .openclaw/agents/
Каждый ссылается на CLAUDE.md + docs/architecture/README.md
Имена артефактов совпадают с CLAUDE.md проекта
Модели сверены с launcher.py
reviewer содержит reviewer-gate на документацию
Доменные «Принципы» и «Запрещено» — под этот проект, не скопированы у другого
deployer знает инфра-специфику/риски проекта

Методичка ORCH-9. enduro-trails — пример-референс, не шаблон. Каждый проект изолирован и пишет свои промпты по этим принципам.

7.5 KiB Raw Blame History Unescape Escape