| --- | |
| trigger: glob | |
| description: Cross-language code style, control flow, and CLI conventions | |
| globs: "*.py,*.rs,*.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 | |
| * Trace existing call graphs and check what inputs downstream functions and | |
| rules already accept before adding new rules, wrapper macros, format | |
| converters, or attributes. Wire new inputs into the existing pipeline at the | |
| narrowest seam. | |
| * Do not modify existing code or behavior unless strictly required; justify | |
| every modified line in existing files. | |
| * Keep parameter, return, and collection element types uniform across all | |
| callers (e.g., always `list[str]`, never `str | list[str]`; always a | |
| `struct`, never `str | struct`). Do not add runtime type branches to accept | |
| inconsistent caller or test inputs; fix callers and test fixtures to pass the | |
| uniform type instead. | |
| * Keep functions small and focused on a single step; decompose multi-stage | |
| functions into named helpers with documented `Args:` and `Returns:`. | |
| * 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. | |
| * When an object, field, or return value contains relative paths, document what | |
| each path is relative to. | |
| ## 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 `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. |