--- name: doc-folder description: > Генерирует ОДИН обзорный README.md в корне указанной папки — навигационную карту мульти-проектной папки для будущего claude code и человека. Рекурсивно находит все .cs, определяет проекты (.csproj) и описывает каждый публичный тип кратким абзацем: что класс делает в целом, его логика/роль и зависимости — без сигнатур методов и таблиц параметров. Структура README: проекты → namespace → классы. Язык вывода — РУССКИЙ. Используй, когда пользователь говорит «doc-folder», «сделай README для папки», «опиши проекты в каталоге», «карта кода папки», «обзор классов в папке» — даже без слова «skill». Это НЕ генератор inline /// (для этого — doc-cs), НЕ детальная API-дока по .md на класс (для этого — doc-md) и НЕ схема БД (для этого — doc-db). disable-model-invocation: true allowed-tools: Read, Grep, Glob, Write, Bash, Task argument-hint: путь к папке (мульти-проектной) --- # doc-folder — обзорный README.md для мульти-проектной папки ## Когда срабатывать Пользователь просит обзорную карту кода папки: «doc-folder», «сделай README для папки», «опиши проекты в каталоге», «обзор классов». Вывод — один `README.md` в корне указанной папки, а НЕ дока по классам (`doc-md`) и не `///` (`doc-cs`). ## Общий алгоритм (три прохода) ### Pass 1 — обнаружение (главная сессия, Glob + Grep) 1. **Аргумент — путь к папке.** Если не передан — спроси путь. 2. **Найди все .cs:** `Glob("<папка>/**/*.cs")`. Исключи `bin/`, `obj/` и сгенерированные файлы: `*.g.cs`, `*.Designer.cs`, `*.AssemblyInfo.cs`, `*.AssemblyAttributes.cs`. 3. **Найди проекты:** `Glob("<папка>/**/*.csproj")`. Для каждого определи имя (файл без расширения), корневую папку, root-namespace (`` или имя проекта), `TargetFramework(s)`. 4. **Привяжи каждый .cs к проекту** по ближайшему `.csproj` вверх по дереву. `.cs` без проекта собери в группу «Вне проектов». 5. **Извлеки из каждого .cs** (Grep): `namespace`, ПУБЛИЧНЫЕ типы (`public ... class|interface|enum|record|struct`), базовый тип/интерфейсы, наличие `/// `. Только `public` — `internal`/`private` пропускай. - В одном `.cs` может быть **несколько** public-типов — делай запись на **каждый тип**, а не на файл. - **Вложенные** (nested) public-типы тоже включай. Grep по `public …` не отличает вложенные от верхнеуровневых — вложенность определяй при чтении тела типа в Pass 2 (по фигурным скобкам родителя). - Учитывай и file-scoped (`namespace X;`), и блочные (`namespace X { }`) объявления. Если `namespace` в файле нет (top-level statements) — тип относится к глобальному namespace проекта. ### Pass 2 — описание классов (LLM; опц. субагенты ≤ 10) Для каждого public-типа сформируй запись ~3-6 строк строго по `references/class-summary-style-ru.md` (прочитай файл до генерации): назначение (что класс делает в целом) + логика/роль + зависимости/использование. Без сигнатур методов и таблиц параметров. ### Pass 3 — сборка README (главная сессия) 1. Собери `README.md` по `assets/readme.md.template` (структура ниже). 2. Если существуют `documentation/api/` (от `doc-md`) или `documentation/database.md` (от `doc-db`) — добавь строку ссылок на них. Если их нет — строку не добавляй. 3. **Запиши** через `Write` в `<указанная папка>/README.md`. Файл **всегда перезаписывается** — это снимок текущего кода. ## Структура README (проекты → namespace → классы) - **Frontmatter** `type: folder-overview` (схема — `../doc-md/references/frontmatter-schema.md`, единый источник истины). - **Шапка**: назначение файла + дата генерации. - **Сводная таблица проектов**: Проект | TFM | Namespace | Описание. - **Описание проекта**: бери `` из `.csproj`, если есть; иначе сформулируй сам по структуре и коду проекта. - **Namespace** в таблице: root-namespace проекта; если namespace-деклараций нет (top-level statements) — пиши `(global)`. - **Раздел на каждый проект** → подзаголовки по `namespace` → записи классов. - Если в проекте один `namespace` (или его нет вовсе) — уровень группировки опусти, классы идут списком сразу под проектом. - **Вложенный** тип ставь записью сразу ПОСЛЕ записи родительского типа. - Если sub-namespace содержит **один** тип — не плоди отдельный заголовок: включи тип в ближайший родительский раздел, указав полный namespace в мета-строке записи (`Слой: … · \`Full.Sub.Namespace\` · …`). - **Тестовые проекты включай**; для тест-классов `layer` = `test`. Полный шаблон — `assets/readme.md.template`. Пример записи класса: ```markdown #### `SvItemDao` — репозиторий справочника «Уровни доступа» Слой: data-access · `Sample.Dico` · [`src/Dico/SvItemDao.cs`](src/Dico/SvItemDao.cs) Инкапсулирует CRUD к таблице `DICT.SV_ITEM` через ADO.NET. `Insert` версионирует запись через `SV_PREVIOUSID`, `GetAll` отдаёт только активные строки (`SV_RECORDSTATUS = 1`). Зависит от `AppContext`, используется `AccessService`. ``` ## Обработка больших папок (параллелизм ≤ 10) Опционально. Pass 1 и Pass 3 — всегда в главной сессии (один выходной файл, блоки склеивает главная). Pass 2 распараллеливай субагентами `Task` волнами не более 10: каждому передай его `.cs`-файлы и путь к `references/class-summary-style-ru.md` (обязан прочитать до генерации, иначе объём и стиль описаний разъедутся). Субагент возвращает готовые markdown-блоки классов — главная сессия компонует их в единый README. ## Соглашения - Язык вывода — русский; имена типов/членов/проектов — как в коде. - Только public-типы. Не выдумывай назначение — лучше короче. - Не воспроизводи сигнатуры методов и таблицы параметров (это `doc-md`). - Относительные пути в ссылках считай от `README.md` в корне указанной папки. - Ссылки на `documentation/...` ставь только если файлы существуют. - Якоря для ссылок в таблице проектов формируй по правилу GitHub Markdown: нижний регистр, пробелы → `-`, точки и прочие спецсимволы убери (`OllamaApiConsole` → `#ollamaapiconsole`, `My.Proj.Api` → `#myprojapi`). ## Когда отказаться - Просят inline `///` в `.cs` → `doc-cs`. - Просят детальную доку по классу (`.md` на класс, таблицы методов) → `doc-md`. - Просят описать схему БД → `doc-db`.