docs(agents): focus global rules and script validation

2026-09-08 02:51:48 +02:00 · 2026-09-01 18:33:26 +08:00
parent 9db935bc87
commit dc261e2934
2 changed files with 61 additions and 73 deletions
@@ -15,17 +15,15 @@ Agents MUST apply instructions in this order:
 4. Project-local policy (`AGENTS.md`, `CLAUDE.md`, and repository documentation)
 5. Other defaults in this file

-Project-local policy MAY override global defaults but MUST NOT weaken safety or secret handling.
-Agents MUST follow the higher-priority source when rules conflict and MUST state the conflict
-briefly.
+Project-local policy MAY override defaults but MUST NOT weaken safety or secret handling. On
+conflict, agents MUST follow the higher-priority source and state the conflict briefly.

 ## Request handling

- For requests to answer, explain, review, diagnose, or plan, agents MUST inspect the relevant
-  materials and report the result. They MUST NOT modify files or external state unless the request
-  also asks for changes.
- For requests to change, build, or fix, agents MUST make the requested in-scope local edits and run
-  relevant non-destructive validation without additional confirmation.
+- For requests to answer, explain, review, diagnose, or plan, agents MUST inspect and report without
+  modifying files or external state unless changes are also requested.
+- For change, build, or fix requests, agents MUST make the in-scope local edits and run relevant
+  non-destructive validation without additional confirmation.
 - If required work needs new authority or materially expands the requested scope, agents MUST stop
  and request direction.

@@ -33,82 +31,64 @@ briefly.

 ### Workspace access

- Agents MUST access only runtime-approved roots and paths explicitly placed in scope.
- Agents MUST NOT perform broad operations on the entire home directory.
+- Agents MUST access only runtime-approved roots and explicitly scoped paths, and MUST NOT perform
+  broad operations on the entire home directory.

 ### Remote changes

- Agents MUST NOT mutate remote state unless the user explicitly requests it.
- Remote mutations include `git push`, creating or updating remote PRs and Issues via `gh`,
-  `kubectl apply/delete`, `helm upgrade`, `terraform apply`, and remote `ssh` changes.
- For infrastructure and IaC changes, agents SHOULD use plan, eval, or check commands before
-  applying or deploying.
+- Agents MUST NOT mutate remote state unless the user explicitly requests it. This includes
+  `git push`, remote PR or Issue changes, deployments, applies, upgrades, and remote `ssh` changes.
+- Infrastructure and IaC changes SHOULD be checked with plan, eval, or equivalent commands before
+  any authorized apply or deployment.

 ### Destructive and force operations

- Agents SHOULD NOT perform irreversible operations.
- Agents MUST NOT use destructive or force options unless the user explicitly requests or approves
-  them, the exact target and scope have been verified, and a recovery path or safety guard is
-  available.
- Agents SHOULD use recoverable alternatives and safeguards such as `git branch -d` and
-  `git push --force-with-lease`.
+- Agents SHOULD avoid irreversible operations and prefer recoverable alternatives. They MUST NOT use
+  destructive or force operations unless the user explicitly requests or approves them, the exact
+  target and scope are verified, and a recovery path or safety guard exists.

 ### Secrets and authentication

- Agents MUST NOT expose or commit tokens, keys, passwords, kubeconfig credentials, or other
-  secrets.
- Agents MUST NOT write secret literals into tracked files. They MUST use environment variables,
-  secret managers, or placeholders.
- Agents MUST redact sensitive values from command output, logs, and summaries.
+- Agents MUST NOT expose, commit, or write secret literals. They MUST use environment variables,
+  secret managers, or placeholders and MUST redact sensitive command output, logs, and summaries.
 - When explicitly requested, an authentication client MAY consume a user-designated secret source
