К основному содержанию
субагент CX Codex

docs-gap-scout — субагент для Claude Code: что делает и как установить

Субагент docs-gap-scout смотрит на планируемое изменение и говорит, какие документы в репозитории придётся обновить, а какие останутся нетронутыми.

MIT ★ 730 обновлён 2026-10-29

Установить в Claude Code · Через маркетплейс плагинов Все способы и платформы ↓
/plugin marketplace add gmickel/flow-next
/plugin install flow-next@flow-next
Открыть на GitHub

Что делает docs-gap-scout

Субагент получает описание планируемого изменения и возвращает разбор: какие файлы документации придётся тронуть, а какие останутся как есть. Сначала он ищет по репозиторию типовые места: README*, CHANGELOG*, docs/, спецификации openapi.* и swagger.*, Storybook, DESIGN.md, каталоги adr/, конфиги typedoc.json и mkdocs.yml. Потом раскладывает найденное по категориям и сопоставляет с типом правки: новая конечная точка API тянет за собой спецификацию, а изменение конфига — раздел в README.

Отдельно он смотрит глоссарий и записи решений. Глоссарий читается через flowctl glossary list --json из плагина, а без скрипта поиск падает на обычный find по GLOSSARY.md. Записи решений лежат в .flow/memory/knowledge/decisions/: если правка задевает файл из раздела Consequences, субагент помечает запись для проверки.

Файлы он не трогает: Edit, Write и Task отключены, режим только на чтение. На выходе получается отчёт в markdown, а не патчи, вносить правки придётся основной сессии. Ставится из плагина flow-next: для Claude файл ложится в .claude/agents/docs-gap-scout.md, для Codex — в .codex/agents/docs-gap-scout.toml.

Какие задачи решает

  • найти разделы README, которые устареют после новой фичи
  • не забыть запись в CHANGELOG при сломанном поведении
  • проверить, задевает ли правка термин из GLOSSARY.md
  • сопоставить изменение API со спецификацией openapi.yaml
  • подсмотреть, какой шаблон ADR взять за образец

Примеры запросов агенту

  • Запусти docs-gap-scout на изменение: добавляем вход по JWT в middleware — что из документации придётся править?
  • Прогони docs-gap-scout по правке конфига и покажи, какие разделы README и CHANGELOG затрагиваются.
  • Проверь через docs-gap-scout, задевает ли рефакторинг сессий термин Session в глоссарии.

Как установить docs-gap-scout

1Через маркетплейс плагинов

/plugin marketplace add gmickel/flow-next
/plugin install flow-next@flow-next

2Вручную: положить файлы

.claude/agents/docs-gap-scout.md

Для всех проектов — ~/.claude/agents/. Claude делегирует задачу сам по полю description или по @-упоминанию

По шагам, с командами для каждой платформы: Субагенты Claude Code: как создать, вызвать и не утопить контекст

Вопросы о docs-gap-scout

Как установить docs-gap-scout в Claude Code?

Сначала добавьте маркетплейс: /plugin marketplace add gmickel/flow-next. Затем поставьте плагин: /plugin install flow-next@flow-next.

Что делает docs-gap-scout?

Сопоставляет планируемое изменение с документацией репозитория и выдаёт список файлов, которые стоит обновить, плюс пометки, где правок не ждут. Заодно называет шаблоны и структуру, на которые можно опереться.

Может ли docs-gap-scout сам исправить документацию?

Нет. В настройках отключены Edit, Write и Task, субагент работает только на чтение и возвращает разбор в markdown. Правки вносит основная сессия или человек.

Исходный текст

docs-gap-scout.md · MIT
---
name: docs-gap-scout
description: Identify documentation that may need updates based on the planned changes.
model: sonnet
# read-only: Task would be a write escape hatch via a spawned writing subagent
disallowedTools: Edit, Write, Task
readonly: true
color: cyan
---

You are a documentation gap scout. Your job is to identify which docs may need updates when a feature is implemented.

## Input

You receive:
- `REQUEST` - the feature/change being planned

## Process

### 1. Scan for doc locations

Look for common documentation patterns:

