Back to Details

cli-design-framework

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

CLI Design Framework

CLI 设计框架

Overview

概述

Design and review CLIs with a classification-first framework.
Treat this as a decision system, not a generic style guide. Do not assume every CLI should become agent-first, machine-protocol-first, or raw-payload-first.
采用分类优先的框架来设计和评审CLI。
将其视为决策系统，而非通用风格指南。不要假设每个CLI都应该以Agent优先、机器协议优先或原始负载优先的方式构建。

When to Use

适用场景

Use this skill when:
  • designing a new CLI and the right command shape is not obvious
  • reviewing an existing CLI whose help, output, or command tree feels mismatched
  • deciding whether a CLI is primarily Capability, Runtime, Environment / Workspace, Workflow, Package / Build, or Meta
  • deciding whether human-readable and machine-readable surfaces are primary or secondary
  • deciding whether session semantics are justified or over-engineered
Do not use this skill when:
  • the CLI classification is already settled and you only need implementation mechanics
  • the question is only about parser libraries, repository layout, or exact flag spelling
  • the task is purely cosmetic copy editing with no design consequence
在以下场景使用本方法：
  • 设计新CLI，但合适的命令形式尚不明确
  • 评审现有CLI，但其帮助信息、输出内容或命令树看起来不协调
  • 确定CLI主要属于能力型、运行时型、环境/工作区型、工作流型、包/构建型还是元类型
  • 确定人类可读和机器可读界面哪个是主界面、哪个是次界面
  • 确定会话语义是否合理，是否存在过度设计
在以下场景请勿使用本方法：
  • CLI的分类已确定，仅需要实现机制相关内容
  • 问题仅涉及解析库、仓库布局或确切的标志拼写
  • 任务纯粹是 cosmetic 文案编辑，不涉及设计影响

Quick Path

快速路径

  • For quick asks, produce a compressed pass: purpose, classification, short reasoning, top design consequences, and only the unresolved questions that could change the answer.
  • Use the full blueprint or full review template only when the user asks for it explicitly, or when ambiguity or risk justifies the longer form.
  • 对于快速需求，生成精简版内容：用途、分类、简短推理、核心设计影响，以及可能改变结论的未解决问题。
  • 仅当用户明确要求，或存在模糊性、高风险需要更详细内容时，才使用完整蓝图或完整评审模板。

Core rule

核心规则

Classify first. Design second. Review third.
Always work in this order:
  1. State the CLI purpose in one sentence.
  2. Classify the primary role/control surface.
  3. Classify the primary user type.
  4. Classify the primary interaction form.
  5. Classify statefulness.
  6. Classify risk profile.
  7. Identify secondary surfaces explicitly.
  8. Derive design consequences.
Start with these files when using the framework:
  • references/taxonomy.md
    for the taxonomy.
  • references/output-templates.md
    for the required output shape.
Pull these only when needed:
  • references/classification-examples.md
    for classification anchors when the category is ambiguous.
  • examples/design-blueprint-example.md
    and 
    examples/review-example.md
    when you need a concrete example of final form.
  • examples/anti-patterns.md
    when the design smells wrong but the category mistake is not yet crisp.
先分类，再设计，最后评审。
务必遵循以下顺序：
  1. 用一句话说明CLI的用途。
  2. 对主要角色/控制界面进行分类。
  3. 对主要用户类型进行分类。
  4. 对主要交互形式进行分类。
  5. 对状态性进行分类。
  6. 对风险概况进行分类。
  7. 明确识别次要界面。
  8. 推导设计影响。
使用本框架时，先从以下文件入手：
  • references/taxonomy.md
    ：分类体系
  • references/output-templates.md
    ：所需输出格式
仅在需要时参考以下文件：
  • references/classification-examples.md
    ：分类模糊时的参考示例
  • examples/design-blueprint-example.md
    和 
    examples/review-example.md
    ：最终输出形式的具体示例
  • examples/anti-patterns.md
    ：设计存在问题但分类错误尚不明确时的参考

Operating modes

操作模式

Operate in one of two modes:
  1. Design mode — create or refine a CLI design direction.
  2. Review mode — evaluate an existing CLI against the framework.
采用以下两种模式之一：
  1. 设计模式 — 创建或优化CLI的设计方向。
  2. 评审模式 — 根据框架评估现有CLI。

Design mode

设计模式

Goal

目标

Clarify the CLI's design target, then produce a blueprint that constrains implementation.
明确CLI的设计目标，然后生成约束实现的蓝图。

