[DOCS] Potential CI/CD hangs and missing safety flags in "Unix-style utility" documentation

Documentation Type

Unclear/confusing documentation

Documentation Location

URL: https://code.claude.com/docs/en/common-workflows

Section/Topic

Section: Use Claude as a unix-style utility -> Add Claude to your verification process

Current Documentation

The documentation suggests adding a linting script to package.json:

// package.json
{
    ...
    "scripts": {
        ...
        "lint:claude": "claude -p 'you are a linter. please look at the changes vs. main and report any issues related to typos. report the filename and line number on one line, and a description of the issue on the second line. do not return any other text.'"
    }
}

What's Wrong or Missing?

The provided example is risky for CI/CD environments and automated pipelines for the following reasons:

1. Potential for Hanging: While -p (print mode) is intended to be non-interactive, the documentation does not mention that Claude may still encounter states where it awaits permission or hits a loop. In a headless CI environment, this can cause the pipeline to hang indefinitely.
2. Missing Security/Safety Flags: For a script intended to run in a "verification process" (typically CI), the example lacks safety arguments like --max-turns (to prevent infinite loops/cost spikes) and --allow-dangerously-skip-permissions (to ensure the agent doesn't stop to ask for confirmation in a non-interactive shell).
3. Deprecation Context: Per Changelog version 1.0.113, piped input in interactive mode has been deprecated. While this example uses a string prompt, developers often combine this with cat file | claude -p, and the docs should clarify the preferred method for passing local context in headless mode to avoid "broken" states.

Suggested Improvement

Add a warning regarding CI/CD usage and update the code example to include safety flags that ensure the process exits cleanly.

Suggested Text:

Note on CI/CD Usage: When running Claude Code in non-interactive environments (like GitHub Actions or Jenkins), always include --max-turns to prevent infinite loops and ensure you have configured appropriate permissions. If your environment is secure and isolated, you may need --allow-dangerously-skip-permissions to prevent the process from hanging on a permission prompt.

Updated Example:

"scripts": {
    "lint:claude": "claude -p '...your prompt...' --max-turns 2 --allow-dangerously-skip-permissions"
}

Impact

High - Prevents users from using a feature

Additional Context

• Changelog 1.0.113: Explicitly mentions "Deprecated piped input in interactive mode."
• CLI Reference: States that -p is for querying via SDK and exiting, but doesn't explicitly warn that it might still wait for tool approvals if not configured with skip-permission flags.
• Comparison: Similar tools (like certain linters or CLI wrappers) usually provide a "CI mode" or "non-interactive" flag that defaults to failing rather than waiting for input; Claude Code requires explicit configuration to achieve this.