refactor: навыки-делегаторы → нативные субагенты
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) <noreply@anthropic.com>
This commit is contained in:
@@ -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
|
||||
+26
-65
@@ -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)».
|
||||
@@ -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-приёмы импорта/экспорта/обхода).
|
||||
|
||||
@@ -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`
|
||||
|
||||
|
||||
@@ -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
|
||||
```
|
||||
|
||||
## Тесты
|
||||
|
||||
@@ -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`).
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -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 + память.
|
||||
|
||||
Reference in New Issue
Block a user