# Брейншторм: Промпты и контекст агентов
Дата: 2026-02-21

## Prompt Architecture

Многослойный промпт:

```
1. System Prompt (agent.json)     — базовая роль, неизменная
2. Agent Prompt (prompt.md)       — агент САМ улучшает
3. Project Context (docs)         — документация проекта
4. Skills (SKILL.md)              — progressive loading
5. Tools (MCP)                    — автоматически
6. Guidelines                     — общие правила работы
7. Session History                — предыдущие сообщения
8. Current Message                — текущее событие
```

## System Prompt vs Agent Prompt

| | System Prompt | Agent Prompt |
|---|---|---|
| Файл | `agent.json → prompt` | `prompt.md` в agent home |
| Кто меняет | Человек | Агент сам |
| Содержание | Базовая роль | Best practices, уроки, стиль |

System prompt = конституция (не трогаем).
Agent prompt = записная книжка (агент дополняет после задач).

## Agent Home Directory

```
agents/coder/
  agent.json           # конфиг (не меняется агентом)
  prompt.md            # промпт, который агент САМ улучшает
  memory/
    project-a.md       # память по проекту A
    project-b.md       # память по проекту B
  workspace/           # рабочее барахло (downloads, temp)
  skills/              # скилы
  sessions/            # сессии (JSONL)
```

## Guidelines (общие для всех)

```markdown
## Работа с задачами
- Получил задачу → прочитай описание через get_task()
- Если сложная → разбей на этапы через add_step()
- Обновляй этапы через complete_step()
- Декомпозиция → create_task(parent_id=...)
- Не можешь → reject_task() с объяснением
- Завершил → add_comment() + update_task(status="in_review")

## Коммуникация
- Вопрос → send_message() с @mention
- Не хватает контекста → read_messages()
- Не отвечай на чужое (если listen_mode=mentions)

## Git
- Ветка: task/{номер}-{slug}
- Коммиты с осмысленными сообщениями
- Конфликт → разреши сам или попроси

## Самоулучшение
- После задачи: запиши findings в prompt.md
- Перед задачей: прочитай prompt.md
- Записывай: паттерны проекта, частые ошибки, предпочтения ревьюера
- НЕ дублируй system prompt

## Memory
- После задачи → допиши в memory/{project}.md
- Перед задачей → прочитай memory
```

## Документация проекта

### Два источника
- **Git repo** (`docs/`) — для проектов с кодом, версионировано
- **File storage** — всегда доступно, для всех проектов

### Описание проекта указывает где docs
```json
{
  "docs_source": "git" | "storage" | "both",
  "repo_urls": ["https://..."]
}
```

### File storage = минимум
Даже если проект в git, file storage всегда есть:
- Артефакты (скриншоты, диаграммы)
- Docs для проектов без git
- Вложения из чата

### Агент может обновлять docs
- Git → clone, commit, push
- Storage → upload_file()
- Не удалять чужое — только дополнять

## Примеры System Prompt по ролям

### Кодер
```
Ты опытный разработчик. Пишешь чистый, читаемый код.
Следуешь best practices: обработка ошибок, тесты, понятные имена.
Перед началом всегда изучаешь существующий код.
```

### Архитектор
```
Ты архитектор. Принимаешь технические решения, декомпозируешь задачи.
Предпочитаешь простые решения. "Boring technology" > хайп.
Каждое решение обосновываешь.
```

### Тестер
```
Ты QA-инженер. Находишь баги, пишешь тесты, проверяешь edge cases.
Никогда не говоришь "всё ок" если не проверил.
```

### DevOps
```
Ты DevOps-инженер. CI/CD, деплой, мониторинг, инфраструктура.
Автоматизируешь всё что можно. Безопасность — приоритет.
```

## Идеи на подумать

- **Dynamic prompt по типу задачи**: bug → "сначала воспроизведи", epic → "декомпозируй"
- **Prompt по лейблам**: frontend → React tips, backend → API tips
- **MetaGPT SOP**: Input → Process → Output для каждого типа задачи