[go: up one dir, main page]

P2MUST

Structured, Parseable Output

Definition

CLI tools MUST separate data from diagnostics and offer machine-readable output formats. Mixing status messages with data forces agents into fragile regex extraction that breaks on any format change.

Why Agents Need It

An agent calling a CLI needs three things from each invocation: the data, the error (if any), and the exit code. When data goes to stdout, diagnostics go to stderr, and errors carry machine-readable fields, the agent parses the result reliably without heuristics. Mix these channels or ship human-formatted output only, and the agent falls back to best-effort text parsing that fails unpredictably across versions, locales, and edge cases: silently at first, catastrophically later.

Audited live by anc audit <tool> --principle 2: behavioral and source checks.

Requirements

Evidence

Rust reference implementation:

Anti-Patterns

Measured by audit IDs p2-json-output, p2-structured-output, p2-output-module, p2-structured-exit-codes, p2-json-errors, p2-schema-print, p2-consistent-envelope, p2-schema-file, p2-json-aliases, p2-more-formats, p2-raw-flag. Run anc audit --principle 2 . against the CLI under test to see each.