# Инструкция: как добавить запись в справочник

## Формат одной записи (шаблон)

```markdown
## [P0/P1/P2] Короткое название проблемы
**Симптом:** что происходит, как проявляется
**Причина:** root cause
**Решение:** что сделали / что нужно сделать
**Статус:** ✅ FIXED / ⚠️ OPEN / ❌ WORKAROUND / 🟡 PLATFORM
**Версия:** vX.Y.Z (в какой версии исправлено, если есть)
**Файлы:**
- `путь/к/файлу.go:номер_строки` — что там
**Источники:**
- `docs/50_history/NN_*.md` — ссылка на историю
- `HISTORY/...` — если описание в HISTORY/

## Пример заполнения

## [P0] POST 403 после DDoS-Guard
**Симптом:** terraform apply → HTTP 403 на POST запросах к ColdFusion API
**Причина:** DDoS-Guard блокирует запросы без User-Agent; %2F в URL ломает WAF
**Решение:**
1. `req.Header.Set("User-Agent", "Mozilla/5.0")` во всех HTTP-вызовах
2. `rawQuery := "endpoint=" + path` (без url.Values, чтобы не было %2F)
3. `TLSNextProto = make(map[string]func(...))` — отключить HTTP/2 ALPN
4. `transport.Proxy = nil` — не использовать HTTPS_PROXY
**Статус:** ⚠️ OPEN (User-Agent ✅ FIXED v5.0.75, POST всё ещё 403)
**Файлы:**
- `universal_rebuild/internal/core/client.go:865` — doRequest (User-Agent ✅)
- `universal_rebuild/internal/core/client.go:522` — FindExistingInstances (User-Agent ✅)
- `universal_rebuild/internal/core/client.go:597` — GetInstanceState (User-Agent ✅)
- `universal_rebuild/internal/core/client.go:644` — GetInstanceStateRaw (User-Agent ✅)
- `universal_rebuild/internal/resources_core/domain_collision.go:99` — коллизии доменов (User-Agent ✅)
- `devops/01_generate_yamls.sh` — urllib без User-Agent 🔴
**Источники:**
- `HISTORY/SONNET/0107.md`
- `HISTORY/2026-07-01_ddos_guard_403_and_registry_fix.md`
```

## Правила

1. **Каждый баг — одна запись.** Не группировать разные проблемы в одну.
2. **Симптом — конкретно:** что видит пользователь/агент (ошибка, код возврата, сообщение).
3. **Файлы — с номерами строк:** `universal_rebuild/internal/core/client.go:865` (без `L`).
4. **Статус — честно:** если не исправлено — ⚠️ OPEN.
5. **Ссылки на источники** — относительные пути от корня репы.
6. **Приоритет P0/P1/P2:**
   - **P0** — блокирует работу (apply падает, data loss)
   - **P1** — серьёзно мешает (wrong behaviour, needless calls)
   - **P2** — улучшение/cleanup

## Куда добавлять

| Тип записи | Файл |
|-----------|------|
| Новый баг (любой) | `01_BUGS_ALL.md` (в конец раздела по букве/категории) |
| Новый симптом | `02_BUGS_BY_SYMPTOM.md` |
| Новая категория | `03_BUGS_BY_CATEGORY.md` |
| Архитектурное решение | `04_ARCHITECTURE.md` |
| Новое состояние | `05_STATE_MATRIX.md` |
| Критичное для агентов | `06_TLDR_FOR_AGENTS.md` |

## После добавления

1. Проверить что ссылки валидны (файлы существуют, строки примерно верны)
2. Обновить `INDEX.md` — алфавитный указатель
3. `git add + git commit + git push`