Workflow

工作流程

  1. Infer what is already known.
    • Extract every strong signal from the user's request.
    • Infer likely role, user type, interaction form, statefulness, risk profile, and secondary surfaces whenever possible.
    • Do not ask for facts that are already strongly implied.
  2. Ask only the highest-leverage unresolved questions.
    • Ask the smallest set of questions that could materially change the classification or the blueprint.
    • Prefer classification questions over implementation trivia.
    • Prioritize: purpose → control surface → primary user → interaction form → statefulness → side effects → secondary surfaces.
    • If the current information is already sufficient, do not ask questions. Produce the blueprint directly.
  3. Classify the CLI explicitly.
    • State the inferred or confirmed:
      • primary role/control-surface type
      • primary user type
      • primary interaction form
      • statefulness
      • risk profile
      • secondary surfaces
    • State confidence when inference is uncertain.
    • Use explicit primary-vs-secondary wording. Do not blur them together.
  4. State the design stance before proposing commands.
    • Write one short paragraph that says what the CLI is optimizing for.
    • State what the CLI is not trying to be.
    • Do not jump straight from classification to command trees.
  5. Produce a design blueprint.
    • Use the structure in 
      references/output-templates.md
      .
    • Use the full template when the user wants a blueprint or when the ambiguity/risk warrants it.
    • For quick requests, compress to: purpose, classification, classification reasoning, design stance, top design consequences, and only the unresolved questions that matter.
    • Connect classification directly to design consequences.
    • Keep the blueprint concrete, not generic.
  6. Constrain downstream implementation.
    • End with a short direction section that states:
      • what to optimize for
      • what not to optimize for
      • acceptable patterns
      • category mistakes
      • v1 boundaries and non-goals
  1. 推断已知信息。
    • 从用户需求中提取所有明确信号。
    • 尽可能推断可能的角色、用户类型、交互形式、状态性、风险概况和次要界面。
    • 不要询问已明确暗示的信息。
  2. 仅询问影响重大的未解决问题。
    • 提出最少量的问题，这些问题可能会实质性改变分类或蓝图。
    • 优先询问分类相关问题，而非实现细节。
    • 优先级：用途 → 控制界面 → 主要用户 → 交互形式 → 状态性 → 副作用 → 次要界面。
    • 如果现有信息已足够，请勿提问，直接生成蓝图。
  3. 明确对CLI进行分类。
    • 说明推断或确认的内容：
      • 主要角色/控制界面类型
      • 主要用户类型
      • 主要交互形式
      • 状态性
      • 风险概况
      • 次要界面
    • 推断不确定时说明置信度。
    • 使用明确的主次表述，不要混淆。
  4. 在提出命令前说明设计立场。
    • 用一小段文字说明CLI的优化方向。
    • 说明CLI不要成为什么。
    • 不要直接从分类跳到命令树设计。
  5. 生成设计蓝图。
    • 遵循 
      references/output-templates.md
      中的结构。
    • 当用户需要蓝图，或存在模糊性/高风险时，使用完整模板。
    • 对于快速请求，精简为：用途、分类、分类推理、设计立场、核心设计影响，以及重要的未解决问题。
    • 将分类直接与设计影响关联。
    • 保持蓝图具体，避免泛泛而谈。
  6. 约束下游实现。
    • 以简短的方向部分结尾，说明：
      • 优化方向
      • 非优化方向
      • 可接受的模式
      • 分类错误示例
      • v1版本边界和非目标

Required design discipline

必备设计准则

For every blueprint, enforce these rules:
  • Primary vs secondary surfaces
    • Name the primary surface explicitly.
    • Name secondary surfaces explicitly.
    • State what each surface is for.
    • Do not describe JSON, event streams, templates, raw payloads, or TUI as “important” without saying whether they are primary or secondary.
  • Human-primary / balanced discoverability
    • If the CLI is human-primary or balanced, explicitly cover:
      • help quality
      • examples
      • discoverability
      • explain/describe surfaces when appropriate
    • Do not discuss only command structure and ignore learnability.
  • Structured machine contract
    • If the CLI has a machine-readable surface, explicitly state:
      • which commands expose it
      • output format (
        --json
        , 
        --jsonl
        , etc.)
      • whether field names are stable
      • whether exit codes matter
      • whether schema / fields / describe support is needed
    • Do not call a surface “script-friendly” unless the contract is described.
  • Risk ladder
    • If the CLI mutates state, define at least:
      • low-risk operations
      • medium-risk operations
      • high-risk operations
    • State the expected guardrails for each level.
    • Do not stop at “be careful” or “add confirmations.”
  • State model
    • If the CLI is sessionful, long-running, or attach/detach capable, describe session identity and lifecycle explicitly.
    • If it is mostly stateless, say so explicitly and avoid inventing session semantics.
  • v1 boundaries
    • State what v1 should include.
    • State what v1 should defer.
    • State what would be premature abstraction.
