---
name: architecture-research
description: "Используй этот скилл когда обсуждаете архитектурные решения, добавление нового функционала, выбор подходов. Триггеры: 'давай добавим', 'предлагаю реализовать', 'как лучше сделать', 'какой подход', 'архитектурное решение', 'новый функционал', 'лучшие практики', 'best practices', 'как реализовать', 'выбор подхода', 'архитектура', 'паттерн для'. НЕ для вопросов по 1С (используй 1c-doc-research). НЕ для общих tech-вопросов без привязки к фреймворку (используй tech-research)."
ultrathink: true
---

# Architecture Research — исследование для архитектурных решений

## Когда использовать

Когда обсуждаем архитектурные решения, добавление нового функционала в PDF Framework, выбор подхода к реализации. Отличия от других research-скиллов:

| Скилл | Когда |
|-------|-------|
| `1c-doc-research` | Вопросы про платформу 1С |
| `tech-research` | Общие вопросы по технологиям (RAG, embeddings, LangChain) |
| **`architecture-research`** | **Конкретные решения по нашему фреймворку**: что добавить, как реализовать, какой подход выбрать |

---

## 3-tier структура знаний

```
architecture-research/
├── cache/          # ФАКТЫ — объективные, переиспользуемые (бенчмарки, GitHub repos, документация)
│   ├── _index.json           # Индекс тем + keywords для быстрого поиска
│   └── <тема>.md             # Факты без выводов
├── adr/            # РЕШЕНИЯ — контекстные, версионируемые (ADR формат)
│   ├── _index.json           # Индекс решений + lifecycle
│   └── NNN-<название>.md     # Context → Decision → Consequences → Alternatives
└── SKILL.md        # ПРОЦЕДУРА — как проводить исследование (этот файл)
```

**Принцип разделения** (ADR-002):
- **cache/** — только объективные факты. Можно переиспользовать для другого решения
- **adr/** — субъективные решения с обоснованием. Привязаны к контексту фреймворка
- Каждый ADR ссылается на cache-файл через поле `research`

---

## 6 фаз исследования

### Фаза 0: Проверка кеша

Проверь `architecture-research/cache/_index.json` — есть ли уже исследование по теме.

Если есть — прочитай кешированный файл, используй как основу, дополни если нужно.

### Фаза 1: Локальная база знаний (docs/documentation/)

**ОБЯЗАТЕЛЬНАЯ ФАЗА.** Прежде чем предлагать решение — проверь что написано в документации.

```
D:\1С-Framework\docs\documentation\
├── Claude Code Docs/     → hooks, skills, MCP, subagents, plugins
├── Lang Chain Docs/      → LangChain, LangGraph, Deep Agents, integrations
├── Language Server Protocol/ → LSP спецификация
├── Протокол контекста модели/ → MCP спецификация, серверы, клиенты
└── Hooks + Skills + MCP.md  → обзорный документ
```

**Действия:**
1. `Glob` по `docs/documentation/**/*.md` — найди файлы, релевантные теме
2. `Read` найденные файлы — извлеки конкретные паттерны, API, примеры
3. Запиши что нашёл — это фундамент предложения

**Примеры поиска по темам:**

| Тема решения | Где искать |
|-------------|-----------|
| Агентная архитектура | `Lang Chain Docs/Deep Agents/`, `Lang Chain Docs/Lang Graph/` |
| Multi-agent | `Lang Chain Docs/Lang Chain/Расширенное использование/Многоагентный/` |
| Hooks/Skills | `Claude Code Docs/2. Создавайте с Claude Code/` |
| MCP интеграция | `Протокол контекста модели/Документация/` |
| RAG pipeline | `Lang Chain Docs/Учиться/LangGraph/Создайте собственный RAG-агент*.md` |
| Memory/State | `Lang Chain Docs/Lang Graph/Возможности/Память.md`, `Упорство.md` |
| Streaming | `Lang Chain Docs/Lang Chain/Основные компоненты/Стриминг/` |
| Инструменты | `Lang Chain Docs/Интеграции LangChain/Интеграция по компонентам/` |

### Фаза 2: Лучшие практики (Web + GitHub)

**ОБЯЗАТЕЛЬНАЯ ФАЗА.** Ищи актуальные best practices в интернете.

**Действия:**
1. `WebSearch` — официальная документация + best practices 2025-2026
2. `WebSearch` — GitHub repos с высоким рейтингом (stars > 100)
3. `WebSearch` — статьи и benchmarks (если есть сравнение подходов)

**Шаблон поисковых запросов:**
```
"{технология} best practices 2026"
"{технология} production patterns github"
"{технология} vs {альтернатива} benchmark"
"site:github.com {технология} {паттерн} stars:>100"
```

**Приоритет источников:**
1. Официальная документация (docs.anthropic.com, python.langchain.com, qdrant.tech)
2. GitHub repos от авторов библиотек
3. Рецензированные статьи (arxiv, blog posts от maintainers)
4. Community best practices (Stack Overflow, Reddit r/LangChain)

### Фаза 3: Синтез — предложение решения

**Объедини** локальные знания (Фаза 1) + web-практики (Фаза 2):

1. Что говорит наша документация
2. Что рекомендуют авторы библиотек
3. Какие паттерны используют production-проекты на GitHub
4. Мой анализ: что подходит конкретно нашему фреймворку

**Формат предложения:**

```markdown
## Предложение: [название]

