From be7804c699c70cb1d314ca9178889f1f82cc1430 Mon Sep 17 00:00:00 2001 From: Richard Levasseur Date: Thu, 22 Oct 2026 10:03:57 -0700 Subject: [PATCH] agents: add bazelrc rules and clarify script execution conventions Record learned repository invariants following BuildBuddy RBE optimization. Add rules for Bazel RC whitespace quoting, performance flag documentation, and invocation privacy. Clarify directly executable script requirements and prohibit redundant shell forwarders. --- .agents/rules/bazelrc.md | 18 ++++++++++++++++++ .agents/rules/python.md | 3 +++ .agents/rules/shell.md | 2 ++ .agents/rules/workspace.md | 7 ++----- 4 files changed, 25 insertions(+), 5 deletions(-) create mode 100644 .agents/rules/bazelrc.md diff --git a/.agents/rules/bazelrc.md b/.agents/rules/bazelrc.md new file mode 100644 index 0000000000..87135ce788 --- /dev/null +++ b/.agents/rules/bazelrc.md @@ -0,0 +1,18 @@ +--- +trigger: glob +description: Bazel configuration (.bazelrc) rules and conventions +globs: "*.bazelrc,.bazelrc" +--- + +# Bazelrc Rules + +* **Quote Values with Spaces**: Wrap flag values containing spaces in double + quotes (e.g., `--build_metadata="KEY=value with spaces"`). Unquoted spaces + cause Bazel's rc parser to treat subsequent words as build targets. +* **Document Performance Flags**: Document performance-tuning flags (e.g., + `--remote_cache_compression`, `--experimental_remote_cache_chunking`, + `--rewind_lost_inputs`) with inline comments explaining their concrete + benefit. +* **Invocation Privacy**: Keep local invocations private. Never add + `--build_metadata=VISIBILITY=PUBLIC` to repository-level or user bazelrc + files; configure public visibility and CI metadata only in CI. diff --git a/.agents/rules/python.md b/.agents/rules/python.md index 9921b5a597..38006fd0f9 100644 --- a/.agents/rules/python.md +++ b/.agents/rules/python.md @@ -20,6 +20,9 @@ globs: "*.py,*.sh" * Factor non-trivial scripts (such as multi-line Python or shell logic) into standalone files (e.g. `.py` or `.sh` files) instead of inlining them via heredocs (`<< 'EOF'`) or `-c` flags (`python3 -c`, `bash -c`). +* **Directly Executable Scripts**: Scripts executed directly (outside a + `py_binary` rule) must have `chmod +x` (mode `100755`) and a + `#!/usr/bin/env python3` shebang. ## Interface & ABC Docstrings * In abstract base class / interface methods, always document `Args:`, diff --git a/.agents/rules/shell.md b/.agents/rules/shell.md index 015a0a2ecd..faa2022490 100644 --- a/.agents/rules/shell.md +++ b/.agents/rules/shell.md @@ -11,3 +11,5 @@ globs: "*.sh" with `while IFS= read -r file; do ...; done < "$manifest"`. Do not use unquoted command substitution (`$(cat "$manifest")`) or suppress ShellCheck `SC2046` assuming paths lack spaces. +* Do not create companion `.sh` forwarders that merely pass `"$@"` to another + executable or script. diff --git a/.agents/rules/workspace.md b/.agents/rules/workspace.md index 7f87eba3b2..0259910035 100644 --- a/.agents/rules/workspace.md +++ b/.agents/rules/workspace.md @@ -11,11 +11,8 @@ basis: * Fetch `upstream/main` (`git fetch upstream main`). * Base any new branch or worktree upon `upstream/main` (e.g., `git checkout -b upstream/main`). -* Run the workspace helper script to configure upstream tracking and safe - pushing: - ```bash - .agents/scripts/setup_client.py - ``` +* Run `.agents/scripts/setup_client.py ` to configure upstream tracking, + safe pushing, and client `user.bazelrc`. * Never use `git push -u` or `--set-upstream` (it breaks upstream tracking). * When pushing to a checked-out PR branch from an external fork, push explicitly to that remote (`git push HEAD:`). Do not rely on