From 166376676b20b2953cd989f5cd1cf8dfa76e6034 Mon Sep 17 00:00:00 2001
From: Ryan Yin <xiaoyin_c@qq.com>
Date: Tue, 25 Aug 2026 17:07:53 +0800
Subject: [PATCH] docs(agents): clarify command waiting and environment rules

---
 agents/AGENTS.md | 39 ++++++++++++++++++++++++++-------------
 1 file changed, 26 insertions(+), 13 deletions(-)

diff --git a/agents/AGENTS.md b/agents/AGENTS.md
index 262864c1..0dfd2d12 100644
--- a/agents/AGENTS.md
+++ b/agents/AGENTS.md
@@ -1,7 +1,6 @@
-# RULES - Global Agent Baseline
+# Personal Global Agent Rules
 
-This file defines the cross-project baseline for AI coding agents. It focuses on safety, boundaries,
-and portable behavior.
+This file defines my global defaults and safety boundaries for coding agents.
 
 ## 1) Instruction Priority
 
@@ -10,7 +9,7 @@ Apply instructions in this order:
 1. Runtime system/developer instructions
 2. User task request
 3. Project-local policy (`AGENTS.md`, `CLAUDE.md`, repo docs)
-4. This global RULES
+4. These global rules
 
 If rules conflict, follow the higher-priority source and state the conflict briefly.
 
@@ -22,10 +21,10 @@ If rules conflict, follow the higher-priority source and state the conflict brie
   - Examples: `git push`, creating/updating remote PRs/Issues via `gh`.
 - MUST NOT auto-run remote-mutating commands unless explicitly requested.
   - Examples: `kubectl apply/delete`, `helm upgrade`, `terraform apply`, remote `ssh` mutation.
-- MUST NOT perform destructive/irreversible operations or use force options, even if explicitly
-  requested (e.g. `rm -rf`, `terraform destroy`).
-  - MAY perform verified, recoverable cleanup when explicitly requested (e.g. `git branch -d` for a
-    fully merged branch).
+- MUST NOT perform destructive or irreversible operations, or use force options (e.g. `rm -rf`,
+  `terraform destroy`).
+- MAY perform explicitly requested, verified, and recoverable cleanup (e.g. `git branch -d` for a
+  fully merged branch).
 - MUST NOT expose or commit secrets (tokens, keys, kubeconfig credentials, passwords).
 
 ## 3) Security and Secrets Handling
@@ -60,19 +59,33 @@ If rules conflict, follow the higher-priority source and state the conflict brie
 
 ## 6) Tooling Defaults
 
-- Use Bash only for quick one-offs, Nushell for personal tooling, Python for everything else.
+- Use Nushell for personal tooling, Bash for simple one-off commands, and Python for scripts or
+  complex control flow.
 - Prefer structural search tools first for code find/replace (`ast-grep`/`jq`/`yq`), then text tools
   (`rg`, `fd`).
 - Prefer project task runners (`just`, `make`, `npm scripts`, etc.) over ad-hoc commands when
   equivalent.
-- Only use `nix run`, `flake.nix`/`shell.nix`, or `uv`/`pnpm` for missing commands & packages.
-  Otherwise, ask the user—never use another installer.
-- Use `gh` CLI for GitHub operations, especially code/PR/issue search and inspection.
+- On NixOS, do not assume FHS paths or conventional system/package installers: they may not work and
+  can pollute the managed environment. For missing tools or dependencies, use `nix run`, the
+  project's flake/dev shell, or its existing `uv`/`pnpm` workflow; otherwise, ask the user.
+- Use `gh` CLI for authorized GitHub operations, especially code/PR/issue search and inspection.
+- Keep waits bounded and observable: avoid long uninterrupted sleeps and unbounded loops.
+- For waits or potentially blocking operations, use short polling intervals with progress output and
+  explicit timeouts or bounds; do not treat a timeout as proof that the underlying process is still
+  running. Prefer Python over Bash for custom polling logic.
+- For subprocesses that may fork or daemonize, verify that inherited stdout/stderr pipes cannot keep
+  the parent blocked; avoid unconditional `capture_output` when output is not needed.
 
 ## 7) Environment Defaults
 
 - Primary OS: NixOS & macOS.
 - Shell: default to Nushell, Bash also exists.
+- Common project locations:
+  - Open-source project sources: `~/codes/src/`
+  - Personal Git repositories: `~/codes/`
+  - Work-related projects: `~/work/`
+- These paths are location hints only; access them only when they are explicitly in scope or
+  approved.
 
 ## 8) Script Engineering Principles
 
@@ -87,7 +100,7 @@ Treat scripts as interruptible jobs that must be diagnosable and safe to rerun:
 
 ## 9) Communication Defaults
 
-- Respond in the language the user is currently using, prefer English & Chinese.
+- Respond in the user's language; prefer English or Chinese.
 - Code, commands, identifiers, and code comments: Prefer English.
 - Be concise, concrete, and action-oriented.