Back to Details

agent-native-cli

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Agent-Native CLI

Agent原生CLI

Treat the command/tool boundary as an interface for an agent, not just a way to expose shell commands.
将命令/工具的边界视为Agent的交互接口，而非仅仅是暴露Shell命令的方式。

Core approach

核心方法

When designing or reviewing a workflow:
  1. Inspect the repository's existing commands, scripts, CI, and development conventions first.
  2. Identify repeated multi-step operations and mechanical work.
  3. Move deterministic work out of the model and into scripts, Make targets, or higher-level CLI commands.
  4. Give the agent a small, semantic command surface.
  5. Minimize output crossing the tool → model boundary.
  6. Return only information needed for the agent's next decision.
  7. Use structured output when the agent needs to inspect fields or make decisions.
  8. Use exit codes and explicit failure semantics for machine-detectable outcomes.
  9. Make side effects, required inputs, and destructive behavior explicit.
  10. Keep commands discoverable and composable.
  11. Preserve human usability; do not optimize for agents by making normal development harder.
设计或评审工作流时：
  1. 首先检查仓库现有命令、脚本、CI及开发规范。
  2. 识别重复的多步操作与机械性工作。
  3. 将确定性工作从模型中迁移至脚本、Make目标或更高层级的CLI命令中。
  4. 为Agent提供精简的语义化命令界面。
  5. 尽量减少跨工具→模型边界的输出内容。
  6. 仅返回Agent做出下一步决策所需的信息。
  7. 当Agent需要检查字段或做出决策时，使用结构化输出。
  8. 使用退出码与明确的失败语义实现机器可检测的结果。
  9. 明确标注副作用、必填输入及破坏性操作。
  10. 确保命令具备可发现性与可组合性。
  11. 保留人类易用性；切勿为了适配Agent而增加常规开发的难度。

Important distinction

重要区别

Optimize both sides of the boundary:
text
Action compression:
agent → one semantic command → many deterministic operations

Observation compression:
many lines of tool output → small decision-relevant result → agent
Short commands alone are not enough. A command that returns thousands of irrelevant lines can still be expensive for an agent.
同时优化边界的两端：
text
Action compression:
agent → one semantic command → many deterministic operations

Observation compression:
many lines of tool output → small decision-relevant result → agent
仅缩短命令长度是不够的。一个返回数千行无关内容的命令对Agent而言仍会产生高额成本。

Agent vs deterministic tooling

Agent与确定性工具

Keep the agent responsible for decisions that require context or judgment:
text
Agent:
what should happen?
when should it happen?
which option is appropriate?

Deterministic tooling:
how should the known procedure execute?
what exact commands are required?
how should known results be summarized?
Do not hide meaningful decisions inside scripts merely to reduce model interaction.
让Agent负责需要上下文判断的决策：
text
Agent:
应该执行什么操作？
何时执行该操作？
哪个选项更合适？

Deterministic tooling:
已知流程应如何执行？
需要哪些具体命令？
已知结果应如何汇总？
切勿仅仅为了减少模型交互，就将有意义的决策逻辑隐藏在脚本中。

Output contract

输出约定

Prefer a deliberate separation between the primary agent-facing result and diagnostics:
text
stdout → compact result / next-decision information
exit code → machine-detectable success or failure
stderr/logs → detailed diagnostics when needed
Do not discard actionable errors merely to reduce tokens. Preserve a path to full diagnostics without forcing them into every successful tool response.
建议明确区分面向Agent的核心结果与诊断信息：
text
stdout → 精简结果 / 下一步决策所需信息
exit code → 机器可检测的成功或失败状态
stderr/logs → 必要时提供详细诊断信息
切勿仅为了减少令牌消耗而丢弃可操作的错误信息。在不强制将诊断信息加入每次成功响应的前提下，保留获取完整诊断信息的途径。

Design checklist

设计检查清单

For each candidate command, consider:
  • Is the operation deterministic enough to move outside the model?
  • Can several low-level commands become one semantic operation?
  • What is the smallest useful input surface?
  • What decisions still belong to the agent?
  • What output does the agent actually need?
  • Can stdout be reduced without hiding important failures?
  • Should the result be structured?
  • Are exit codes meaningful?
  • Are side effects explicit and safe?
  • Can detailed diagnostics be retrieved separately?
  • Can the agent discover how to use it without reading implementation details?
  • Does the interface remain convenient for humans?
针对每个候选命令，需考虑：
  • 该操作是否足够确定，可迁移至模型外部执行？
  • 多个底层命令能否整合为一个语义化操作？
  • 最小可用的输入界面是什么？
  • 哪些决策仍需由Agent负责？
  • Agent实际需要哪些输出内容？
  • 能否在不隐藏重要失败信息的前提下精简stdout？
  • 结果是否应采用结构化格式？
  • 退出码是否具备明确含义？
  • 副作用是否明确且安全？
  • 能否单独获取详细诊断信息？
  • Agent无需查看实现细节就能掌握命令的使用方法吗？
  • 该接口对人类用户是否依然便捷？

Working method

工作流程

When asked to improve a repository:
  1. Inspect before changing.
  2. Reuse existing repository mechanisms where practical.
  3. Identify a small set of high-value workflows.
  4. Implement the smallest useful command surface.
  5. Preserve existing behavior and CI unless the task explicitly calls for a change.
  6. Document the command contract and discoverability path.
  7. Measure the result separately; do not claim token savings without an actual measurement.
当需要优化仓库时：
  1. 先检查再修改。
  2. 尽可能复用仓库现有机制。
  3. 识别一小部分高价值工作流。
  4. 实现最小可用的命令界面。
  5. 除非任务明确要求变更，否则保留现有行为与CI流程。
  6. 记录命令约定与可发现路径。
  7. 单独测量优化结果；未经实际测量，请勿宣称实现了令牌节省。

References

参考资料

Read these when relevant:
  • references/command-abstraction.md
  • references/compact-output.md
  • references/structured-output.md
  • references/deterministic-workflows.md
相关场景下可阅读：
  • references/command-abstraction.md
  • references/compact-output.md
  • references/structured-output.md
  • references/deterministic-workflows.md

Do not over-engineer

避免过度设计

Prefer existing repository mechanisms first. A Make target, shell script, package script, or small CLI command is often enough. Do not introduce a framework merely to satisfy this skill.
优先采用仓库现有机制。一个Make目标、Shell脚本、包脚本或小型CLI命令通常已足够满足需求。切勿仅仅为了适配此技能而引入框架。