Память агентов и жизненный цикл Skills¶

Статус: ДЕЙСТВУЕТ.

Обновлено: 2026-08-26.

Назначение¶

Система сохраняет повторно применимый опыт разработки SKUARO и превращает подтверждённые процедуры в проектные Skills. Она не заменяет канонические документы, Git, тесты или разрешения владельца.

Слои знаний¶

Слой	Назначение	Источник истины
Правила и решения	Обязательные границы и принятые выборы	`AGENTS.md`, policy, architecture, ADR
Текущее состояние	Что реализовано, заблокировано и следует делать дальше	`docs/STATUS.md`
Опыт	Повторяемое знание о сработавших и неудачных подходах	`docs/agent-memory/`
Skill	Проверяемая повторяемая процедура	`.agents/skills/<skill-name>/`
История сессии	Фактический отчёт конкретной работы	`logs/sessions/` и Git

При противоречии запись опыта или Skill уступает каноническому правилу и актуальному состоянию. Агент останавливает затронутое действие, показывает конфликт и запрашивает решение.

Запись или Skill получает подтверждённый статус только после evidence gate по docs/AGENT_WORKFLOW.md. Заявление автора без проверки не переводит процедуру в VALIDATED или ACTIVE.

Порядок перед задачей¶

Восстановить обязательный контекст по AGENTS.md.
Определить тип задачи и её ключевые входы, выходы, область и permissions.
Поискать подходящий проектный Skill в .agents/skills.
Поискать релевантный опыт в docs/agent-memory по типу задачи, тегам, компоненту и известной ошибке.
Использовать только применимые записи с совместимыми предпосылками; устаревший опыт проверить по текущему коду и документации.

Когда создавать запись опыта¶

Запись создаётся, если выполнено хотя бы одно условие:

найдено неочевидное и подтверждённое решение;
обнаружен повторяемый сбой и установлен способ диагностики;
доказан безопасный порядок действий;
выявлено ограничение инструмента или среды;
новый подход измеримо лучше прежнего;
результат полезен другой роли или следующей сессии.

Обычные команды, очевидные действия и полный терминальный вывод отдельно не сохраняются. Их достаточно перечислить в отчёте задачи или session log.

Формат записи опыта¶

Файл: docs/agent-memory/YYYY-MM-DD-краткая-тема.md.

# Краткое название

- Дата:
- Статус: OBSERVED | VALIDATED | SKILL_CANDIDATE | ACTIVE | DEPRECATED | BLOCKED
- Тип задачи:
- Компоненты:
- Теги:
- Связанные решения:
- Связанный Skill: отсутствует | путь

## Контекст и границы

## Что сработало

## Что не сработало и почему

## Проверки и свидетельства

## Когда применять

## Когда не применять

## Следующее улучшение

Запись содержит ссылки на факты и проверки, а не секреты, credentials, PII, реальные клиентские данные или полный чат.

Продвижение опыта в Skill¶

Состояние	Условие	Следующее действие
`OBSERVED`	подход сработал один раз	сохранить и повторно проверить
`VALIDATED`	подход подтверждён повтором или независимым тестом	оценить повторяемость
`SKILL_CANDIDATE`	стабильный процесс экономит время или снижает риск	создать или обновить Skill
`ACTIVE`	Skill проверен и доступен проекту	применять по описанию
`DEPRECATED`	процесс заменён или больше не применим	указать замену, не удалять историю
`BLOCKED`	процесс небезопасен или зависит от нерешённого условия	не применять до снятия блокировки

Сложная, дорогая или рискованная процедура может перейти в SKILL_CANDIDATE после первого подтверждённого выполнения, если формализация явно снижает риск.

Создать новый или обновить существующий¶

Перед созданием агент сравнивает:

цель;
входные данные;
ожидаемый результат;
область проекта;
необходимые permissions;
риски и условия остановки.

Если эти элементы совпадают, обновляется существующий Skill. Новый Skill создаётся только для существенно отличающегося контракта. Совпадающие имена не используются: Codex не объединяет одноимённые Skills автоматически.

Требования к Skill¶

одно понятное назначение;
точное name и различающее description;
явные входы, выходы и границы применимости;
инструкции по проверке результата;
условия безопасной остановки;
ссылки только на действительно нужные references;
scripts только для детерминированной повторяемой механики;
отсутствие секретов и скрытого расширения полномочий.

Изменение должно исправлять подтверждённый недостаток или давать проверяемое улучшение. Для нового или существенно изменённого Skill выполняются структурная валидация, реалистичный dry-run либо тест наблюдаемого результата и review границ.

Критические Skills¶

К критическим относятся deploy, migration, backup/restore, удаление, production, секреты и security-операции.

Для них обязательны:

независимый tester и/или reviewer;
отдельное разрешение перед фактическим опасным действием;
проверяемые предусловия и остановка при неопределённости;
rollback или recovery plan;
запрет на самоактивацию обновлённой версии во время текущей операции.

Реестр памяти¶

Запись	Статус	Область	Связанный Skill
Общая память и Skills	`ACTIVE`	Процесс разработки	`.agents/skills/agent-learning`
Доказательная передача задач	`ACTIVE`	Межагентная приёмка	`.agents/skills/task-verification`
Resend и проверка DNS	`OBSERVED`	Email integration / DNS	отсутствует
Canonicalization-safe redaction Auth-токенов	`VALIDATED`	Auth/runtime logging security	отсутствует
Чистый Compose env и Caddy recreate при rollback	`VALIDATED`	DEV/STAGE deploy / rollback	отсутствует
Отдельный production-readiness контур	`SKILL_CANDIDATE`	Production audit / repair / GO-NO-GO	`.agents/skills/production-readiness`