### Основание (из docs/documentation/)
- [Что нашли в локальной документации]
- Ссылка: [файл](docs/documentation/path/to/file.md)

### Best Practices (из web)
- [Что рекомендуют]
- Источник: [URL]

### Рекомендация для нашего фреймворка
- [Конкретное предложение с обоснованием]
- Почему этот подход лучше альтернатив
- Что нужно изменить в нашем коде

### Риски и альтернативы
- [Что может пойти не так]
- [Запасной вариант]
```

### Фаза 4: Атрибуция

**Каждый факт** в предложении должен быть атрибутирован:
- `[docs]` — из `docs/documentation/`
- `[web]` — из web-поиска (с URL)
- `[exp]` — из нашего опыта (MEMORY.md)
- `[own]` — моя экспертная оценка

### Фаза 5: Кеширование фактов

Сохрани **только факты** в `architecture-research/cache/<тема>.md`:

```markdown
# [Тема исследования]

**Дата:** YYYY-MM-DD
**Статус:** актуально | устарело
**Теги:** [keyword1, keyword2]

## Из документации
[Что нашли в docs/documentation/]

## Из интернета
[Best practices с URL, бенчмарки, GitHub repos]

## Ключевые источники
[Все URL с описанием]
```

**ВАЖНО:** НЕ включай в кеш выводы, решения, сравнения с "нашим фреймворком". Кеш = объективные данные, переиспользуемые для любого решения.

Обнови `cache/_index.json`:
```json
{
  "topics": [
    {
      "file": "<тема>.md",
      "keywords": ["keyword1", "keyword2"],
      "last_verified": "YYYY-MM-DD"
    }
  ]
}
```

### Фаза 6: Фиксация решения (ADR)

Если исследование привело к архитектурному решению — создай ADR:

```markdown
# ADR-NNN: [Название решения]

**Дата:** YYYY-MM-DD
**Статус:** proposed | accepted | superseded | deprecated
**Исследование:** [ссылка на cache-файл]

## Контекст
[Почему возник вопрос]

## Решение
[Что решили + обоснование с атрибуцией [docs/web/exp/own]]

## Последствия
### Положительные / Отрицательные

## Альтернативы
[Что рассматривали и почему отклонили]

## Связанные файлы
[Какие файлы фреймворка затрагивает]
```

Обнови `adr/_index.json` — добавь запись с lifecycle-статусом.

**Когда НЕ нужен ADR:**
- Чисто информационное исследование (нет решения)
- Тактическое решение на 1 коммит (не архитектурное)

---

## Критерии домена

| Критерий | architecture-research | tech-research |
|----------|----------------------|---------------|
| Привязка к нашему фреймворку | **ДА** — решения для PDF Framework | НЕТ — общие знания |
| Проверка docs/documentation/ | **ОБЯЗАТЕЛЬНО** | Не обязательно |
| Результат | Конкретное предложение | Обзор технологии |
| Кеш | Решения + обоснования | Факты + примеры |