Перейти к основному содержимому

Реорганизация AI-документации — План реализации

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Перенести AI-документацию из .claude/docs/ в .docs/ с иерархической навигацией INDEX -> глава -> страница, используя прокси-страницы для документации рядом с кодом.

Architecture: Единая точка входа .docs/INDEX.md ведет к главам (INDEX.md внутри подпапок). Полноценные главы содержат контент в .docs/. Прокси-главы ссылаются на файлы, живущие рядом с кодом (api/*.md, web/*/README.md).

Tech Stack: Markdown, git mv, bash

Spec: docs/superpowers/specs/2026-04-07-docs-reorganization-design.md

Task 1: Создать целевые директории​

Files:

  • Create: .docs/subsystems/, .docs/workflows/, .docs/reference/, .docs/tasks/, .docs/api/, .docs/web/

  • Step 1: Создать директории

cd c:/Projects/it
mkdir -p .docs/subsystems .docs/workflows .docs/reference .docs/tasks .docs/api .docs/web
  • Step 2: Проверить результат
ls -d .docs/*/

Expected: subsystems/, workflows/, reference/, tasks/, api/, web/

Task 2: Переместить подсистемы из .docs/projects/subsystems/ в .docs/subsystems/​

Files:

  • Move: .docs/projects/subsystems/* -> .docs/subsystems/*

  • Step 1: Переместить файлы подсистем

cd c:/Projects/it
# Файлы верхнего уровня
git mv .docs/projects/subsystems/automation.md .docs/subsystems/automation.md
git mv .docs/projects/subsystems/logins.md .docs/subsystems/logins.md
git mv .docs/projects/subsystems/mcp.md .docs/subsystems/mcp.md
git mv .docs/projects/subsystems/project-reviews.md .docs/subsystems/project-reviews.md
git mv .docs/projects/subsystems/projects.md .docs/subsystems/projects.md
git mv .docs/projects/subsystems/sla.md .docs/subsystems/sla.md
git mv .docs/projects/subsystems/sls.md .docs/subsystems/sls.md
git mv .docs/projects/subsystems/ssl.md .docs/subsystems/ssl.md
git mv .docs/projects/subsystems/task-ratings.md .docs/subsystems/task-ratings.md
git mv .docs/projects/subsystems/unit-testing.md .docs/subsystems/unit-testing.md
git mv .docs/projects/subsystems/update-it.md .docs/subsystems/update-it.md
  • Step 2: Переместить поддиректории
cd c:/Projects/it
# ssl/
mkdir -p .docs/subsystems/ssl
git mv .docs/projects/subsystems/ssl/mail.md .docs/subsystems/ssl/mail.md
git mv .docs/projects/subsystems/ssl/template-messages.md .docs/subsystems/ssl/template-messages.md

# unit-testing/
mkdir -p .docs/subsystems/unit-testing
git mv .docs/projects/subsystems/unit-testing/assertions.md .docs/subsystems/unit-testing/assertions.md
git mv .docs/projects/subsystems/unit-testing/mocking.md .docs/subsystems/unit-testing/mocking.md
git mv .docs/projects/subsystems/unit-testing/predicates.md .docs/subsystems/unit-testing/predicates.md
git mv .docs/projects/subsystems/unit-testing/queries.md .docs/subsystems/unit-testing/queries.md
git mv .docs/projects/subsystems/unit-testing/registration.md .docs/subsystems/unit-testing/registration.md
git mv .docs/projects/subsystems/unit-testing/sla-tests.md .docs/subsystems/unit-testing/sla-tests.md
git mv .docs/projects/subsystems/unit-testing/test-data.md .docs/subsystems/unit-testing/test-data.md

# parser/
mkdir -p .docs/subsystems/parser
git mv .docs/projects/subsystems/parser/INDEX.md .docs/subsystems/parser/INDEX.md
git mv .docs/projects/subsystems/parser/ARCHITECTURE.md .docs/subsystems/parser/architecture.md
git mv .docs/projects/subsystems/parser/METADATA.md .docs/subsystems/parser/metadata.md
git mv .docs/projects/subsystems/parser/MODULES.md .docs/subsystems/parser/modules.md
git mv .docs/projects/subsystems/parser/ONESCRIPT.md .docs/subsystems/parser/onescript.md
git mv .docs/projects/subsystems/parser/PARSER.md .docs/subsystems/parser/parser.md
git mv .docs/projects/subsystems/parser/PATTERNS.md .docs/subsystems/parser/patterns.md
git mv .docs/projects/subsystems/parser/TESTS.md .docs/subsystems/parser/tests.md
git mv .docs/projects/subsystems/parser/WORKFLOW.md .docs/subsystems/parser/workflow.md
  • Step 3: Проверить результат
find .docs/subsystems/ -name "*.md" | sort

Expected: 29 файлов в .docs/subsystems/

  • Step 4: Commit
git commit -m "refactor: перенос подсистем из .docs/projects/subsystems/ в .docs/subsystems/"

Task 3: Переместить workflows и reference из .docs/projects/​

Files:

  • Move: .docs/projects/workflows/* -> .docs/workflows/*

  • Move: .docs/projects/*.md -> .docs/reference/*

  • Move: .docs/projects/integration-contracts/tasks-batch.md -> .docs/reference/tasks-batch.md

  • Step 1: Переместить workflows

cd c:/Projects/it
git mv .docs/projects/workflows/rest-api.md .docs/workflows/rest-api.md
git mv .docs/projects/workflows/parser.md .docs/workflows/parser.md
  • Step 2: Переместить reference файлы
cd c:/Projects/it
git mv .docs/projects/http-connector.md .docs/reference/http-connector.md
git mv .docs/projects/functional-options-architecture.md .docs/reference/functional-options.md
git mv .docs/projects/project.md .docs/reference/project.md
git mv .docs/projects/integration-contracts/tasks-batch.md .docs/reference/tasks-batch.md
  • Step 3: Проверить, что .docs/projects/ пуста
find .docs/projects/ -name "*.md" 2>/dev/null

Expected: пустой вывод

  • Step 4: Удалить пустую директорию
rm -rf .docs/projects/
  • Step 5: Commit
git commit -m "refactor: перенос workflows и reference, удаление .docs/projects/"

Task 4: Перенести оставшиеся файлы из .claude/docs/​

Files:

  • Move: .claude/docs/tasks-common.md -> .docs/tasks/common.md

  • Move: .claude/docs/tasks-autonomous.md -> .docs/tasks/autonomous.md

  • Move: .claude/docs/tasks-interactive.md -> .docs/tasks/interactive.md

  • Move: .claude/docs/mcp-requirements.md -> .docs/reference/mcp-requirements.md

  • Move: .claude/docs/1c-query-optimization.md -> .docs/reference/query-optimization.md

  • Move: .claude/docs/docs-tags.md -> .claude/rules/docs-tags.md

  • Delete: .claude/docs/navigation.md

  • Step 1: Переместить tasks

cd c:/Projects/it
git mv .claude/docs/tasks-common.md .docs/tasks/common.md
git mv .claude/docs/tasks-autonomous.md .docs/tasks/autonomous.md
git mv .claude/docs/tasks-interactive.md .docs/tasks/interactive.md
  • Step 2: Переместить reference
cd c:/Projects/it
git mv .claude/docs/mcp-requirements.md .docs/reference/mcp-requirements.md
git mv .claude/docs/1c-query-optimization.md .docs/reference/query-optimization.md
  • Step 3: Переместить docs-tags в rules
cd c:/Projects/it
git mv .claude/docs/docs-tags.md .claude/rules/docs-tags.md
  • Step 4: Удалить navigation.md
cd c:/Projects/it
git rm .claude/docs/navigation.md
  • Step 5: Проверить, что .claude/docs/ пуста
ls .claude/docs/

Expected: пустой вывод или ошибка (директория не существует)

  • Step 6: Удалить пустую директорию
rmdir .claude/docs/ 2>/dev/null; echo "done"
  • Step 7: Commit
git commit -m "refactor: перенос файлов из .claude/docs/ в .docs/, удаление .claude/docs/"

Task 5: Создать корневой .docs/INDEX.md​

Files:

  • Create: .docs/INDEX.md

  • Step 1: Создать файл

# Документация проекта

Техническая документация для 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-редактор, общие стили
  • Step 2: Проверить
cat .docs/INDEX.md
  • Step 3: Commit
git add .docs/INDEX.md && git commit -m "docs: корневой INDEX.md"

Task 6: Создать INDEX.md для главы subsystems​

Files:

  • Create: .docs/subsystems/INDEX.md

  • Step 1: Создать файл

# Подсистемы 1С

Архитектура и структуры данных подсистем конфигурации.

## Страницы

- [Автоматизация](automation.md) — правила событий, триггеры, условия
- [Логины и пароли](logins.md) — карта объектов, структура данных, точки входа
- [MCP](mcp.md) — Model Context Protocol, архитектура, Node.js-прокси
- [Обзоры проектов](project-reviews.md) — единая точка входа, регистр истории, документ обзора
- [Проекты](projects.md) — управление проектами и задачами
- [SLA](sla.md) — соглашения об уровне сервиса
- [СЛС](sls.md) — система лицензирования Софтонит
- [БСП](ssl.md) — библиотека стандартных подсистем
- [Оценки заданий](task-ratings.md) — хранение, видимость, права, каналы установки
- [Юнит-тестирование](unit-testing.md) — YAXUnit, правила написания тестов
- [Обновление](update-it.md) — механизм обновления конфигурации
- [Парсер Docsinum](parser/INDEX.md) — архитектура парсера базы знаний
  • Step 2: Commit
git add .docs/subsystems/INDEX.md && git commit -m "docs: INDEX.md для главы subsystems"

Task 7: Создать INDEX.md для главы workflows​

Files:

  • Create: .docs/workflows/INDEX.md

  • Step 1: Создать файл

# Рабочие процессы

Пошаговые workflow для типовых задач разработки.

## Страницы

- [Изменение REST API](rest-api.md) — порядок изменений API: OpenAPI, 1С, тесты
- [Изменение парсера Docsinum](parser.md) — правки парсера, тесты, синхронизация
  • Step 2: Commit
git add .docs/workflows/INDEX.md && git commit -m "docs: INDEX.md для главы workflows"

Task 8: Создать INDEX.md для главы reference​

Files:

  • Create: .docs/reference/INDEX.md

  • Step 1: Создать файл

# Справочники

Справочная информация по инструментам, архитектуре и интеграциям.

## Страницы

- [HTTPКоннектор](http-connector.md) — HTTP-клиент конфигурации, замена HTTPСоединение
- [Оптимизация запросов](query-optimization.md) — правила оптимизации запросов 1С
- [MCP-требования](mcp-requirements.md) — требования к работе с MCP-серверами и EDT
- [Функциональные опции](functional-options.md) — трехуровневая цепочка, проектные флаги, редакции
- [Контекст проекта](project.md) — описание проекта, технологический стек
- [Batch tasks API](tasks-batch.md) — контракт пакетной работы с задачами
  • Step 2: Commit
git add .docs/reference/INDEX.md && git commit -m "docs: INDEX.md для главы reference"

Task 9: Создать INDEX.md для главы tasks​

Files:

  • Create: .docs/tasks/INDEX.md

  • Step 1: Создать файл

# Работа с задачами

Правила работы AI-агента с MCP tracker.

## Страницы

- [Общие правила](common.md) — главное правило, режимы работы, жизненный цикл задачи
- [Автономный режим](autonomous.md) — работа без участия пользователя, оркестратор
- [Интерактивный режим](interactive.md) — работа с пользователем, диалоговый режим
  • Step 2: Commit
git add .docs/tasks/INDEX.md && git commit -m "docs: INDEX.md для главы tasks"

Task 10: Создать прокси-главу .docs/api/INDEX.md​

Files:

  • Create: .docs/api/INDEX.md

  • Step 1: Создать файл

# REST API

Документация REST API. Исходники: `api/`.

> При добавлении нового .md файла в `api/` — добавь строку сюда.

## Страницы

- [Архитектура](../../api/ARCHITECTURE.md) — модули 1С, схема обработки запросов
- [Пагинация](../../api/PAGINATION.md) — offset/limit/with_total, формат ответа
- [Фильтрация](../../api/FILTERS.md) — параметр filter, операторы сравнения, логические операторы
- [Сортировка](../../api/SORTING.md) — параметр order, стабильная пагинация
- [Поля](../../api/FIELDS.md) — параметр fields, выборка полей
- [Авторизация](../../api/AUTH.md) — HTTP Basic Auth, генерация токена
- [Ссылки](../../api/REFS.md) — формат ref_entity_UUID и enum_type_value
- [Методы](../../api/METHODS.md) — добавление методов API в 1С, ДанныеAPI()
- [Бинарные данные](../../api/BINARY.md) — передача файлов, HTTP-ответы с бинарным телом
- [Спецификация](../../api/SPEC-GUIDE.md) — обслуживание OpenAPI, шаблоны, чек-лист
- [Swagger](../../api/SWAGGER.md) — workflow OpenAPI, команды redocly
- [Маппинг](../../api/ENDPOINT-MAP.md) — endpoint <-> код 1С, алгоритмы изменений
- [Тестирование](../../api/TESTING.md) — тестирование API, test_api.py
- [README](../../api/README.md) — workflow OpenAPI, lint, bundle, preview
  • Step 2: Commit
git add .docs/api/INDEX.md && git commit -m "docs: прокси-глава api/INDEX.md"

Task 11: Создать прокси-главу .docs/web/INDEX.md​

Files:

  • Create: .docs/web/INDEX.md

  • Step 1: Создать файл

# Веб-компоненты

Веб-проекты конфигурации. Исходники: `web/`. Monorepo на turborepo, TypeScript/Node.js 22.

> При добавлении нового README.md в `web/*/` — добавь строку сюда.

## Страницы

- [Панель задания](../../web/task/README.md) — HTML-макет задания, стили, сборка в шаблоны 1С
- [Markdown-редактор](../../web/nano-editor/README.md) — WYSIWYG-редактор для описаний и комментариев
  • Step 2: Commit
git add .docs/web/INDEX.md && git commit -m "docs: прокси-глава web/INDEX.md"

Task 12: Обновить CLAUDE.md​

Files:

  • Modify: CLAUDE.md

  • Step 1: Обновить путь к project.md в секции "Main files"

Заменить строку 5:

Read `.claude/docs/project.md` for project context and tech stack.

На:

Read `.docs/reference/project.md` for project context and tech stack.
  • Step 2: Заменить секцию "On-demand references"

Удалить строки 22-37 (от ## On-demand references до строки с Read .claude/templates/new-api-endpoint.md).

Заменить на:

## On-demand references (read only when relevant)

Read `.docs/INDEX.md` for AI documentation navigation — subsystems, workflows, reference, tasks, API, web.
Читай корневой индекс, затем INDEX.md нужной главы, затем страницу.
Не загружай все страницы главы — только те, что нужны для текущей задачи.

Read `.claude/rules/docs-tags.md` when creating or editing documentation in docs/
Read `.claude/templates/new-api-endpoint.md` when creating a new REST API endpoint
  • Step 3: Обновить секцию "ALWAYS"

Заменить строку:

- Перед правкой REST API прочитать `api/INDEX.md` и `api/ENDPOINT-MAP.md`

На:

- Перед правкой REST API прочитать `.docs/api/INDEX.md`, затем нужные страницы
  • Step 4: Обновить секцию "Documentation"

Заменить:

## Documentation

Документацию генерировать ТОЛЬКО по явному запросу пользователя.
НЕ генерировать документацию автоматически при завершении доработок.
Техническая: `.claude/docs/`, пользовательская: `docs/`.

На:

## Documentation

Документацию генерировать ТОЛЬКО по явному запросу пользователя.
НЕ генерировать документацию автоматически при завершении доработок.
Техническая (AI): `.docs/`, пользовательская: `docs/`.
  • Step 5: Обновить таблицу "Auto-loaded rules"

Добавить строку в таблицу:

| `docs-rules.md` | Правила самодокументирования .docs/ |
  • Step 6: Проверить, что не осталось ссылок на .claude/docs/
grep -n "\.claude/docs/" CLAUDE.md

Expected: пустой вывод (нет совпадений)

  • Step 7: Commit
git add CLAUDE.md && git commit -m "docs: обновление CLAUDE.md — новые пути .docs/"

Task 13: Создать правило самодокументирования .claude/rules/docs-rules.md​

Files:

  • Create: .claude/rules/docs-rules.md

  • Step 1: Создать файл

## Правила документации .docs/

### Навигация

Техническая AI-документация: `.docs/INDEX.md`.
Навигация: корневой INDEX -> INDEX.md главы -> страница.
Не загружай все страницы главы — только нужные для текущей задачи.

### Когда обновлять INDEX.md

- Добавил новый .md файл в `api/`, `web/*/` — добавь строку в соответствующий `.docs/*/INDEX.md`
- Удалил .md файл — убери строку из INDEX.md
- Создал новую подсистему/модуль и написал документацию в `.docs/` — добавь строку в INDEX.md главы
- Переименовал файл — обнови ссылку в INDEX.md

### Когда НЕ обновлять INDEX.md

- Изменил содержимое существующей страницы — INDEX.md не трогай
- Правки кода без изменения документации — ничего не делай

### Формат строки в INDEX.md

`- [Название](путь) — краткое описание до ~80 символов`
  • Step 2: Commit
git add .claude/rules/docs-rules.md && git commit -m "docs: правило самодокументирования .docs/"

Task 14: Обновить внутренние ссылки в перенесенных файлах​

Files:

  • Modify: .docs/subsystems/ssl.md (ссылка на ssl/)

  • Modify: .docs/workflows/parser.md (ссылка на subsystems/parser/)

  • Modify: .docs/subsystems/parser/INDEX.md (заголовки файлов в нижнем регистре)

  • Step 1: Проверить ссылки в ssl.md

grep -n "\.\./\|\.claude/docs/" .docs/subsystems/ssl.md

Если есть ссылки вида .claude/docs/subsystems/ssl/ — заменить на ssl/ (относительный путь теперь верный).

  • Step 2: Проверить ссылки в workflows/parser.md
grep -n "\.\./\|\.claude/docs/" .docs/workflows/parser.md

Ссылка ../subsystems/parser/WORKFLOW.md должна стать ../subsystems/parser/workflow.md (файл переименован в нижний регистр).

  • Step 3: Обновить parser/INDEX.md

В файле .docs/subsystems/parser/INDEX.md обновить ссылки на файлы (переименованы в нижний регистр):

  • ARCHITECTURE.md -> architecture.md

  • METADATA.md -> metadata.md

  • MODULES.md -> modules.md

  • PARSER.md -> parser.md

  • ONESCRIPT.md -> onescript.md

  • TESTS.md -> tests.md

  • WORKFLOW.md -> workflow.md

  • PATTERNS.md -> patterns.md

  • Step 4: Поиск других битых ссылок

grep -rn "\.claude/docs/" .docs/ --include="*.md"

Expected: пустой вывод. Если есть совпадения — исправить на новые пути.

  • Step 5: Commit
git add -A .docs/ && git commit -m "fix: обновление внутренних ссылок после переноса"

Task 15: Финальная проверка​

  • Step 1: Проверить структуру .docs/
find .docs/ -name "*.md" | sort

Expected: ~45 файлов, без поддиректории projects/.

  • Step 2: Проверить, что .claude/docs/ не существует
ls .claude/docs/ 2>/dev/null || echo "OK: directory removed"

Expected: OK: directory removed

  • Step 3: Проверить, что нет ссылок на старые пути
grep -rn "\.claude/docs/" CLAUDE.md .claude/rules/ .docs/ --include="*.md"

Expected: пустой вывод

  • Step 4: Проверить INDEX.md — все ссылки ведут на существующие файлы
# Проверка корневого INDEX
for f in subsystems/INDEX.md workflows/INDEX.md reference/INDEX.md tasks/INDEX.md api/INDEX.md web/INDEX.md; do
  test -f ".docs/$f" && echo "OK: $f" || echo "MISSING: $f"
done

Expected: все OK

  • Step 5: Проверить docs-tags.md в rules
test -f .claude/rules/docs-tags.md && echo "OK" || echo "MISSING"

Expected: OK