95 lines
7.5 KiB
Markdown
95 lines
7.5 KiB
Markdown
# 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. Что ОБЯЗАНО быть в КАЖДОМ промпте (инварианты канона)
|
||
Независимо от проекта:
|
||
1. **«Прочти `CLAUDE.md` и `docs/architecture/README.md` перед работой»** — в разделе «Что прочесть в начале».
|
||
2. **Точные имена артефактов проекта** в «Что произвести» (берутся из CLAUDE.md проекта; у каждого проекта свой набор — см. п.5).
|
||
3. **Golden source:** «изменил функционал → обнови документацию В ТОМ ЖЕ изменении».
|
||
4. **Не править артефакты других стадий.**
|
||
5. **Не закрывать задачу самостоятельно** — это делает CI / финальная стадия.
|
||
6. **Машинные вердикты** — только 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 — пример-референс, не шаблон. Каждый проект изолирован и пишет свои промпты по этим принципам.*
|