# agent-prompt-kit

**Превращает уже сделанную работу в специализированное окружение для следующей. Одна команда читает текущую сессию и связанные сессии рантайма, составляет карточку задачи и карточку домена и создаёт Workspace или сохранённого агента, где уже лежат правила, критерий приёмки, разобранные примеры и хранилище прежней работы. Четырнадцать модулей, проверяемых машиной.**

[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![Modules](https://img.shields.io/badge/modules-14-6f42c1)](PROMPT.ru.md)
[![Lint](https://img.shields.io/badge/lint-prompt__lint.py-informational)](tools/prompt_lint.py)
[![Experience](https://img.shields.io/badge/experience-reuse-0f766e)](skills/experience-reuse/SKILL.ru.md)
[![Rules](https://img.shields.io/badge/lint%20rules-27-brightgreen)](tools/prompt_lint.py)
[![English version](https://img.shields.io/badge/lang-EN%20%2F%20RU-0ea5e9)](README.md)

<img src="https://github.com/paulmann/agent-prompt-kit/raw/main/assets/social-preview.png"
     alt="agent-prompt-kit — переносимый системный промпт, делающий агента специалистом"
     width="100%">

Хороший ответ умирает вместе с чатом. Когда тот же класс работ приходит снова, свежая сессия
начинает с нуля: тот же разбор, те же тупики, те же вопросы. Набор делает это повторение дешёвым —
не тем, что агент «лучше помнит», а тем, что после работы остаётся **зарегистрированное рабочее
окружение**.

Одна команда — один результат: каталог (Workspace или сохранённый агент), где уже лежат правила этого
класса работ, карточка домена с проверяемым критерием приёмки, разобранные примеры вместе с провалом,
хранилище прежней работы и стартовый промпт для следующего окна.

| Что делает команда | Почему это важно |
|---|---|
| читает текущую сессию **и связанные сессии рантайма** | материал — реальная работа, а не её описание |
| составляет карточку задачи и карточку домена до действий | тема объявлена, а не подразумевается |
| создаёт каталог окружения со всеми частями | следующий круг начинается с одиннадцатого шага, а не с первого |
| называет шаг регистрации для каждого рантайма | HARNESS: один клик; AutoClaw2: перезагрузка; изображать иное — и есть дефект |
| передаёт стартовый промпт | каталог без передачи — музей, а не рабочее место |

Каждое утверждение о рантайме в этом репозитории помечено: замерено здесь или сообщено из сессии —
см. [`docs/INSTALL.ru.md`](docs/INSTALL.ru.md).

> **Состояние.** Все числа здесь измерены 2026-10-24 для версии 1.2.0 командой
> `python tools/prompt_lint.py`. Длинные руководства — в [`docs/`](docs/) и
> [Wiki](https://github.com/paulmann/agent-prompt-kit/wiki).

## Содержание

- [Что это](#что-это)
- [В цифрах](#в-цифрах)
- [Установка](#установка)
- [Рантаймы](#рантаймы)
- [Использование](#использование)
- [Четырнадцать модулей](#четырнадцать-модулей)
- [Переиспользование опыта](#переиспользование-опыта)
- [Ворота качества](#ворота-качества)
- [Переносимость](#переносимость)
- [Документация](#документация)
- [Языки](#языки)
- [Разработка](#разработка)
- [Участие в проекте](#участие-в-проекте)
- [Лицензия](#лицензия)

## Что это

Один файл `PROMPT.md` плюс материал, чтобы ему доверять и его адаптировать.

| Часть | Что даёт |
|---|---|
| [`PROMPT.ru.md`](PROMPT.ru.md) | сам промпт: 14 модулей, 14 самопроверок, 10 инвариантов |
| [`AGENTS.ru.md`](AGENTS.ru.md) | тот же контракт в машинной форме — для агентов, читающих правила репозитория |
| [`skills/experience-reuse/`](skills/experience-reuse/SKILL.ru.md) | навык M13: workflow, чек-лист применимости, четыре шаблона записей, политика безопасности |
| [`tools/experience.py`](tools/experience.py) | хранилище опыта и доставание одной командой, с проверкой схемы и секретов |
| [`memory/`](memory/README.ru.md) | где живут записи; три очищенных примера идут в поставке |
| [`tools/prompt_lint.py`](tools/prompt_lint.py) | проверяет полноту модулей, парность переводов, заготовки, ссылки, секреты, согласие версий, M13 и ширину ворот |
| [`examples/EXAMPLES.ru.md`](examples/EXAMPLES.ru.md) | три домена одной формы: обычный случай, неоднозначный, провал |
| [`docs/`](docs/) | обоснование дизайна, протокол адаптации, чек-лист QA, валидация по исходной цели |

Промпт решает пять конкретных проблем, по порядку:

1. **Дрейф темы** — агент отвечает на соседний, более лёгкий вопрос. Противоядие — карточка задачи
   (M1) и карточка домена (M2), существующие до любого действия.
2. **Выдуманный контекст** — «как мы обсуждали» о переписке, которую не читали. Противоядие —
   журнал контекста (M3) и три метки свидетельств (M4).
3. **Непроверяемые утверждения** — «это работает» без наблюдения. Противоядие — рабочий цикл (M5),
   таблица возможностей (M6) и ворота (M8).
4. **Повторная работа** — та же задача делается заново, потому что прежняя попытка не всплыла.
   Противоядие — хранилище опыта и проверка применимости (M13).
5. **Стоимость переиспользования** — новый домен требует переписать промпт. Противоядие — протокол
   специализации (M10): одна карточка, один файл примеров, одна строка приёмки.

## В цифрах

Измерено в этом дереве 2026-10-24:

| Поверхность | Значение | Источник измерения |
|---|---:|---|
| Модулей в промпте | 14 | `PROMPT.md`, заголовки `M0`…`M13` |
| Строк самопроверки | 14 | `grep -c '^\*\*Check:\*\*' PROMPT.md` |
| Инвариантов | 10 | `PROMPT.md`, раздел «Инварианты» |
| Проверок ворот качества | 12 | `PROMPT.md`, раздел M8 |
| Различных правил в линтере | 27 | `grep -o 'add("[a-z]*", "[a-z.-]*"' tools/prompt_lint.py \| sort -u` |
| Самопроверок хранилища опыта | 13 | `python tools/experience.py selftest` |
| Проработанных примеров | 3 + 3 очищенных записи | `examples/`, `skills/experience-reuse/examples/` |
| Зависимостей | 0 | импорты в `tools/` |

## Установка

```bash
git clone https://github.com/paulmann/agent-prompt-kit.git
cd agent-prompt-kit

python tools/prompt_lint.py            # код 0 — документ структурно полон
```

Нужен только Python 3.11+. Ни пакетов, ни сервиса, ни учётной записи.

## Рантаймы

Одна и та же процедура, три разных механизма. Что может модель и что обязан человек — различается по
рантаймам, и таблица говорит, что именно. Замерено на этой машине либо помечено как сообщённое из
сессии.

| Рантайм | Команда | Модель делает | Человек делает | Проверено |
|---|---|---|---|---|
| **AutoClaw2** | `/agent-prompt-kit` (и `/skill:agent-prompt-kit`) | пишет навык в `%USERPROFILE%\.pi\agent\skills\` и команду в `...\prompts\` | перезагружает, чтобы снимок ресурсов пересобрался | замерено в бандле приложения |
| **HARNESS** | `/agent-prompt-kit` | создаёт весь каталог Workspace со всеми файлами | один клик: добавить каталог как Workspace | механизм замерен здесь; клик — из сессии |
| **SagaAI** | — | вставить `PROMPT.ru.md` как рабочий контракт | по требованиям рантайма | **не проверено**: установщик отказывается угадывать |

```bash
python tools/install.py --runtime autoclaw2 --check    # файлы и состояние регистрации
python tools/install.py --runtime autoclaw2 --write    # установить, заменяемое — с бэкапом
python tools/install.py --runtime harness  --write
```

Установщик никогда не сообщает ручной шаг как выполненный. В HARNESS он печатает клик; в AutoClaw2
проверяет манифест ресурсов и говорит `NOT READY`, пока перезагрузка не произошла. Полная механика и
таблица ловушек: [`docs/INSTALL.ru.md`](docs/INSTALL.ru.md).

## Использование

1. Откройте `PROMPT.ru.md`.
2. Вставьте всё ниже YAML-заголовка в поле системного промпта вашего агента.
3. Дайте агенту настоящий запрос. Он обязан ответить карточкой задачи, карточкой домена,
   результатом, метками свидетельств и строкой ворот.

Промпт сознательно не привязан к инструментам — см. [Переносимость](#переносимость). Проработанный
ответ в трёх несвязанных доменах — в [`examples/EXAMPLES.ru.md`](examples/EXAMPLES.ru.md).

## Четырнадцать модулей

| Модуль | На какой вопрос отвечает | Чем проверяется |
|---|---|---|
| M0 | Чей это голос и какие у него две фазы? | тема названа одним предложением |
| M1 | Что на самом деле просят? | карточка задачи, каждое поле заполнено или `неизвестно` |
| M2 | Какой специалист нужен и что он обязан проверить? | карточка домена, условие приёмки проверяемо |
| M3 | Какой контекст существует и насколько он хорош? | журнал контекста с источником на утверждение |
| M4 | Как помечать то, что я знаю? | `[факт]` / `[вывод]` / `[предположение]` |
| M5 | Как работать, ничего не ломая? | цикл: рамка → достать → план → шаг → проверка → запись |
| M6 | Чем можно пользоваться и что запрещено? | таблица возможностей, правила безопасности |
| M7 | Какую форму имеет ответ? | пять разделов плюс необязательный раздел использованного опыта |
| M8 | Откуда знать, что работа закончена? | двенадцать проверок, сообщаемых строкой |
| M9 | Как побеждают этот промпт? | шестнадцать режимов отказа с противоядиями |
| M10 | Как направить его на новый домен? | одна карточка, один файл примеров, одна строка приёмки |
| M11 | Как выглядит хороший ответ? | три проработанных примера |
| M12 | Что проверить перед отправкой? | пять вопросов, по строке на каждый |
| M13 | Как не делать заново уже сделанное? | доставание до планирования, вердикт применимости, очищенное хранилище |

## Переиспользование опыта

M13 превращает «мы это делали» из надежды в вызов инструмента:

```bash
python tools/experience.py search "добавить nullable колонку в эндпоинт списка" --limit 5
```

```text
query: добавить nullable колонку в эндпоинт списка  ·  2 candidate(s)
  [ 25] recipe    add-nullable-column-to-list-endpoint validated overlap 5, validated, high confidence, verified 2d ago
  [ 11] failure   retry-migration-until-it-passes    validated overlap 1, validated, prior failure: read before acting
```

Каждая строка несёт причину своей позиции, поэтому агент отвергает кандидата по свидетельству, а не
по ощущению. Переиспользование решают шесть вопросов — цель, окружение, допущения, покрытие
проверкой, безопасность, свежесть, — и невысказанная адаптация считается слепым копированием.

Что хранилище отвергает, по своим же тестам: запись с литералом, похожим на токен; рецепт без
раздела `Rollback`; запись без `last_verified_at`, помеченную `validated`. О чём предупреждает:
проверка старше 180 дней, почти-дубликат заголовка. Чего не делает никогда: не удаляет — записи
помечаются устаревшими со ссылкой на замену.

## Ворота качества

Агент обязан напечатать одну строку, например `ворота 12/12` или
`ворота 10/12 — 6, 9 провалены: <причина>`. Двенадцать проверок определены в M8; две, что
проваливаются чаще всего на практике:

- **№4 покрытие свидетельствами** — фактическое утверждение, не попавшее в журнал контекста;
- **№6 проверка** — «это работает» без команды или наблюдения.

Строка ворот — не украшение: именно она делает ответ аудируемым для того, кто не видел работы
агента. `docs/QA.md` превращает те же двенадцать проверок в человеческий чек-лист ревью.

## Переносимость

В промпте нет имён инструментов. Возможности названы классом и разрешаются в каждом рантайме:

| Класс возможности | Примеры соответствий |
|---|---|
| `read-files` | инструмент чтения, `cat` в оболочке, буфер редактора |
| `write-files` | инструмент записи/патча, heredoc, встроенная подсказка |
| `run-commands` | оболочка, песочница, CI-раннер |
| `web-search` | поиск, браузер, присланные пользователем адреса |
| `publish` | `git push`, реестр пакетов, API вики |

Если возможности нет, промпт деградирует явно (M6): просит содержимое, выдаёт артефакт текстом или
называет отсутствующую возможность. Он никогда не делает вид.

Проверенные цели импорта: AutoClaw2, HARNESS, SagaAI и любой агент, принимающий системный промпт.
Машинный вариант — [`AGENTS.ru.md`](AGENTS.ru.md).

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

| Документ | Содержание |
|---|---|
| [`docs/DESIGN.ru.md`](docs/DESIGN.ru.md) | почему модули, какие решения отвергнуты и почему |
| [`docs/ADAPTATION.ru.md`](docs/ADAPTATION.ru.md) | специализация под новый домен за пятнадцать минут |
| [`docs/QA.ru.md`](docs/QA.ru.md) | чек-лист ревью, выведенный из ворот |
| [`docs/VALIDATION.ru.md`](docs/VALIDATION.ru.md) | исходная цель, требование за требованием, с проверкой на каждое |
| [`examples/EXAMPLES.ru.md`](examples/EXAMPLES.ru.md) | три домена, три карточки, три строки ворот |

## Языки

Английские файлы основные, русские копии несут суффикс `.ru.md` — конвенция самого GitHub. Оба
набора держит в синхроне `tools/prompt_lint.py`: он роняет сборку, если у документа нет пары.

| Английский | Русский |
|---|---|
| [README.md](README.md) | [README.ru.md](README.ru.md) |
| [PROMPT.md](PROMPT.md) | [PROMPT.ru.md](PROMPT.ru.md) |
| [AGENTS.md](AGENTS.md) | [AGENTS.ru.md](AGENTS.ru.md) |
| [docs/VALIDATION.md](docs/VALIDATION.md) | [docs/VALIDATION.ru.md](docs/VALIDATION.ru.md) |

## Разработка

```bash
python tools/prompt_lint.py            # структурные контракты
python tools/prompt_lint.py --json     # машинный вывод
```

Правка промпта:

1. Правьте `PROMPT.md`; идентификаторы модулей не меняйте — на них ссылаются инструменты и ревью.
2. Обновите `PROMPT.ru.md` тем же коммитом.
3. Поднимите `version` в заголовке и добавьте запись в `CHANGELOG.md`; линтер сравнивает их.
4. Гоняйте линтер до кода `0`.

## Участие в проекте

См. [CONTRIBUTING.ru.md](CONTRIBUTING.ru.md). Политика безопасности — [SECURITY.ru.md](SECURITY.ru.md).

## Лицензия

[MIT](LICENSE).