Реорганизация AI-документации: прокси-страницы
Цель
Перенести AI-документацию из .claude/docs/ в .docs/ с иерархической навигацией INDEX -> глава -> страница. LLM загружает только нужные файлы, не перегружая контекст. Документация, живущая рядом с кодом (api/*.md, web/*/README.md), остается на месте.
Подход: федерация с прокси-страницами
.docs/ — единственная точка входа для LLM. Для документации, которая живет рядом с кодом, создаются легковесные прокси-страницы (10-15 строк со ссылками). Реальный контент не дублируется.
Файловая структура
.docs/
INDEX.md # Корневой индекс (оглавление)
# Полноценные главы (контент внутри .docs/)
subsystems/
INDEX.md
automation.md
logins.md
mcp.md
sla.md
sls.md
projects.md
project-reviews.md
task-ratings.md
ssl.md
ssl/
mail.md
template-messages.md
unit-testing.md
unit-testing/
assertions.md
mocking.md
predicates.md
queries.md
registration.md
sla-tests.md
test-data.md
update-it.md
parser/
INDEX.md
architecture.md
metadata.md
modules.md
onescript.md
parser.md
patterns.md
tests.md
workflow.md
workflows/
INDEX.md
rest-api.md
parser.md
reference/
INDEX.md
http-connector.md
query-optimization.md
mcp-requirements.md
functional-options.md
project.md
tasks-batch.md
project.md
tasks/
INDEX.md
common.md
autonomous.md
interactive.md
# Прокси-главы (контент живет рядом с кодом)
api/
INDEX.md # Прокси: ссылки на api/*.md
web/
INDEX.md # Прокси: ссылки на web/task/, web/nano-editor/
Формат INDEX.md
Корневой INDEX.md
# Документация проекта
Техническая документация для AI-агентов. Читай INDEX.md нужной главы, затем переходи к странице.
## Главы
- [Подсистемы 1С](subsystems/INDEX.md) — архитектура, структуры данных, бизнес-логика подсистем
- [Рабочие процессы](workflows/INDEX.md) — пошаговые workflow для типовых задач
- [Справочники](reference/INDEX.md) — HTTPКоннектор, оптимизация запросов, MCP, функциональные опции
- [Работа с задачами](tasks/INDEX.md) — правила работы AI-агента с MCP tracker
- [REST API](api/INDEX.md) — архитектура, эндпоинты, спецификация OpenAPI
- [Веб-компоненты](web/INDEX.md) — панель задания, Markdown-редактор, общие стили
INDEX.md полноценной главы
# Подсистемы 1С
Архитектура и структуры данных подсистем конфигурации.
## Страницы
- [Автоматизация](automation.md) — правила событий, триггеры, условия
- [SLA](sla.md) — соглашения об уровне сервиса
- [Проекты](projects.md) — управление проектами и задачами
- [Парсер Docsinum](parser/INDEX.md) — архитектура парсера базы знаний
- ...
INDEX.md прокси-главы
# REST API
Документация REST API. Исходники: `api/`.
> При добавлении нового .md файла в `api/` — добавь строку сюда.
## Страницы
- [Архитектура](../../api/ARCHITECTURE.md) — модули 1С, схема обработки запросов
- [Пагинация](../../api/PAGINATION.md) — offset/limit/with_total
- [Фильтрация](../../api/FILTERS.md) — параметр filter, операторы
- ...
Формат строки
- [Название](путь) — краткое описание до ~80 символов
Описание дает LLM достаточно контекста для решения: загружать страницу или нет.
Интеграция с CLAUDE.md
Замена секции "On-demand references"
Текущие строки Read .claude/docs/... удаляются. Заменяются на:
## Documentation
Техническая документация для AI: `.docs/INDEX.md`.
Читай корневой индекс, затем INDEX.md нужной главы, затем страницу.
Не загружай все страницы главы — только те, что нужны для текущей задачи.
Пользовательская документация (Docusaurus): `docs/`.
Правила тегирования: `.claude/rules/docs-tags.md`.
Правило самодокументирования
Добавляется в .claude/rules/common-rules.md или отдельный .claude/rules/docs-rules.md:
## Правила документации .docs/
### Когда обновлять
- Добавил новый .md файл в `api/`, `web/*/` — добавь строку в соответствующий `.docs/*/INDEX.md`
- Удалил .md файл — убери строку из INDEX.md
- Создал новую подсистему/модуль и написал документацию в `.docs/` — добавь строку в INDEX.md главы
- Переименовал файл — обнови ссылку в INDEX.md
### Когда НЕ обновлять
- Изменил содержимое существующей страницы — INDEX.md не трогай
- Правки кода без изменения документации — ничего не делай
### Формат строки в INDEX.md
- [Название](путь) — краткое описание до ~80 символов
Миграция
Из .claude/docs/ (7 файлов)
| Файл | Куда |
|---|---|
navigation.md | Удаляется (заменен .docs/INDEX.md) |
tasks-common.md | .docs/tasks/common.md |
tasks-autonomous.md | .docs/tasks/autonomous.md |
tasks-interactive.md | .docs/tasks/interactive.md |
mcp-requirements.md | .docs/reference/mcp-requirements.md |
1c-query-optimization.md | .docs/reference/query-optimization.md |
docs-tags.md | .claude/rules/docs-tags.md |
Из .docs/projects/ (35 файлов)
Убрать лишний уровень projects/:
| Было | Стало |
|---|---|
.docs/projects/subsystems/* | .docs/subsystems/* |
.docs/projects/workflows/* | .docs/workflows/* |
.docs/projects/http-connector.md | .docs/reference/http-connector.md |
.docs/projects/functional-options-architecture.md | .docs/reference/functional-options.md |
.docs/projects/project.md | .docs/reference/project.md |
.docs/projects/integration-contracts/tasks-batch.md | .docs/reference/tasks-batch.md |
Не переезжает
| Файл | Почему |
|---|---|
api/*.md | Остается на месте, прокси в .docs/api/INDEX.md |
web/task/README.md | Остается на месте, прокси в .docs/web/INDEX.md |
web/nano-editor/README.md | Остается на месте, прокси в .docs/web/INDEX.md |
.claude/rules/* | Правила, не документация |
docs/* | Пользовательская документация Docusaurus |
Итого после миграции
.claude/docs/— пустая, удаляется.docs/projects/— пустая, удаляется
Цикл работы LLM
Типовой сценарий (3 файла)
"Добавь пагинацию в API для объекта X":
.docs/INDEX.md— выбирает главу "REST API".docs/api/INDEX.md— выбирает "Пагинация"api/PAGINATION.md— получает контент
Кросс-доменный сценарий (4-5 файлов)
"Добавь новый эндпоинт API для подсистемы проектов":
.docs/INDEX.md— видит и API, и Подсистемы.docs/api/INDEX.md— Методы, Спецификация, Маппинг.docs/subsystems/INDEX.md— Проекты- Загружает 4-5 страниц из двух глав