architect/KNOWLEDGE.md

KNOWLEDGE — Библиотека критических открытий

Назначение: Сюда записываются факты о системе, которые не очевидны из кода, но критически влияют на поведение.

Когда записывать: Только с разрешения оператора. Предложить — при обнаружении; записать — после "да".

Уровни:
- 🔴 Критическое — без этого знания система работает неправильно незаметно
- 🟡 Важное — влияет на поведение, есть обходной путь
- 🟢 Полезное — ускоряет диагностику, не обязательно

Формат:

## [KN-XXX] Название
Уровень / Открыто / Симптом / Проверка / Решение / Ссылка

[KN-001] Конфликт Output Styles vs Base System Prompt

Уровень: 🔴 Критическое
Открыто: 2026-02-19
Решено: 2026-03-27
Документ: architect/arh/analysis/2026-02-19-instruction-conflict/SUMMARY.md

Суть:
Claude Code имеет слоёвую архитектуру инструкций. При keep-coding-instructions: true наши Output Styles ДОБАВЛЯЮТСЯ к базовым инструкциям Anthropic, а не заменяют их. Базовые инструкции (Layer 1) имеют наивысший приоритет и побеждают в конфликтах.

Слои (по приоритету):

LAYER 1: Base System Prompt (Anthropic)         ← ВЫСШИЙ, всегда побеждает (если true)
LAYER 2: --append-system-prompt                 ← теряется после compaction
LAYER 3: Output Styles (.claude/output-styles/) ← выживает compaction
LAYER 4: SessionStart hook (additionalContext)  ← напоминание, не приказ
LAYER 5: CLAUDE.md (claudeMd)                   ← САМЫЙ НИЗКИЙ

Механизм провала (при keep-coding-instructions: true):

Base: "NEVER create files unless absolutely necessary"
  + SafeDialog: "показывай план, жди подтверждения"
  = Base побеждает → Claude создаёт файлы БЕЗ подтверждения

Решение: keep-coding-instructions: false

keep-coding-instructions: false
  = Output Style ПОЛНОСТЬЮ ЗАМЕНЯЕТ базовый системный промпт
  = Наши правила становятся системными инструкциями (Layer 1)
  = Base prompt Anthropic отключается

Выживаемость при разных состояниях сессии:

Состояние CLAUDE.md (L5) Output Style (L3) Hook (L4)
Старт новой сессии ✅ Да ✅ Да ✅ Да (если cd WORKSPACE)
Compaction (сжатие контекста) ✅ Да ✅ Да (файлы, не история) ❌ Нет (не повторяется)
Restart (claude --resume) ✅ Да ✅ Да ⚠️ Только если cd WORKSPACE

Вывод: Output Styles выживают везде. С false — наши правила всегда активны.

Симптом (как понять что сломалось):
- Claude выполняет L3-L4 операции без запроса подтверждения
- Claude создаёт файлы сразу, не показывая план
- Claude задаёт вопросы "А или Б?" вместо таблицы с рекомендацией
- Claude игнорирует протоколы уровней L1-L4

Проверка:

Написать: "создай файл test.md"
✅ Норма: Claude показывает план и ждёт "ок"
❌ Сломано: Claude создаёт файл сразу

Статус: ✅ ИСПРАВЛЕНО 2026-03-27 — SafeDialog.md переписан с keep-coding-instructions: false
Решение: Изменить на keep-coding-instructions: false + переписать styles с явными OVERRIDES

[KN-002] Хук SessionStart требует cd в WORKSPACE

Уровень: 🟡 Важное
Открыто: 2026-03-25
Документ: architect/standards/HOOKS_SESSION.md

Суть:
Claude Code ищет .claude/settings.json (и хуки внутри него) относительно текущей рабочей директории (CWD) при запуске. Если claude --resume вызван не из /opt/claude-workspace, хук SessionStart не срабатывает — CLAUDE.md не инжектируется в сессию.

Симптом:
- Claude не знает правил после resume сессии
- CLAUDE.md не применяется (нет ответа "HOOK OK" при старте)
- Инструкции работают после start (новая сессия), но теряются при session (resume)

Проверка:

grep "WORKSPACE\|cd /opt" /usr/local/bin/session
# Должно быть: cd "$WORKSPACE" перед каждым claude --resume
# Если пусто — хук не сработает при прямом вызове session

Статус: ⚠️ НЕ ИСПРАВЛЕНО — cd "$WORKSPACE" отсутствует в system/scripts/session
Правило: Любой скрипт с claude --resume обязан сначала cd /opt/claude-workspace
Обходной путь: Всегда запускать через start (он делает cd сам)

[KN-003] CLAUDE.md — контекст, не системная инструкция

Уровень: 🟢 Полезное
Открыто: 2026-02-19

Суть:
CLAUDE.md читается как claudeMd (Layer 5 — самый низкий приоритет). Это "напоминание" в контексте, а НЕ системная инструкция. Любое правило в CLAUDE.md может быть перебито базовым system prompt Anthropic. Попытки добавить "OVERRIDE" или "КРИТИЧНО" в CLAUDE.md не работают — они игнорируются.

Вывод для будущего:
- Строгие правила → писать в Output Styles (Layer 3) с keep-coding-instructions: false
- CLAUDE.md → только для контекста, справочников, ссылок, не для поведенческих правил

[KN-004] Риски Output Style — когда может не сработать

Уровень: 🟡 Важное
Открыто: 2026-03-27

Суть:
Output Style активен только если пользователь выбрал его через /style. Если стиль не выбран — работает только базовый промпт. keep-coding-instructions: false помогает только когда стиль АКТИВЕН.

Сценарии отказа:

Сценарий Поведение Риск
Новая сессия без /style SafeDialog Базовый промпт, без наших правил 🔴 Высокий
/style Default выбран вместо SafeDialog Default правила 🟡 Средний
Compaction Стиль выживает (файлы не удаляются) ✅ Нет риска
claude --resume Стиль выживает ✅ Нет риска

Защита (layered fallback):

УРОВЕНЬ 1: SafeDialog.md (keep-coding-instructions: false) ← лучший вариант
УРОВЕНЬ 2: Default.md (keep-coding-instructions: false)    ← если wrong style
УРОВЕНЬ 3: CLAUDE.md раздел "КРИТИЧЕСКИЕ ПРАВИЛА"          ← если вообще нет стиля

Правило:
- Все output styles должны иметь keep-coding-instructions: false
- В CLAUDE.md должен быть блок критических правил как fallback
- При новой сессии в новом проекте — сразу /style SafeDialog

Последнее обновление: 2026-03-27