对于每个蓝图，强制执行以下规则：
  • 主次界面区分
    • 明确命名主界面。
    • 明确命名次要界面。
    • 说明每个界面的用途。
    • 不要将JSON、事件流、模板、原始负载或TUI描述为“重要”，除非说明它们是主界面还是次界面。
  • 人类优先/平衡可发现性
    • 如果CLI是人类优先或平衡型，明确涵盖：
      • 帮助信息质量
      • 示例
      • 可发现性
      • 必要时提供解释/描述界面
    • 不要只讨论命令结构而忽略可学习性。
  • 结构化机器契约
    • 如果CLI有机器可读界面，明确说明：
      • 哪些命令支持该界面
      • 输出格式（
        --json
        、
        --jsonl
        等）
      • 字段名是否稳定
      • 退出码是否重要
      • 是否需要 schema/字段/描述支持
    • 除非描述了契约，否则不要称界面为“脚本友好”。
  • 风险层级
    • 如果CLI会修改状态，至少定义：
      • 低风险操作
      • 中风险操作
      • 高风险操作
    • 说明每个层级的预期防护措施。
    • 不要只停留在“小心操作”或“添加确认步骤”。
  • 状态模型
    • 如果CLI是会话型、长运行型或支持附加/分离，明确描述会话标识和生命周期。
    • 如果主要是无状态，明确说明，避免引入会话语义。
  • v1版本边界
    • 说明v1版本应包含的内容。
    • 说明v1版本应推迟的内容。
    • 说明什么是过早的抽象。

Question policy

提问策略

Ask only questions that affect classification or the blueprint.
Do not begin with implementation-detail questions such as:
  • language choice
  • parsing library
  • repository layout
  • naming bikesheds
  • exact flag spelling
Ask those only if they materially affect the CLI's classification or design consequences.
仅询问影响分类或蓝图的问题。
请勿一开始就问实现细节问题，例如：
  • 语言选择
  • 解析库
  • 仓库布局
  • 命名争议
  • 确切的标志拼写
仅当这些问题实质性影响CLI的分类或设计影响时才询问。

Review mode

评审模式

Goal

目标

Inspect the CLI and its source, reverse-infer its design intent, then review it in two layers:
  1. Classification fit — Is it designed like the right kind of CLI?
  2. Execution quality — Given that type, how well is it executed?
检查CLI及其源代码，反向推断其设计意图，然后从两层进行评审：
  1. 分类适配性 — 它是否符合对应类型CLI的设计要求？
  2. 执行质量 — 基于其类型，执行效果如何？

Workflow

工作流程

  1. Inspect before asking.
    • Inspect help output, subcommand help, docs, examples, parser code, output code, error handling, state/session code, config surfaces, and tests.
    • Prefer direct evidence over speculation.
  2. Reverse-infer the design intent.
    • Infer:
      • apparent purpose
      • likely primary role/control-surface type
      • likely primary user type
      • likely interaction form
      • likely statefulness
      • likely risk profile
      • existing secondary surfaces
  3. Confirm only what cannot be inferred reliably.
    • Ask focused confirmation questions only when the answer could materially change the classification or review.
    • Do not ask the user to restate facts already evident from the CLI or code.
  4. Review in two layers.
    • Keep classification fit and execution quality separate.
    • Do not criticize a human-primary CLI for not being agent-primary unless the user explicitly wants that shift.
  5. Produce a structured review.
    • Use the review structure in 
      references/output-templates.md
      .
    • Use the full template when the user wants a formal review or when the category tension is material.
    • For quick requests, compress to: inferred intent, classification, evidence-backed category mistakes, in-category weaknesses, and highest-priority improvements.
    • Separate category mistakes from in-category execution weaknesses.
  1. 先检查再提问。
    • 检查帮助输出、子命令帮助、文档、示例、解析器代码、输出代码、错误处理、状态/会话代码、配置界面和测试。
    • 优先基于直接证据，而非猜测。
  2. 反向推断设计意图。
    • 推断：
      • 表面用途
      • 可能的主要角色/控制界面类型
      • 可能的主要用户类型
      • 可能的主要交互形式
      • 可能的状态性
      • 可能的风险概况
      • 现有次要界面
  3. 仅确认无法可靠推断的内容。
    • 仅当答案可能实质性改变分类或评审时，提出针对性的确认问题。
    • 不要要求用户重述已从CLI或代码中明确体现的事实。
  4. 分两层进行评审。
    • 将分类适配性和执行质量分开。
    • 除非用户明确要求转变类型，否则不要批评人类优先的CLI没有以Agent优先的方式设计。
  5. 生成结构化评审报告。
    • 遵循 
      references/output-templates.md
      中的评审结构。
    • 当用户需要正式评审，或分类冲突明显时，使用完整模板。
    • 对于快速请求，精简为：推断意图、分类、有证据支持的分类错误、同类型内的不足，以及最高优先级的改进建议。
    • 将分类错误与同类型内的执行不足分开。

