| --- | |
| trigger: glob | |
| description: Cross-language code style, control flow, and CLI conventions | |
| globs: "*.py,*.sh,*.cc,*.h,*.go,*.bzl,*.bazel,*.yaml,*.yml" | |
| --- | |
| # Code Style Rules | |
| ## File Organization & Definition Order | |
| Order definitions within a file as: | |
| 1. Global variables / constants | |
| 2. Flags / CLI arguments | |
| 3. Functions | |
| 4. Classes | |
| 5. Main | |
| ## Control Flow & API Design | |
| * Use early-return guard clauses over deeply nested conditionals. | |
| * When branching on validation modes, make the fall-off `else` the error case | |
| (fail-closed). | |
| * Accept one form per input (e.g., a file path, not "path or inline content"). | |
| Do not add unrequested modes, filters, knobs, or flag aliases. Create test | |
| fixture files instead of adding test-only code paths. | |
| * Use module constants directly instead of adding function parameters for values | |
| that never vary. | |
| * When exposing a private constant (`_NAME`) as public (`NAME`), update all | |
| internal callers to `NAME` and remove `_NAME = NAME` aliases. | |
| * Omit speculative precondition checks when the underlying operation fails | |
| clearly on its own. | |
| * Do not accept `None` or add `if x is not None` guards unless `None` is a valid | |
| domain state. | |
| * Do not write nested comprehensions or comprehensions with multiple `for` | |
| clauses; use explicit loops. | |
| * Avoid long or complex inline expressions (e.g. multi-condition ternaries, | |
| compound boolean chains, or dense one-liners). Break them into named | |
| intermediate variables, prior preparation steps, or explicit statements. | |
| ## CLI & Flags | |
| * Comment non-obvious flags (`--force`), non-default schemes, subtle arguments | |
| (such as significant trailing slashes), and timeouts/thresholds/retries. | |
| * Restrict constrained flag values strictly to the expected tokens (e.g., | |
| `true|false`) rather than permissive truthy/falsy sets. | |
| * Include `(AGENTS: requires user confirmation to use)` in `--help` text and | |
| error messages for CLI flags that bypass safety checks. | |
| ## Sorting | |
| * Add `keep-sorted start` and `keep-sorted end` markers on list and dict config | |
| or registry tables, even when they have a single entry. | |
| ## Bulk Logging | |
| * In bulk operations, log a single summary line on success; on failure, list | |
| each failing item sorted, one per line, with its location and reason. |