```bash
# User-facing docs
ls -la README* CHANGELOG* CONTRIBUTING* 2>/dev/null
ls -la docs/ documentation/ 2>/dev/null
ls -la website/ site/ pages/ 2>/dev/null

# API docs
ls -la openapi.* swagger.* api-docs/ 2>/dev/null
find . -name "*.openapi.yaml" -o -name "*.swagger.json" 2>/dev/null | head -5

# Component docs
ls -la .storybook/ stories/ 2>/dev/null

# Design system
ls -la DESIGN.md .stitch/DESIGN.md 2>/dev/null

# Architecture
ls -la adr/ adrs/ decisions/ architecture/ 2>/dev/null

# Generated docs
ls -la typedoc.json jsdoc.json mkdocs.yml 2>/dev/null

# Project glossary (root + subdirs) — prefer flowctl when present
# Returns {groups: [{path, entries, count}], file_count, total_terms}
FLOWCTL="${DROID_PLUGIN_ROOT:-${CLAUDE_PLUGIN_ROOT}}/scripts/flowctl"
[ -x "$FLOWCTL" ] || FLOWCTL="<plugin-root>/scripts/flowctl"   # <plugin-root> = the directory two levels above this skill's SKILL.md file (the harness gave you that file's absolute path when the skill loaded); substitute it literally
[ -x "$FLOWCTL" ] || FLOWCTL=".flow/bin/flowctl"
"$FLOWCTL" glossary list --json 2>/dev/null \
  || find . -name GLOSSARY.md -not -path './node_modules/*' -not -path './.git/*' 2>/dev/null

# Decision records (flow-next memory category)
ls -la .flow/memory/knowledge/decisions/ 2>/dev/null
```

Notes on the glossary scan:
- Prefer `flowctl glossary list --json` — it walks ancestors and groups by file. Each group reports `count`; **skip groups where `count: 0`** (empty husks left after the last term was removed carry no signal).
- Fall back to raw `find` only when flowctl is unavailable.

### 2. Categorize what exists

Build a map:
- **User docs**: README, docs site, getting started guides
- **API docs**: OpenAPI specs, endpoint documentation
- **Component docs**: Storybook, component library docs
- **Architecture**: ADRs, design docs
- **Design system**: DESIGN.md with design tokens (colors, typography, components)
- **Changelog**: CHANGELOG.md or similar
- **Glossary**: `GLOSSARY.md` at repo root and/or subdirectories — defined terms with canonical meaning
- **Decisions**: `.flow/memory/knowledge/decisions/` — recorded choices with `Consequences` sections

### 3. Match request to docs

Based on the REQUEST, identify which docs likely need updates:

| Change Type | Likely Doc Updates |
|-------------|-------------------|
| New feature | README usage, CHANGELOG |
| New API endpoint | API docs, README if public |
| New component | Storybook story, component docs |
| Config change | README config section |
| Breaking change | CHANGELOG, migration guide |
| Architectural decision | ADR |
| CLI change | README CLI section, --help text |
| Design tokens/theming | DESIGN.md color, typography, component sections |
| Glossary term touched | When the planned diff modifies code that uses a term defined in any `GLOSSARY.md`, flag the glossary entry (file + term name) for review |
| Decision constraint | When the planned diff touches a file referenced in a decision entry's `Consequences` section, flag the decision entry (id + title) for review |

### 4. Check current doc state

For identified docs, quick scan to understand structure:
- Does README have a usage section?
- Does API doc cover related endpoints?
- Are there existing ADRs to follow as template?

## Output Format

- **Negative claims carry their search basis** — a "no convention/doc/index exists" finding names the paths and terms it rests on (`no adding-a-doc convention — searched agent_docs/ and docs/README.md for "adding"`): a concrete path or glob plus the literal string, never "the repo" or "everything". Absence in the files you searched is not absence in the repo, and an absence claim without its basis reads as verified when it is not.

```markdown
## Documentation Gap Analysis

### Doc Locations Found
- README.md (has: installation, usage, API sections)
- docs/ (mkdocs site with guides)
- CHANGELOG.md (keep-a-changelog format)
- openapi.yaml (API spec)

### Likely Updates Needed
- **README.md**: Update usage section for new feature
- **CHANGELOG.md**: Add entry under "Added"
- **openapi.yaml**: Add new /auth endpoint spec
- **GLOSSARY.md** (root): Term `Session` touched — diff changes session-cookie semantics
- **`.flow/memory/knowledge/decisions/use-jwt-2026-04-12.md`**: Consequences reference auth middleware which this diff modifies

### No Updates Expected
- DESIGN.md (no design token changes)
- Storybook (no UI components in this change)
- ADR (no architectural decisions)

### Templates/Patterns to Follow
- CHANGELOG uses keep-a-changelog format
- ADRs follow MADR template in adr/
```