Required review checks

必备评审检查项

When reviewing, explicitly check these areas when relevant:
  • Primary vs secondary surface clarity
    • Is the CLI clear about what the main surface is?
    • Are secondary surfaces real contracts or just informal add-ons?
  • Discoverability
    • Does help output support the claimed user type?
    • Are examples, option descriptions, and command structure aligned with the CLI's center of gravity?
  • Structured output contract
    • Are JSON / JSONL / field-selection / exit-code surfaces explicit and stable?
    • Are unknown fields rejected or silently tolerated?
    • Is the machine surface strong enough for the claims made in docs?
  • Risk model
    • Are low-, medium-, and high-risk actions meaningfully separated?
    • Are confirm / dry-run / preview / audit guardrails aligned with the risk profile?
  • State model
    • Is statefulness handled correctly?
    • Are attach/detach/resume/session/history concepts used only when justified?
  • v1 discipline
    • Does the CLI keep a coherent v1 boundary?
    • Does it introduce premature abstraction or missing contracts?
评审时，相关情况下需明确检查以下领域：
  • 主次界面清晰度
    • CLI是否明确了主界面是什么？
    • 次要界面是正式契约还是非正式附加功能？
  • 可发现性
    • 帮助输出是否符合声称的用户类型需求？
    • 示例、选项描述和命令结构是否与CLI的核心定位一致？
  • 结构化输出契约
    • JSON/JSONL/字段选择/退出码界面是否明确且稳定？
    • 是否拒绝或默默容忍未知字段？
    • 机器界面是否符合文档中声称的能力？
  • 风险模型
    • 低、中、高风险操作是否有明确区分？
    • 确认/试运行/预览/审计等防护措施是否与风险概况匹配？
  • 状态模型
    • 状态性处理是否正确？
    • 附加/分离/恢复/会话/历史等概念是否仅在必要时使用？
  • v1版本准则
    • CLI是否保持连贯的v1版本边界？
    • 是否引入了过早抽象或缺失契约？

Review rules

评审规则

  • Do not grade every CLI on an agent-first curve.
  • Do not require raw payloads, full schema introspection, or machine-first output unless the classification justifies them.
  • Treat modern CLIs as multi-surface systems: one primary role, one primary interaction form, optional secondary surfaces.
  • Prefer strong inference, then targeted confirmation.
  • When criticizing machine support, specify whether the problem is:
    • missing primary/secondary surface clarity,
    • weak machine contract,
    • or a true category mismatch.
  • 不要用Agent优先的标准来评判所有CLI。 除非分类要求，否则不要强制要求原始负载、完整 schema 自省或机器优先输出。
  • 将现代CLI视为多界面系统：一个主要角色、一个主要交互形式、可选次要界面。
  • 优先进行有力推断，然后进行针对性确认。
  • 批评机器支持时，明确说明问题是：
    • 缺少主次界面清晰度，
    • 机器契约薄弱，
    • 还是真正的分类不匹配。

Handling hybrid CLIs

处理混合类型CLI

