dev-cli-consistency-audit

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

CLI Consistency Review

CLI工具一致性审查

Systematic review of a CLI tool's command interface to ensure consistent naming, conventions, and documentation alignment.

对CLI工具的命令界面进行系统性审查，确保命名、约定和文档的一致性。

Workflow

工作流程

Step 1: Inventory Commands

步骤1：梳理命令清单

Run the CLI with
```
--help
```
or
```
-h
```
to get the top-level command list
For each subcommand, run
```
<cmd> <subcmd> --help
```
to get its full interface
Build an inventory table:

| Command       | Positional Args  | Flags              | Output Formats |
|---------------|------------------|--------------------|----------------|
| pull          | owner/repo       | --issues, --prs    | table, json    |
| search        | [query]          | --type, --limit    | fzf            |
| prune         | owner/repo       | --confirm, --dry-run| table         |

运行CLI工具的
```
--help
```
或
```
-h
```
命令获取顶层命令列表
对于每个子命令，运行
```
<cmd> <subcmd> --help
```
以获取其完整界面
构建清单表格：

| Command       | Positional Args  | Flags              | Output Formats |
|---------------|------------------|--------------------|----------------|
| pull          | owner/repo       | --issues, --prs    | table, json    |
| search        | [query]          | --type, --limit    | fzf            |
| prune         | owner/repo       | --confirm, --dry-run| table         |

Step 2: Convention Analysis

步骤2：约定分析

Check for consistency across all commands:

Positional vs Flag arguments:
- Is the same concept (e.g.,
```
owner/repo
```
  ) passed as positional in some commands and as
```
--repo
```
  flag in others?
- Recommendation: Pick one approach and apply everywhere
Flag naming:
- Are similar concepts named consistently? (e.g.,
```
--output
```
  vs
```
--format
```
  vs
```
-o
```
  )
- Do boolean flags follow the same pattern? (
```
--dry-run
```
  vs
```
--confirm
```
  vs
```
--yes
```
  )
- Are shorthand flags (
```
-f
```
  ,
```
-o
```
  ) assigned consistently?
Pluralization:
- Subcommand names: singular vs plural (e.g.,
```
list files
```
  vs
```
list file
```
  )
- Flag names:
```
--issue
```
  vs
```
--issues
```
Default behaviors:
- Are defaults consistent? (e.g., if one command defaults to
```
--format=table
```
  , do others?)
- Are destructive commands safe by default? (require
```
--confirm
```
  or
```
--force
```
  )
Error messages:
- Do error messages follow a consistent format?
- Are they actionable (tell the user what to do)?

检查所有命令的一致性：

位置参数与标志参数：
- 同一个概念（如
```
owner/repo
```
  ）在某些命令中作为位置参数，而在其他命令中作为
```
--repo
```
  标志传递？
- 建议：选择一种方式并全局应用
标志命名：
- 相似概念的命名是否一致？（例如
```
--output
```
  vs
```
--format
```
  vs
```
-o
```
  ）
- 布尔标志是否遵循相同模式？（
```
--dry-run
```
  vs
```
--confirm
```
  vs
```
--yes
```
  ）
- 简写标志（
```
-f
```
  ,
```
-o
```
  ）的分配是否一致？
单复数形式：
- 子命令名称：单数 vs 复数（例如
```
list files
```
  vs
```
list file
```
  ）
- 标志名称：
```
--issue
```
  vs
```
--issues
```
默认行为：
- 默认设置是否一致？（例如，如果某个命令默认使用
```
--format=table
```
  ，其他命令是否也如此？）
- 破坏性命令默认是否安全？（是否需要
```
--confirm
```
  或
```
--force
```
  确认）
错误消息：
- 错误消息是否遵循统一格式？
- 是否具备可操作性（告知用户应采取的措施）？

Step 3: Documentation Alignment

步骤3：文档对齐检查

