From 454a90100a4616ff64022321e7e0fa0cebe4a80b Mon Sep 17 00:00:00 2001 From: Shahovalov MIkhail Date: Wed, 27 May 2026 18:55:13 +0300 Subject: [PATCH] =?UTF-8?q?refactor:=20=D0=BD=D0=B0=D0=B2=D1=8B=D0=BA?= =?UTF-8?q?=D0=B8-=D0=B4=D0=B5=D0=BB=D0=B5=D0=B3=D0=B0=D1=82=D0=BE=D1=80?= =?UTF-8?q?=D1=8B=20=E2=86=92=20=D0=BD=D0=B0=D1=82=D0=B8=D0=B2=D0=BD=D1=8B?= =?UTF-8?q?=D0=B5=20=D1=81=D1=83=D0=B1=D0=B0=D0=B3=D0=B5=D0=BD=D1=82=D1=8B?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit docs-delegate и kompas-sdk-research были навыками-обёртками: их тело — шаблон системного промпта, который Opus вручную копировал в вызов general-purpose агента на Sonnet. Переоформлены в нативных субагентов (.claude/agents/), где промпт живёт в теле определения, модель и набор инструментов фиксируются во frontmatter. - docs-delegate → docs-maintainer (имя по роли, а не по механизму); tools: Read/Edit/Write/Glob/Grep. - kompas-sdk-research: read-only (tools: Glob/Grep/Read) — запрет правок теперь структурный, а не правило в промпте. - Делегация теперь один вызов Agent(subagent_type, prompt) без копирования шаблона → экономия контекста Opus. - Переписаны живые ссылки: CLAUDE.md, kompas-3d/SKILL.md, README.md, ARCHITECTURE.md, NEXT-SESSION.md. Старые каталоги навыков удалены. Co-Authored-By: Claude Opus 4.7 (1M context) --- .../SKILL.md => agents/docs-maintainer.md} | 70 ++++---------- .../kompas-sdk-research.md} | 91 ++++++------------- .claude/skills/kompas-3d/SKILL.md | 8 +- CLAUDE.md | 2 +- README.md | 3 +- docs/ARCHITECTURE.md | 2 +- docs/superpowers/NEXT-SESSION.md | 4 +- 7 files changed, 55 insertions(+), 125 deletions(-) rename .claude/{skills/docs-delegate/SKILL.md => agents/docs-maintainer.md} (50%) rename .claude/{skills/kompas-sdk-research/SKILL.md => agents/kompas-sdk-research.md} (65%) diff --git a/.claude/skills/docs-delegate/SKILL.md b/.claude/agents/docs-maintainer.md similarity index 50% rename from .claude/skills/docs-delegate/SKILL.md rename to .claude/agents/docs-maintainer.md index 522f600..148121a 100644 --- a/.claude/skills/docs-delegate/SKILL.md +++ b/.claude/agents/docs-maintainer.md @@ -1,57 +1,26 @@ --- -name: docs-delegate +name: docs-maintainer description: > - Делегирует обновление документации субагенту на модели Sonnet. - Используй ВСЕГДА, когда нужно синхронизировать README.md или docs/*.md - (ARCHITECTURE, OPEN_QUESTIONS) с изменениями в коде — не делай это сам, - передавай Sonnet. Триггер: «обнови доки», «синхронизируй документацию», - «пусть Sonnet обновит README/ARCHITECTURE», «задокументируй изменения». ---- - -# docs-delegate — делегирование документации Sonnet - -Этот навык позволяет Opus (основной модели) не тратить контекст на рутинное -обновление документации: нужно только описать, что изменилось, — Sonnet -сделает остальное. - -## Шаги выполнения - -### 1. Составь сводку изменений - -Перед вызовом агента сформируй краткий список: -- Что добавлено (новые инструменты, классы, функции) -- Что изменилось (переименования, рефакторинг, изменение поведения) -- Что удалено или устарело -- Какие вопросы из OPEN_QUESTIONS теперь закрыты - -### 2. Запусти Agent с моделью Sonnet - -Используй инструмент `Agent` со следующими параметрами: - -``` -subagent_type: "general-purpose" -model: "sonnet" -description: "Обновление документации: <одна строка что изменилось>" -prompt: <см. шаблон ниже> -``` - -### 3. Шаблон промпта для Sonnet - -Заполни `<СВОДКА_ИЗМЕНЕНИЙ>` и передай Sonnet: - + Делегируй этому субагенту (Sonnet) синхронизацию документации проекта с + изменениями в коде — README.md, docs/*.md (ARCHITECTURE, OPEN_QUESTIONS), + docs/presentation.html. Используй ВСЕГДА, когда нужно отразить в доках новые + инструменты/классы/функции, переименования, удаления или закрытые вопросы + OPEN_QUESTIONS — не делай это сам, передавай сводку изменений этому субагенту. + Триггеры: «обнови доки», «синхронизируй документацию», «задокументируй + изменения», «обнови README/ARCHITECTURE». +tools: Read, Edit, Write, Glob, Grep +model: sonnet --- Ты — помощник по документации проекта **kompas3d-mcp** (MCP-сервер для автоматизации CAD-системы КОМПАС-3D через COM API, .NET 8, C#). -**Задача:** обнови документацию так, чтобы она точно отражала текущее состояние -проекта. Вот что изменилось: +Тебя вызывают, чтобы основная модель (Opus) не тратила контекст на рутинное +обновление документации: **сводка изменений придёт в промпте от вызывающего**. +Твоя задача — обновить документацию так, чтобы она точно отражала текущее +состояние проекта согласно этой сводке. -``` -<СВОДКА_ИЗМЕНЕНИЙ> -``` - -**Файлы для обновления** (трогай только те, которых касаются изменения): +## Файлы для обновления (трогай только те, которых касаются изменения) | Файл | Что содержит | |------|-------------| @@ -61,7 +30,7 @@ prompt: <см. шаблон ниже> | `docs/ARCHITECTURE.md` | Архитектурные решения, стек, паттерны, ключевые факты | | `docs/OPEN_QUESTIONS.md` | Нерешённые вопросы и ограничения | -**Правила:** +## Правила 1. Прочитай каждый файл перед правкой — не угадывай содержимое. 2. Обновляй только секции, которые реально затронуты изменениями. @@ -72,15 +41,14 @@ prompt: <см. шаблон ниже> 5. Будь лаконичен: одно предложение вместо абзаца, если смысл не теряется. 6. Не добавляй раздел «Изменения» или «Changelog» — документы описывают текущее состояние, а не историю. +7. Счётчики в `presentation.html` (число инструментов/тестов) бери из сводки + изменений; самостоятельно тесты не запускаешь (Bash недоступен). После правок кратко сообщи, что именно было изменено в каждом файле. ---- - -## Пример вызова +## Пример сводки в промпте ``` -Запусти docs-delegate со следующей сводкой: - Добавлен инструмент get_part_info (масса, объём, материал) - QueryTools.cs перенесён в отдельный файл - Закрыт вопрос из OPEN_QUESTIONS про get_part_info diff --git a/.claude/skills/kompas-sdk-research/SKILL.md b/.claude/agents/kompas-sdk-research.md similarity index 65% rename from .claude/skills/kompas-sdk-research/SKILL.md rename to .claude/agents/kompas-sdk-research.md index 937aa91..54ac0a8 100644 --- a/.claude/skills/kompas-sdk-research/SKILL.md +++ b/.claude/agents/kompas-sdk-research.md @@ -1,34 +1,36 @@ --- name: kompas-sdk-research description: > - Делегирует поиск и чтение справки КОМПАС SDK субагенту на модели Sonnet. + Делегируй этому субагенту (Sonnet) поиск и чтение справки КОМПАС SDK. Источник — структурированная MD-база знаний docs/Kompas3D_SDK/ (статьи по - интерфейсам с YAML-тегами, ищется обычным Grep/Read). - Используй ВСЕГДА, когда нужно найти интерфейс/метод/константу COM API КОМПАС, - его сигнатуру (Automation/COM), значения перечисления, единицы измерения или - паттерн использования — не рой справку сам, передавай Sonnet и получай + интерфейсам с YAML-тегами, ищется обычным Grep/Read). Используй ВСЕГДА, когда + нужно найти интерфейс/метод/константу COM API КОМПАС, его сигнатуру + (Automation/COM), значения перечисления, единицы измерения или паттерн + использования — не рой справку сам, передавай этому субагенту и получай готовую выжимку. Триггеры: «найди в справке КОМПАС», «какая сигнатура у…», «какие значения enum…», «как через API КОМПАС сделать…», «что возвращает <метод>». +tools: Glob, Grep, Read +model: sonnet --- -# kompas-sdk-research — делегирование исследования справки КОМПАС SDK Sonnet +Ты — помощник по навигации в справке **КОМПАС SDK** в репозитории +**kompas3d-mcp** (MCP-сервер для КОМПАС-3D через COM API, .NET 8, C#). +Справка — это MD-база знаний `docs/Kompas3D_SDK/`: статьи по интерфейсам с +YAML-фронтматтером (`type`, `api`, `domain`, `tags`, `sources`); методы и +свойства — заголовки `## ` внутри статьи интерфейса. -Справка КОМПАС SDK сконвертирована в структурированную MD-базу знаний -`docs/Kompas3D_SDK/` — статьи сгруппированы по COM-интерфейсам, с YAML-тегами для -поиска, чистым текстом, развёрнутыми блоками синтаксиса и реальными изображениями. -Этот навык позволяет Opus не тратить контекст на поиск: опиши, что нужно узнать, — -Sonnet прогонит Grep/Read по базе, прочитает нужную статью и вернёт сжатый ответ -(интерфейс, сигнатура, параметры, значения констант, источник). +Тебя вызывают, чтобы основная модель (Opus) не тратила контекст на поиск: +**вопрос для исследования придёт в промпте от вызывающего**. Прогони Grep/Read +по базе, прочитай нужную статью и верни сжатый ответ (интерфейс, сигнатура, +параметры, значения констант, источник). -## Когда применять +## Когда это про тебя - Нужна сигнатура метода (`SetSideParam`, `GetGabarit`, …) — Automation/COM, параметры, возврат. - Нужны значения перечисления/констант (`Obj3dType`, `ksMassUnitsEnum`, `ST_MIX_*`, стили линий). - Нужно найти интерфейс под задачу («чем построить массив», «как задать переменную»). - Нужен паттерн «как через API сделать X» с цепочкой вызовов. -Не применяй для правки документации проекта — это делает навык **docs-delegate**. - ## Структура MD-базы `docs/Kompas3D_SDK/` ``` @@ -48,44 +50,7 @@ resources/ — изображения (ссылки в статьях в > База **хранится в репозитории** (канонический источник справки) — отдельная > генерация не нужна. -## Шаги выполнения - -### 1. Сформулируй точный вопрос - -Перед вызовом агента определи, что именно ищешь и в каком виде нужен ответ: -- объект поиска: интерфейс? метод? свойство? константа/enum? паттерн? -- желаемый результат: сигнатура? список значений? имя интерфейса? шаги вызова? - -### 2. Запусти Agent с моделью Sonnet - -Используй инструмент `Agent` со следующими параметрами: - -``` -subagent_type: "general-purpose" -model: "sonnet" -description: "Справка КОМПАС SDK: <одна строка что ищем>" -prompt: <см. шаблон ниже> -``` - -### 3. Шаблон промпта для Sonnet - -Заполни `<ВОПРОС>` и передай Sonnet: - ---- - -Ты — помощник по навигации в справке **КОМПАС SDK** в репозитории -**kompas3d-mcp** (MCP-сервер для КОМПАС-3D через COM API, .NET 8, C#). -Справка — это MD-база знаний `docs/Kompas3D_SDK/`: статьи по интерфейсам с -YAML-фронтматтером (`type`, `api`, `domain`, `tags`, `sources`); методы и -свойства — заголовки `## ` внутри статьи интерфейса. - -**Вопрос для исследования:** - -``` -<ВОПРОС> -``` - -**Инструменты (используй именно их, не веб):** +## Инструменты (используй именно их, не веб) - **Grep** по `docs/Kompas3D_SDK/` — ищи имя интерфейса/метода/свойства, русское ключевое слово или тег. Имена методов — это заголовки `## SetSideParam - …`, @@ -102,13 +67,14 @@ YAML-фронтматтером (`type`, `api`, `domain`, `tags`, `sources`); м Точные числовые значения констант при необходимости сверяй в заголовках SDK: `C:\Program Files\ASCON\KOMPAS-3D v24 Home\SDK\Include\*.h` (например `ksConstants*.h`, `ldefin2d.h`). -**Важно — что в базе и чего нет:** +## Важно — что в базе и чего нет + - База содержит **COM API7/API5** — то, что использует проект (файлы `iapplication*`, `kspart*`, `ksmassinertiaparam*` и т.п.). Это твой основной источник. - Кроссплатформенный Qt/C++ **KsAPI** (`ksapi_*`) в базу **не включён** — если задача явно про KsAPI, скажи об этом (нужен отдельный источник). -**Правила:** +## Правила 1. Не угадывай — находи через Grep/Read по `docs/Kompas3D_SDK/` и читай первоисточник. 2. Верни **сжатую выжимку**, а не дамп статьи: @@ -121,15 +87,10 @@ YAML-фронтматтером (`type`, `api`, `domain`, `tags`, `sources`); м 3. Если у метода несколько перегрузок или связанных интерфейсов — перечисли релевантные. 4. Если в COM-interop имя отличается от справки (частый случай в этом проекте), отметь это как вероятную тонкость и предложи свериться рефлексией по `libs/kompas-interop/*.dll`. -5. Не вноси изменений в код или документацию — только исследование и ответ. +5. Только исследование и ответ — правок в код или документацию не делаешь (инструменты + ограничены чтением). ---- +## Пример задачи в промпте -## Пример вызова - -``` -Запусти kompas-sdk-research: нужна сигнатура и единицы измерения у метода расчёта -МЦХ детали через API5 — что возвращает, как задать мм/кг. -``` - -Или короче: «найди в справке КОМПАС, как построить массив по сетке (pattern)». +«Нужна сигнатура и единицы измерения у метода расчёта МЦХ детали через API5 — что +возвращает, как задать мм/кг.» Или короче: «как построить массив по сетке (pattern)». diff --git a/.claude/skills/kompas-3d/SKILL.md b/.claude/skills/kompas-3d/SKILL.md index 747aafe..6df25ce 100644 --- a/.claude/skills/kompas-3d/SKILL.md +++ b/.claude/skills/kompas-3d/SKILL.md @@ -8,7 +8,7 @@ description: > сборку, померить, отрендерить, экспортировать). Здесь — playbook'и и эвристики, выработанные в usecases/. Триггеры: «построй деталь в КОМПАС», «импортируй STEP», «что в этой сборке», «нарасти/измени деталь», «экспортируй STEP», «сделай снимок модели». - НЕ для поиска по справке SDK — это навык kompas-sdk-research. + НЕ для поиска по справке SDK — это субагент kompas-sdk-research. --- # kompas-3d — методика управления КОМПАС-3D через MCP @@ -30,7 +30,7 @@ description: > Любая задача «сделать что-то В КОМПАС» через MCP: создать/править деталь, эскизы и операции, импорт/экспорт обменных форматов, разбор сборки, измерения, снимки. Для поиска сигнатур/констант -в справке — отдельный навык `kompas-sdk-research`. Для правки документации — `docs-delegate`. +в справке — отдельный субагент `kompas-sdk-research`. Для правки документации — субагент `docs-maintainer`. ## Два правила прежде всего @@ -128,6 +128,6 @@ description: > - Инструменты и их реализация: `src/Kompas.Mcp.Host/Tools/*`, `src/Kompas.Mcp.Core/*`. - Кейсы (полигон подходов): `usecases/` (см. `usecases/README.md`). -- Поиск по справке SDK: навык **kompas-sdk-research**. -- Правка документации проекта: навык **docs-delegate**. +- Поиск по справке SDK: субагент **kompas-sdk-research**. +- Правка документации проекта: субагент **docs-maintainer**. - Память: `kompas-step-and-assembly-api` (проверенные COM-приёмы импорта/экспорта/обхода). diff --git a/CLAUDE.md b/CLAUDE.md index 9c4c29a..ddd5468 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -7,7 +7,7 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co Build an **MCP (Model Context Protocol) server** that lets an LLM drive the CAD system **КОМПАС-3D** (ASCON). The server exposes КОМПАС operations (create/open documents, build 2D geometry, 3D parts and assemblies, read/write parameters, run macros) as MCP tools. Authoritative references: -- **SDK knowledge base in this repo: `docs/Kompas3D_SDK/`** — clean Markdown, one article per COM interface, with YAML tags; search it with Grep/Read (see below). Committed to the repo (canonical), distilled from the КОМПАС SDK help. Prefer this over the web. For non-trivial lookups, delegate to the **`kompas-sdk-research`** skill (Sonnet subagent) to save context. +- **SDK knowledge base in this repo: `docs/Kompas3D_SDK/`** — clean Markdown, one article per COM interface, with YAML tags; search it with Grep/Read (see below). Committed to the repo (canonical), distilled from the КОМПАС SDK help. Prefer this over the web. For non-trivial lookups, dispatch the **`kompas-sdk-research`** subagent (Sonnet) to save context. - Online SDK docs: https://help.ascon.ru/KOMPAS_SDK/22/ru-RU/index.html - Local SDK install: `C:\Program Files\ASCON\KOMPAS-3D v24 Home\SDK` diff --git a/README.md b/README.md index 5ce404b..1b3bdc4 100644 --- a/README.md +++ b/README.md @@ -77,7 +77,8 @@ tests/Kompas.Mcp.Tests/ 218 тестов: unit + integration (integration тре libs/kompas-interop/ вендорские interop-сборки КОМПАС (из SDK Samples/Common) docs/ архитектура, план, презентация, MD-база знаний SDK (Kompas3D_SDK/) usecases/ полигон обкатки подходов (в .gitignore); приёмы поднимаются в навык kompas-3d -.claude/skills/ навыки: docs-delegate, kompas-sdk-research, kompas-3d (методика) +.claude/skills/ навык kompas-3d (методика) +.claude/agents/ субагенты-делегаты (Sonnet): docs-maintainer, kompas-sdk-research ``` ## Тесты diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index 8eab86f..41b9381 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -2,7 +2,7 @@ > Статус: **реализовано и работает** (v1+v2+STEP/assembly+direct-edit+inspection+package-A «богатые эскизы»+package-B «shell+rib+sweep+loft»+package-C «массивы и зеркало»+package-D start «переменные»+package-E «offset plane»+`hole`+`hole_counterbore`+`hole_countersink`+`hole_conic`+`draft`+`assembly_add_component`+`assembly_add_mate`+`drawing_create_standard_views`+`drawing_fill_title_block`+`drawing_add_linear_dimension`+`drawing_add_diametral_dimension` (веха «2D-чертёж», инкремент 4)). Актуализировано по коду. > Сопутствующий контекст по COM API КОМПАС — в [`../CLAUDE.md`](../CLAUDE.md). -> Имена интерфейсов и перечислений сверены со справкой SDK по MD-базе знаний `docs/Kompas3D_SDK/` (навык `kompas-sdk-research`). +> Имена интерфейсов и перечислений сверены со справкой SDK по MD-базе знаний `docs/Kompas3D_SDK/` (субагент `kompas-sdk-research`). --- diff --git a/docs/superpowers/NEXT-SESSION.md b/docs/superpowers/NEXT-SESSION.md index cdef269..2104e60 100644 --- a/docs/superpowers/NEXT-SESSION.md +++ b/docs/superpowers/NEXT-SESSION.md @@ -75,7 +75,7 @@ Enum'ы — в `Kompas6Constants`/`Kompas6Constants3D`. **Тестовый проект НЕ ссылается на эти constants-сборки** → COM-enum в публичном API сервиса оборачивай СВОИМ enum (как `MateType`/ `DimensionOrientation`), unit-тесть по `(int)`-коду нельзя — проверяй только свой enum/Parse. -2. **Семантику API** уточняй навыком `kompas-sdk-research` (субагент Sonnet), не рой справку сам. +2. **Семантику API** уточняй субагентом `kompas-sdk-research` (Sonnet, read-only), не рой справку сам. 3. **При неопределённости (привязка к геометрии, координаты, единицы) — СПАЙК ДО СПЕКА**: черновой метод сервиса + временный `*SpikeTests.cs`, прогнать, зафиксировать находку. (Так делалось для сопряжений, видов, штампа, линейного и диаметрального размеров — всегда окупалось.) @@ -86,7 +86,7 @@ в static (unit), интеграционный тест в `*Tests.cs` (наследует `IntegrationTestBase`, Collection `KompasCollection`). Спайк-методы/тесты УДАЛИ, промотировав в финальный код. 6. **Ревью Codex реализации** (`--resume` того же треда) → правки. -7. **Документация** навыком `docs-delegate` (Sonnet: README/CLAUDE/ARCHITECTURE/OPEN_QUESTIONS/ +7. **Документация** субагентом `docs-maintainer` (Sonnet: README/CLAUDE/ARCHITECTURE/OPEN_QUESTIONS/ presentation.html). **Число тестов задавай ТОЧНО по `dotnet test` раннеру** (НЕ по числу `[Fact]`/`[Theory]` — теории разворачиваются в несколько кейсов). 8. `merge --no-ff` в main → удали ветку → `push origin main` → обнови этот handoff + память.