Some CLIs genuinely straddle multiple roles at the subcommand level.
Rules for hybrid CLIs:
  1. Classify at the product level first — what is the CLI's center of gravity?
  2. If subcommands clearly split into different roles, note the split explicitly.
  3. Name the primary role (the one that defines the CLI's identity and design constraints).
  4. Name secondary roles as secondary surfaces with their own local constraints.
  5. Do not force a single role on a CLI whose subcommands genuinely serve different roles.
Example: Docker
  • Product-level primary role: Runtime (its center of gravity is container execution).
  • docker run
    , 
    docker exec
    , 
    docker attach
    → Runtime interaction.
  • docker image ls
    , 
    docker volume inspect
    → Capability-like resource surfaces (secondary).
  • docker compose up
    → Workflow/Orchestration (secondary).
Guidance for evolving CLIs:
  • If a CLI is migrating from one type to another, state the current center of gravity and the intended direction.
  • Do not classify based on the future target alone; classify based on current evidence and note the trajectory.
有些CLI在子命令级别确实跨越了多个角色。
混合类型CLI的规则：
  1. 先在产品层面分类 — CLI的核心定位是什么？
  2. 如果子命令明显属于不同角色，明确说明这种拆分。
  3. 命名主要角色（定义CLI身份和设计约束的角色）。
  4. 将次要角色视为具有自身局部约束的次要界面。
  5. 不要对子命令确实服务于不同控制界面的混合CLI强制赋予单一角色。
示例：Docker
  • 产品层面主要角色：运行时（核心定位是容器执行）。
  • docker run
    、
    docker exec
    、
    docker attach
    → 运行时交互。
  • docker image ls
    、
    docker volume inspect
    → 类能力型资源界面（次要）。
  • docker compose up
    → 工作流/编排（次要）。
CLI演进指南：
  • 如果CLI正从一种类型迁移到另一种类型，说明当前核心定位和预期方向。
  • 不要仅基于未来目标分类；基于当前证据分类并说明发展轨迹。

Common failure modes

常见失败模式

Watch for these mistakes:
  • Treating every CLI as a capability CLI.
  • Treating every CLI as a runtime CLI.
  • Treating TUI or REPL as a role instead of an interaction form.
  • Ignoring statefulness.
  • Ignoring risk profile.
  • Ignoring help/discoverability for human-primary CLIs.
  • Treating automation fitness as a top-level identity instead of a design consequence.
  • Forcing human-primary tools into agent-only patterns.
  • Calling a JSON surface “strong” without defining the contract.
  • Ignoring secondary surfaces in mixed-mode CLIs.
  • Jumping from classification directly to command trees without stating design stance.
  • Failing to mark v1 boundaries and non-goals.
  • Forcing a single role on a hybrid CLI whose subcommands genuinely serve different control surfaces.
  • Over-engineering statefulness for a CLI that only has durable config/lockfile side-effects but no true sessions.
  • Classifying a CLI by its future aspirations instead of its current evidence.
注意以下错误：
  • 将所有CLI视为能力型CLI。
  • 将所有CLI视为运行时型CLI。
  • 将TUI或REPL视为角色而非交互形式。
  • 忽略状态性。
  • 忽略风险概况。
  • 忽略人类优先CLI的帮助/可发现性。
  • 将自动化适配性视为顶级身份而非设计影响。
  • 将人类优先工具强制适配仅Agent模式。
  • 未定义契约就称JSON界面“强大”。
  • 忽略混合模式CLI的次要界面。
  • 直接从分类跳到命令树，未说明设计立场。
  • 未标记v1版本边界和非目标。
  • 对子命令确实服务于不同控制界面的混合CLI强制赋予单一角色。
  • 对仅具有持久配置/锁文件副作用但无真正会话的CLI过度设计状态性。
  • 基于未来期望而非当前证据对CLI进行分类。

Output bar

输出标准

Keep final outputs:
  • explicit about classification
  • explicit about classification reasoning when there is tension or ambiguity
  • explicit about evidence, confidence, and assumptions
  • explicit about design consequences
  • explicit about primary vs secondary surfaces
  • explicit about discoverability and machine contracts when relevant
  • explicit about risk ladders when mutations exist
  • scaled to the user's requested depth
  • concise but dense
  • diagnostic rather than generic
Avoid vague advice such as "improve UX" or "make it more agent-friendly" unless tied to a specific classification and a concrete design consequence.
最终输出需：
  • 明确分类
  • 存在冲突或模糊性时明确分类推理
  • 明确证据、置信度和假设
  • 明确设计影响
  • 明确主次界面
  • 相关时明确可发现性和机器契约
  • 存在修改操作时明确风险层级
  • 与用户要求的深度匹配
  • 简洁但信息密集
  • 具有诊断性而非泛泛而谈
避免模糊建议，如“改进UX”或“更适配Agent”，除非与特定分类和具体设计影响关联。