> For the complete documentation index, see [llms.txt](https://docs.onerpa.ru/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.onerpa.ru/pi-dsh-1c/openspec-i-znaniya.md).

# OpenSpec и знания

## OpenSpec

Нетривиальная доработка начинается с change: proposal, specs, design и tasks. Агент правит код по выбранному change. Вопрос, мелкая правка и исследование идеи change не требуют.

Общие команды, которые грузят навык и делают ход агента:

| Команда                  | Что делает                                                       |
| ------------------------ | ---------------------------------------------------------------- |
| `/opsx-explore <тема>`   | Читает и обсуждает без реализации                                |
| `/opsx-propose <задача>` | Создаёт change и планирующие файлы, код не пишет                 |
| `/opsx-apply <change>`   | Делает согласованные задачи                                      |
| `/opsx-update <change>`  | Обновляет артефакты с проверкой revision                         |
| `/opsx-sync <change>`    | Переносит delta specs в основные specs, change остаётся активным |
| `/opsx-archive <change>` | Закрывает change после проверки задач и specs                    |

В Pi состояние change: `/openspec init`, список, `/openspec use <change>`, `/spec`, `/tasks`, `/tasks set <change> <id> done <revision> <доказательство>`.

Если изменение не выбрано, `/tasks` пишет по-русски, что открыть `/openspec` и выбрать изменение либо указать имя. Неверное имя тоже объясняется по-русски: от 1 до 96 символов, строчные латинские буквы, цифры, точка, дефис и подчёркивание, первый символ — буква или цифра. Пустой `openspec/config.yaml` означает обычные настройки и ошибкой не считается. Файлы в архиве изменений как конфигурация активного change не проверяются. Ошибка настоящего YAML показывается вместе с путём файла.

В DSH то же на панели «Изменения OpenSpec» и командой `/openspec1c`: `status`, `select`, `validate`, `task … done <revision> <evidence>`. Кнопка «В контекст» кладёт change в текущий разговор, «Проверить strict» гоняет проверку.

Propose и update останавливаются на плане. Archive не закрывает change с незавершёнными задачами. Писать артефакты можно в PLAN и BUILD. Менять код по change можно в BUILD.

### Тикеты

Change или основную спецификацию можно связать с тикетом Jira или другой системы учёта задач. Связи лежат в проекте, в `openspec/tickets.json`, источник списка тикетов — в `openspec/ticket-source.json`. Формат общий для Pi и DSH, файлы можно хранить в Git. Содержимое тикетов и учётные данные туда не пишутся, статус в Jira связь не меняет.

* `/opsx-propose ABC-123` или ссылка на тикет — создать change по тикету. Агент читает тикет через подключённый MCP или доступный веб-инструмент, при закрытом доступе просит текст.
* Pi: `/openspec ticket <changes/имя> <ключ или URL>` сохраняет связь, `-` вместо ключа удаляет её. `/openspec tickets` — открытые тикеты и настройка источника.
* DSH: «Связь с тикетом» в OpenSpec, панель Jira с кнопкой «OpenSpec по тикету», панель «Система учета задач» (Jira, Bitrix24 и YouTrack). См. [Дополнительные возможности DSH](https://docs.onerpa.ru/pages/ngmmddXs599PbBNgkPjw#%D1%82%D0%B8%D0%BA%D0%B5%D1%82%D1%8B-%D0%B8-jira).

## Знания

Факты и правила конкретной конфигурации лежат в `<проект>/.ai-rules/knowledge/` и коммитятся вместе с исходниками. Формат общий для Cursor, Pi и DSH. Агент читает слой инструментом `knowledge_1c` и получает только записи по теме, а не весь архив.

Ничего не становится активным само. Черновик активирует `/config apply` или `/learn approve` в BUILD.

| Действие                                        | Команда                                               |
| ----------------------------------------------- | ----------------------------------------------------- |
| Каркас каталогов, не затирая существующие файлы | `/config scaffold`                                    |
| Имя конфигурации и версия                       | `/config init <имя> :: <версия>`                      |
| Разобрать конфигурацию в черновик               | `/config analyze`                                     |
| Обновить знания после новой версии              | `/config update`                                      |
| Короткий факт                                   | `/learn <факт или правило>`                           |
| Знания из файла или URL                         | `/learn <путь или url>`                               |
| Правило проекта или конфигурации                | `/rule add project :: <тема> :: <правило>`            |
| Список, конфликты, отключение                   | `/rule list`, `/rule conflicts`, `/rule disable <id>` |

`/config scaffold` создаёт отсутствующие `docs/README.md` и `docs/techtask/README.md`. Уже лежащие файлы не перезаписываются.

Устаревший разбор не затирает более новый черновик. Если запись занята, в Pi есть `/learn retry` без нового хода модели.

## Уроки и правила поведения

`/lesson` сохраняет удачный или неудачный приём. Похожая задача позже получает несколько подходящих строк, без фонового хода модели.

`/retro` собирает предложения по сессии и сам файлы не пишет. `/evolve` кладёт кандидатов в очередь. В файл `LLM-RULES.md` попадает только то, что вы одобрили: в Pi это `/llm-rules approve`, в DSH — `/evolve approve`.

## Самоулучшение

`/learn` добавляет знание. `/improve <задача>` просит агента поправить навык, приём, правило или локальный плагин, проверить результат и сохранить урок. `/improve` и `/improve help` показывают памятку и модель не вызывают. Команда не переключает ASK/PLAN/BUILD.

Локальный plugin или skill живёт в изолированном состоянии проекта: записать, проверить статическим сканом, включить. Откат — `disable` или `rollback`. Уже загруженный код процесса без перезапуска сессии не выгружается. В Pi после включения — `/reload` в TUI или новый чат того же проекта в Web. В DSH — новая сессия.

Оценка навыка `/skill-eval` тратит вызовы модели только когда вы явно запускаете прогон. Это доверенный код с правами процесса, не песочница.
