Nemagu Документирование CLI
Описывать наблюдаемый CLI-контракт независимо от языка, библиотеки разбора аргументов и способа упаковки приложения.
Обязательные справочники
Перед созданием или ревью читать:
- structure.md — структура файлов, уровни команд и навигация;
- command-contract.md — нормативное содержание общего и конечного контрактов;
- response-examples.md — требования к примерам консольных ответов;
- review-checklist.md — проверка готовности.
Размещение и навигация
Размещать CLI-документацию внутри presentation/cli/ принятой структуры.
Формировать только поддерево «CLI» в SUMMARY.md; положение среди соседних
presentation-разделов определяет общий скил документации сервиса.
Корневая команда, группы и конечные команды имеют отдельные документы. Общие правила не копировать в каждую команду: конечный документ ссылается на них и фиксирует только собственный контракт или явное отклонение.
Архитектурная граница
CLI владеет внешним синтаксисом, справкой, аргументами и опциями, транспортной валидацией, внешними моделями результата, статусами процесса и преобразованиями. Каждую конечную команду связывать с публичной application-операцией.
CLI-модель не является application DTO даже при совпадении полей. Преобразовывать только публичный application-вход, результат и исходы. Не обращаться к domain и не интерпретировать domain-ошибки напрямую. Идентичность и доверие брать из согласованного источника запуска, не предполагая их наличие или отсутствие.
Код не считать источником требований. Читать его только после отдельного разрешения пользователя для названной адаптации или проверки.
Стабильные обозначения
Использовать схему
<контекст>.presentation.cli.<группы...>.<действие или модель>. Каждый сегмент
обозначает один уровень иерархии; не склеивать ресурс и действие. Одинаковый
контракт имеет одно обозначение независимо от имени файла.
Рабочий процесс
- Согласовать потребителей, доверие, исполняемую команду и область применения.
- Согласовать общие форматы, подробность, потоки, статусы, справку, неполные вызовы и наличие служебных команд.
- Построить иерархию корневой команды, групп и действий.
- Связать каждую конечную команду с одной публичной application-операцией.
- Описать root- и group-уровни без преждевременной детализации данных.
- Для конечной команды описать вход, валидацию, mapping, результат, ошибки, повтор и совместимость.
- Добавить примеры ответов, проверив их по нормативным таблицам.
- Согласовать границу результата и логирования; при проектировании logging-
профиля использовать
service-observability-documentation-writing. - Обновить навигацию и выполнить checklist.
До массового описания однотипных команд полностью проработать одну эталонную команду и согласовать её с пользователем.
Согласование решений
Не выбирать самостоятельно иерархию, позиционные аргументы, имена и короткие формы опций, значения по умолчанию, поведение дубликатов, справки и неполного вызова, форматы, порядок полей, потоки, подробность, статусы завершения, корреляцию, повторы или совместимость.
Предлагать решения из справочника как стартовые варианты, а не как универсальные правила. Общие решения фиксировать один раз и не спрашивать повторно для каждой команды. За один подход задавать до пяти коротких, до трёх средних либо один-два крупных связанных вопроса.
Уровень конкретики
В назначении, навигации и кратком описании называть роль команды, не перечисляя её поля и внутренние шаги. Конкретику размещать там, где она является контрактом: в аргументах, опциях, моделях, валидации, mapping, результате и примерах ответов.
Готовность
Документ готов, если реализация не должна выбирать иерархию, синтаксис, источник и представление значения, обязательность, валидацию, mapping, результат, ошибочный вывод, справку, форматы, подробность, потоки, статусы, повтор или совместимость.
Каждый содержательный документ завершать разделом ## Открытые вопросы. Если
вопросов нет, писать Открытых вопросов нет.; не закрывать раздел, пока остаётся
неявно выбранное решение.