Compare the README documentation with actual
```
--help
```
output:
- Are all commands documented?
- Do the documented flags match the actual implementation?
- Are examples up to date and runnable?
Check help text quality:
- Does each command have a one-line description?
- Are flag descriptions clear and consistent in style?
- Do examples in
```
--help
```
  text work?

比较README文档与实际
```
--help
```
输出：
- 所有命令是否都有文档说明？
- 文档中记录的标志是否与实际实现一致？
- 示例是否是最新且可运行的？
检查帮助文本质量：
- 每个命令是否有一行简短描述？
- 标志描述是否清晰且风格一致？
- ```
--help
```
  文本中的示例是否可用？

Step 4: Report

步骤4：生成审查报告

Present findings:

CLI Consistency Review:

Inconsistencies Found:
1. [Issue] — [Commands affected] — [Suggested fix]
2. ...

Documentation Gaps:
1. [What's missing] — [Where]
2. ...

Recommendations:
1. [Convention to adopt] — [Rationale]
2. ...

呈现审查结果：

CLI Consistency Review:

Inconsistencies Found:
1. [Issue] — [Commands affected] — [Suggested fix]
2. ...

Documentation Gaps:
1. [What's missing] — [Where]
2. ...

Recommendations:
1. [Convention to adopt] — [Rationale]
2. ...

Step 5: Apply Fixes

步骤5：应用修复

For each accepted fix:

Update the command implementation (flag names, defaults, etc.)
Update help text and descriptions
Update README to match
Run
```
--help
```
again to verify alignment

对于每个已确认的修复项：

更新命令实现（标志名称、默认设置等）
更新帮助文本和描述
更新README文档以保持一致
再次运行
```
--help
```
验证对齐情况

Best Practices Reference

最佳实践参考

Positional arguments: Use for the primary subject (e.g.,
```
owner/repo
```
). Limit to 1-2 positional args.
Flags: Use for modifiers and options. Always provide
```
--long-form
```
; add
```
-s
```
shorthand only for frequently used flags.
Boolean flags: Use
```
--flag
```
to enable (default off). For "default on" behaviors, use
```
--no-flag
```
to disable.
Output format: If supporting multiple formats, use
```
--format=table|json|yaml
```
consistently.
Destructive operations: Default to dry-run or require explicit
```
--confirm
```
.
Verbosity: Use
```
--verbose
```
/
```
-v
```
consistently. Consider
```
--quiet
```
/
```
-q
```
as well.

位置参数：用于主要操作对象（如
```
owner/repo
```
）。限制为1-2个位置参数。
标志：用于修饰符和选项。始终提供
```
--long-form
```
长格式；仅为高频使用的标志添加
```
-s
```
简写形式。
布尔标志：使用
```
--flag
```
启用（默认关闭）。对于“默认开启”的行为，使用
```
--no-flag
```
来禁用。
输出格式：如果支持多种格式，统一使用
```
--format=table|json|yaml
```
。
破坏性操作：默认设置为试运行（dry-run）或要求显式的
```
--confirm
```
确认。
详细程度：统一使用
```
--verbose
```
/
```
-v
```
。也可考虑添加
```
--quiet
```
/
```
-q
```
。

Examples

示例

Example 1: Full CLI review

User: "review our cli arguments and make sure they are aligned"
Action:
1. Run --help for all commands
2. Build inventory table
3. Identify naming inconsistencies
4. Check README alignment
5. Present report with specific fixes

Example 2: Pre-release check

User: "make sure our command implementation and comments are aligned"
Action:
1. Compare help text with actual behavior
2. Verify README examples work
3. Check for undocumented flags
4. Update docs to match implementation

示例1：完整CLI审查

User: "review our cli arguments and make sure they are aligned"
Action:
1. Run --help for all commands
2. Build inventory table
3. Identify naming inconsistencies
4. Check README alignment
5. Present report with specific fixes

示例2：发布前检查

User: "make sure our command implementation and comments are aligned"
Action:
1. Compare help text with actual behavior
2. Verify README examples work
3. Check for undocumented flags
4. Update docs to match implementation