SOP: Закодировать невидимое знание в репозиторий

Используйте этот SOP, когда важный контекст всё ещё живёт в Google Docs, тредах чатов, тикетах или головах людей.

Цель

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

Сигналы триггера

• Агент постоянно спрашивает, как работает система.
• Люди говорят «мы это решили в Slack» или «следуй тому, что X сказал на прошлой неделе».
• Ревью ссылается на продуктовые правила или правила безопасности, которых нет в репозитории.
• Новые сессии повторяют работу по обнаружению, которая уже должна быть закрыта.

SOP исполнения

1. Перечислите источники невидимого знания: документы, чаты, негласные командные правила, устные решения.
2. Для каждого источника спросите: это архитектура, продуктовое поведение, политика безопасности, ожидание по надёжности, контекст плана или справочный материал?
3. Закодируйте это в соответствующий артефакт репозитория:
   • архитектура -> ARCHITECTURE.md
   • продуктовое поведение -> docs/product-specs/
   • дизайн-обоснование -> docs/design-docs/
   • состояние исполнения -> docs/exec-plans/
   • повторяющиеся внешние ссылки -> docs/references/
   • ожидания по качеству или надёжности -> docs/QUALITY_SCORE.md или docs/RELIABILITY.md
4. Заменяйте размытые формулировки операционно полезными.
5. Удаляйте или помечайте как deprecated устаревшие копии, чтобы в репозитории сохранялась одна обнаруживаемая истина.

Правила хорошего кодирования

• Пишите ради обнаруживаемости, а не литературной полноты.
• Предпочитайте короткие документы с понятными именами файлов.
• Связывайте родственные артефакты между собой.
• Храните долговечные правила, а не транскрипты встреч.
• Обновляйте репозиторий в той же сессии, в которой принято решение.

Definition Of Done

• Свежий агент может обнаружить нужное правило, не спрашивая человека.
• Один и тот же факт не разбросан по нескольким противоречивым файлам.
• Новый артефакт живёт рядом с кодом или процессом, которым он управляет.