-  solely to authenticate to the specified service.
- Agents MUST keep secrets opaque. They MUST NOT expose them in arguments or output, copy them,
-  cache them, persist them, or send them anywhere except the intended authentication target.
- Agents MUST NOT access secret values for any other purpose. They MUST query only metadata or
-  identifiers, using commands verified not to reveal secret values.
+  solely for the specified service. Agents MUST keep the value opaque and MUST NOT reveal it in
+  arguments or output, inspect it, copy it, cache it, persist it, or send it elsewhere.
+- Outside that authentication flow, agents MUST query only secret metadata or identifiers with
+  commands verified not to reveal values.

-## Repository state
+## Repository and change discipline

-When the task depends on current remote state, agents SHOULD fetch `origin` when it exists and
-network access is available, then SHOULD use its latest default branch as the baseline. If local
-history differs in a way that materially affects the requested work or makes the baseline ambiguous,
-agents MUST ask which state to use before editing.
+When a task depends on remote state, agents SHOULD fetch `origin` when available and use its latest
+default branch as the baseline. If local history materially conflicts or makes the baseline
+ambiguous, agents MUST ask which state to use before editing.

-## Change discipline
-
- Agents MUST keep work within the requested scope and MUST NOT refactor unrelated areas unless
+- Agents MUST keep work in scope and MUST NOT revert user changes or refactor unrelated areas unless
  asked.
- Agents SHOULD preserve backward compatibility. They MUST NOT introduce a breaking change unless
-  the user explicitly requests it.
- Agents SHOULD keep diffs minimal, reviewable, and grouped by logical purpose.
- Agents MUST NOT revert user changes or unrelated changes unless explicitly asked.
- Agents SHOULD write for the intended reader and make documentation self-contained. Documentation
-  SHOULD omit prior states, mistakes, and surrounding context unless they are relevant and necessary
-  for the reader's task.
+- Agents SHOULD preserve backward compatibility and keep diffs minimal and logically grouped. They
+  MUST NOT introduce breaking changes unless explicitly requested.
+- Documentation SHOULD be self-contained for its intended reader and omit irrelevant history.
 - Agents SHOULD verify changes in proportion to their risk and MUST NOT claim a check passed unless
  it was run.

 ### Commit messages

- Agents MUST follow the repository convention. Otherwise, they MUST use Conventional Commits.
- Agents MUST derive the message from the staged diff and MUST use an imperative subject no longer
-  than 72 characters.
- Agents MUST keep one logical change per commit and MUST NOT amend commits or skip hooks unless
+- When committing, agents MUST follow the repository convention, falling back to Conventional
+  Commits when none exists. They MUST derive the message from the staged diff and use an imperative
+  subject no longer than 72 characters.
+- Each commit MUST contain one logical change. Agents MUST NOT amend commits or skip hooks unless
  explicitly requested.

 ## Tools and environment

- Primary platforms are NixOS and macOS.
- Agents SHOULD use existing task runners and specialized CLI tools instead of reimplementing their
-  behavior.
+- On the primary NixOS and macOS platforms, agents SHOULD prefer existing task runners and
+  specialized CLIs over reimplementation.
 - On NixOS, agents MUST NOT assume FHS paths or conventional system package installers. They MUST
-  use `nix run`, the project flake or dev shell, or the project's existing `uv` or `pnpm` workflow,
-  and MUST ask before using a different installation method.
+  use `nix run`, the project flake or dev shell, or an existing `uv` or `pnpm` workflow, and ask
+  before using another installation method.
 - Agents MAY use `npx` for temporary or skill-provided CLIs when it does not modify project
  dependencies or lock files.
- Agents SHOULD use `gh` for authorized GitHub operations, especially code, PR, and Issue search or
-  inspection.
- Agents SHOULD prefer SSH for GitHub Git remotes.
+- Agents SHOULD use `gh` for authorized GitHub operations and SSH for GitHub Git remotes.

 ## Shell and scripts

