CLI Help Layers：ヘルプ情報階層設計ガイド
AI-First CLI のコマンドラインインタラクションとドキュメント体系に設計指針を提供します。主な読者：人間の開発者 + LLM/エージェント。
3つの設計思想
- 段階的開示：usage → help → man、情報密度が段階的に増加。エージェントは多くの場合、最初の2層のみで十分。
- 実例を規範に：tldr を参考に、各層のドキュメントは実行可能な実例を起点とする。
- 構造化優先：固定の区切り文字とフォーマット規則により、LLM によるゼロショット抽出を容易にする。
4層情報アーキテクチャ
| トリガー方法 | 層 | カバレッジ | 内容 |
|---|---|---|---|
| 引数なしのコマンド | @USAGE | 80% | BRIEF + SYNTAX + 3-5 実例 |
-h / --help | @HELP | 95% | OPTIONS 表 + ENUMS + COMMON ERRORS |
サブコマンド --help | @HELP sub | 98% | 固有オプション + INHERITED OPTIONS + TEMPLATE |
--man | @MAN | 100% | SCHEMA + EXIT CODES + ALL ERRORS + CAVEATS |
構造化マーク
@USAGE <path> / @HELP <path> / @MAN <path> → 層識別子
BRIEF: / SYNTAX: / OPTIONS: / ENUMS: / EXAMPLES: / ERRORS: → ブロックラベル
# [RECOMMENDED] / [TEMPLATE] / [PIPELINE] / [ADVANCED] → 実例ラベル
エージェント検出用正規表現：^@(USAGE|HELP|MAN)\s+(.+)$、ブロック：^([A-Z ]+):$
ワークフロー
CLI ヘルプドキュメントの設計またはレビュー時：
- コマンド構造の決定 →
references/architecture.mdを参照（命名規則、名詞-動詞の構成） - Usage の作成 →
references/usage-spec.mdを参照（テンプレート + 実例選択の原則） - Help の作成 →
references/help-spec.mdを参照（OPTIONS 表 + 列挙 + サブコマンド Help） - Man の作成 →
references/man-spec.mdを参照（SCHEMA + EXIT CODES + 完全なエラーコード） - エラーメッセージの設計 →
references/error-design.mdを参照（エラーコードのエンコード + 各層への埋め込み戦略） - エージェント親和性の最適化 →
references/agent-friendly.mdを参照（文案スタイル + マークシステム + 開示フロー） - チェックリスト確認 →
references/checklist.mdを参照（5軸チェックリスト） - 完全な実例の参照 →
references/example-feishu-doc.mdを参照（feishu doc コマンドファミリーの3層完全実践）
適用範囲
このスキルを以下の目的に使用しないでください：
- CLI ツールの実際のコード実装（ドキュメント設計のみを扱う）
- 非コマンドラインの API ドキュメント設計
- 既存 CLI ツールの実行とデバッグ