# CLI Documentation Writing

> Проектирование, создание, адаптация и ревью аналитической Markdown-документации CLI presentation-слоя: исполняемой команды, иерархии групп и действий, аргументов, опций, справки, внешней валидации, моделей результата, форматов, подробности, потоков, статусов завершения, application-mapping, ошибок, примеров ответов, корреляции и SUMMARY.md. Использовать, когда CLI-контракт должен быть достаточен для реализации без новых продуктовых решений. Не использовать для определения application/domain-контрактов, реализации CLI или восстановления требований из кода без разрешения.

- Skill: `nemagu/cli-documentation-writing` (Agent Skill, multi-file: 6 files)
- Install (CLI): `npx skillmds@latest add nemagu/cli-documentation-writing`
- Raw SKILL.md: https://api.skillmd.com/api/skills/nemagu/cli-documentation-writing/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: Nemagu (https://skillmd.com/u/nemagu)
- Updated: 2026-09-21
- Page: https://skillmd.com/skills/nemagu/cli-documentation-writing

---


# Документирование CLI

Описывать наблюдаемый CLI-контракт независимо от языка, библиотеки разбора
аргументов и способа упаковки приложения.

## Обязательные справочники

Перед созданием или ревью читать:

- [structure.md](references/structure.md) — структура файлов, уровни команд и
  навигация;
- [command-contract.md](references/command-contract.md) — нормативное содержание
  общего и конечного контрактов;
- [response-examples.md](references/response-examples.md) — требования к
  примерам консольных ответов;
- [review-checklist.md](references/review-checklist.md) — проверка готовности.

## Размещение и навигация

Размещать CLI-документацию внутри `presentation/cli/` принятой структуры.
Формировать только поддерево «CLI» в `SUMMARY.md`; положение среди соседних
presentation-разделов определяет общий скил документации сервиса.

Корневая команда, группы и конечные команды имеют отдельные документы. Общие
правила не копировать в каждую команду: конечный документ ссылается на них и
фиксирует только собственный контракт или явное отклонение.

## Архитектурная граница

CLI владеет внешним синтаксисом, справкой, аргументами и опциями, транспортной
валидацией, внешними моделями результата, статусами процесса и
преобразованиями. Каждую конечную команду связывать с публичной
application-операцией.

CLI-модель не является application DTO даже при совпадении полей. Преобразовывать
только публичный application-вход, результат и исходы. Не обращаться к domain и
не интерпретировать domain-ошибки напрямую. Идентичность и доверие брать из
согласованного источника запуска, не предполагая их наличие или отсутствие.

Код не считать источником требований. Читать его только после отдельного
разрешения пользователя для названной адаптации или проверки.

## Стабильные обозначения

Использовать схему
`<контекст>.presentation.cli.<группы...>.<действие или модель>`. Каждый сегмент
обозначает один уровень иерархии; не склеивать ресурс и действие. Одинаковый
контракт имеет одно обозначение независимо от имени файла.

## Рабочий процесс

1. Согласовать потребителей, доверие, исполняемую команду и область применения.
2. Согласовать общие форматы, подробность, потоки, статусы, справку, неполные
   вызовы и наличие служебных команд.
3. Построить иерархию корневой команды, групп и действий.
4. Связать каждую конечную команду с одной публичной application-операцией.
5. Описать root- и group-уровни без преждевременной детализации данных.
6. Для конечной команды описать вход, валидацию, mapping, результат, ошибки,
   повтор и совместимость.
7. Добавить примеры ответов, проверив их по нормативным таблицам.
8. Согласовать границу результата и логирования; при проектировании logging-
   профиля использовать `service-observability-documentation-writing`.
9. Обновить навигацию и выполнить checklist.

До массового описания однотипных команд полностью проработать одну эталонную
команду и согласовать её с пользователем.

## Согласование решений

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

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

## Уровень конкретики

В назначении, навигации и кратком описании называть роль команды, не перечисляя
её поля и внутренние шаги. Конкретику размещать там, где она является
контрактом: в аргументах, опциях, моделях, валидации, mapping, результате и
примерах ответов.

## Готовность

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

Каждый содержательный документ завершать разделом `## Открытые вопросы`. Если
вопросов нет, писать `Открытых вопросов нет.`; не закрывать раздел, пока остаётся
неявно выбранное решение.