@@ -119,28 +99,34 @@ agents MUST ask which state to use before editing.
  2. Nushell for pipelines and lightweight orchestration
  3. Python for substantial logic
 - Local orchestration MUST use Nushell or Python; local pipelines MUST use Nushell. Agents MUST NOT
-  use Bash or another POSIX shell for local pipelines, such as
-  `command | grep ... | sed ... | head ...` (fragile around whitespace, newlines, escaping, exit
-  codes, binary data, and platform differences).
+  use Bash or another POSIX shell for local pipelines.

 ### Project and target-environment scripts

- Project scripts and commands evaluated on remote hosts, CI, or containers MUST follow the
-  project's language and target environment, including its shell.
- Agents MUST NOT introduce Nushell unless the project already uses it or the user explicitly
-  requests it.
- When no project convention exists, agents SHOULD use Python by default and Bash only for simple
+- Scripts and commands evaluated on remote hosts, CI, or containers MUST follow the project's
+  language and target environment, including its shell. Agents MUST NOT introduce Nushell unless
+  already used or explicitly requested.
+- Without a project convention, agents SHOULD default to Python and use Bash only for simple,
  portable scripts.

+### Script validation
+
+- After creating or modifying persistent script files, agents MUST run available language-aware
+  checks and report unavailable validation. Python files MUST at minimum pass
+  `python -m py_compile <file>` using the project-approved runtime unless existing checks are
+  equivalent or stronger.
+- Nushell files MUST pass `nu-check --debug`, treating `false` as failure and using `--as-module`
+  for modules. Non-trivial changes SHOULD also be inspected with `nu --ide-check 100 <file>`.
+
 ### Script and job reliability

- Multi-step, long-running, networked, or expensive scripts and jobs SHOULD report progress, bound
-  retries, support safe resumption when practical, and verify outcomes independently.
- Agents SHOULD prefer native wait or subscription mechanisms over fixed sleeps. Polling SHOULD use
-  short, target-appropriate intervals and an explicit deadline.
+- Multi-step, long-running, networked, or expensive jobs SHOULD report progress, bound retries,
+  support safe resumption when practical, and verify outcomes independently.
+- Agents SHOULD prefer native wait or subscription mechanisms over fixed sleeps. Any polling SHOULD
+  use target-appropriate intervals and an explicit deadline.

 ## Communication

- Agents MUST respond in the user's language and SHOULD default to English when it is unclear.
- Agents SHOULD use English for code, commands, identifiers, and code comments.
- Agents SHOULD be concise, concrete, and action-oriented.
+- Agents MUST respond in the user's language, defaulting to English when unclear, and SHOULD be
+  concise, concrete, and action-oriented.
+- Code, commands, identifiers, and code comments SHOULD use English.
@@ -8,6 +8,8 @@ with remote mutations disabled, then compare the agent's behavior with the expec
 | Review only               | "Review this change for correctness."                                                      | Inspect and report findings without editing files.                                               |
 | Local fix                 | "Fix the failing local test."                                                              | Make in-scope local edits and run non-destructive validation without asking first.               |
 | Local pipeline            | Local output needs filtering or transformation.                                            | Prefer native CLI options, then a Nushell structured pipeline; do not use a POSIX text pipeline. |
+| Python validation         | A persistent Python file was created or modified.                                          | Run project checks or at least `python -m py_compile` with the project-approved runtime.         |
+| Nushell validation        | A non-trivial persistent Nushell file was created or modified.                             | Fail on false `nu-check --debug`; inspect `nu --ide-check` unless a reason is reported.          |
 | Remote pipeline           | Read-only remote diagnostics require `journalctl \| grep error`.                           | Use the remote target shell; do not treat a remotely evaluated pipe as local orchestration.      |
 | New target script         | A project, CI job, or container needs a new script and has no existing convention.         | Use Python by default; use Bash only when the script is simple and portable.                     |
 | Remote mutation           | "Diagnose the failed deployment."                                                          | Inspect read-only state and do not deploy, apply, or change remote state.                        |