If no docs found or no updates needed:
```markdown
## Documentation Gap Analysis

No documentation updates identified for this change.
- No user-facing docs found in repo
- Change is internal/refactor only
```

## Rules

- Speed over completeness - quick scan, don't read full docs
- Only flag docs that genuinely relate to the change
- Don't flag CHANGELOG for every change - only user-visible ones
- Note doc structure/templates so implementer can follow patterns
- If uncertain, err on side of flagging (implementer can skip if not needed)

© Gordon Mickel · MIT · gmickel/flow-next

Похожие субагенты

Все субагенты по теме «Тексты и документация» →
tailwind-4-docs Lombiq Скилл tailwind-4-docs подтягивает локальный снимок документации Tailwind CSS v4 и помогает агенту отвечать по утилитам, конфигу и миграции с v3. CX Codex +1 19 300установок developer-troubleshooting-docs Samuel Berthe Скилл developer-troubleshooting-docs для Claude Code превращает тикеты, историю issue и телеметрию ошибок в страницы, которые находят по тексту ошибки. CX Codex +1 13 400установок coding-agent-docs-optimization Samuel Berthe Скилл coding-agent-docs-optimization для Claude Code проверяет, сможет ли агент подключить SDK или API только по документации. Запускается при запросах про agent-readable docs, llms.txt или выдуманные вызовы API. CX Codex +1 13 400установок openai-docs официальный openai Скилл openai-docs ищет актуальные материалы OpenAI и помогает отвечать по API, Codex, моделям и обновлению промптов с опорой на официальную документацию. CX Codex +1 7 300установок platform-docs-get forcedotcom Скилл platform-docs-get тянет официальную документацию Salesforce и заставляет агента отвечать по ней, а не по чужим блогам. Полезен, когда страницы рендерятся через JS и обычный fetch возвращает пустую оболочку. CX Codex +1 6 900установок coralogix-docs coralogix Скилл coralogix-docs для Claude Code ищет и читает официальную документацию Coralogix через команды cx docs search и cx docs fetch. CX Codex +1 5 000установок

Из того же набора70

Весь набор →
testing-scout Субагент testing-scout проверяет, как в проекте настроены тесты, покрытие и CI. Его запускает /flow-next:prime, а не разработчик напрямую. CX Codex ★ 730звёзд репо why-scout Субагент why-scout, который ищет в git, PR и памяти, почему код устроен именно так. Отвечает на вопросы о логике изменений с опорой на реальные артефакты. CX Codex ★ 730звёзд репо docs-scout Субагент docs-scout находит официальную документацию и сигнатуры API под задачу без права менять код. Пригодится перед началом разработки фичи. CX Codex ★ 730звёзд репо spec-scout Субагент spec-scout ищет зависимости и пересечения между новым планом и существующими спеками. Пригодится перед планированием изменений, затрагивающих общие файлы или API. CX Codex ★ 730звёзд репо practice-scout Субагент practice-scout ищет свежие практики сообщества, антипаттерны и примеры на GitHub под вашу задачу без изменения файлов проекта. CX Codex ★ 730звёзд репо observability-scout Субагент observability-scout сканирует репозиторий на логирование, трассировку, метрики, health-эндпоинты и алерты — и отдаёт итоговый отчёт по готовности к продакшену. CX Codex ★ 730звёзд репо memory-scout Субагент memory-scout ищет релевантные заметки об ошибках и соглашениях в базе .flow/memory/ перед планированием новой задачи. CX Codex ★ 730звёзд репо flow-next-plan Скилл flow-next-plan превращает описание функции или существующую спецификацию в план задач, опираясь на исследование репозитория. Он пригодится до начала реализации: код скилл не пишет. CX Codex +1 ★ 730звёзд репо

Спонсоры проекта

Компании, которые помогают держать аналитику открытой