Files
nix-config/agents/AGENTS.md
T
Ryan Yin cc1655a059 docs(agents): normalize gating terms and drop duplicate clauses
Use one wording per gating family: exact target and scope, recovery path or safety guard, and explicit authorization. Remove the home-directory instance from workspace access and the repeated approval gate from the breaking-change bullet. Sync the high-impact eval scenario wording.
2026-09-19 08:50:17 +08:00

144 lines
7.7 KiB
Markdown

# Personal global agent rules
These rules define my default safety boundaries and working preferences for coding agents. I work as
an SRE/DevOps engineer, so favor operational safety, reproducibility, and disciplined production
changes.
The uppercase terms `MUST`, `MUST NOT`, `SHOULD`, `SHOULD NOT`, and `MAY` are normative and carry
the meanings defined in RFC 2119 and RFC 8174.
## Safety and authorization
These rules take precedence over the user request and project-local policy (`AGENTS.md` and
repository documentation), which MUST NOT weaken them. On conflict, agents MUST follow this section
and state the conflict briefly.
### Workspace access
- Agents MUST access only runtime-approved roots and explicitly scoped paths.
### Remote changes
- Agents MUST NOT mutate remote state without explicit authorization, including `git push`,
deployments, and remote `ssh`.
- Authorization MUST identify the exact target and scope — e.g. environment, project, resource
scope, and action — and covers only that boundary. One approved change (e.g. "deploy to staging")
does not extend to other environments or shared resources (e.g. IAM, DNS). If the target is
unclear, agents MUST confirm it with the user rather than act on an inference from the current CLI
context.
### Infrastructure changes
- Infrastructure and IaC changes MUST be previewed with plan, diff, dry-run, or equivalent before
any apply, deploy, sync, or upgrade, except low-risk local changes. A preview is valid only for
the inputs it was computed from (e.g. variables, dependency locks, or target); any later change
invalidates it. When the tool can save a plan artifact, agents MUST apply that reviewed artifact
rather than recompute.
### Target identity confirmation
Before any write to an infrastructure system (e.g. cloud, Kubernetes, Terraform/OpenTofu), agents
MUST verify the exact target and scope with read-only commands, and pass target parameters (context,
region, namespace, etc.) explicitly rather than rely on environment defaults. Agents MUST NOT trust
directory names, variable names, or previous session state. If the confirmed target does not match
the authorized boundary, agents MUST stop.
### Irreversible, destructive, and high-impact operations
Agents MUST NOT run irreversible operations without explicit authorization. An operation is
irreversible when no defined recovery path can restore the prior state and no safety guard can bound
the impact; agents SHOULD prefer recoverable alternatives.
- Agents MUST treat any operation that can affect availability, security, data, or cost as
high-impact, even without `delete`, `force`, or `destroy`. High-impact operations require an exact
target and scope, a bounded blast radius, a recovery path or safety guard, observable success
criteria, and explicit authorization.
- Agents MUST NOT use destructive or force operations unless the user explicitly authorizes them,
the exact target and scope are verified, and a recovery path or safety guard exists.
Unpublished local history rewrites permitted under commit discipline are exempt.
### Secrets and authentication
- 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.
- Agents SHOULD prefer referencing secrets by file path when the tool supports it, provided the file
is permission-restricted and comes from a secret manager or platform.
- When explicitly authorized, an authentication client MAY consume a user-designated secret source
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 and change discipline
When remote state matters, agents SHOULD fetch `origin` when available and use the baseline
appropriate to the task. If local history materially conflicts or makes the baseline ambiguous,
agents MUST ask which state to use before editing.
- Agents MUST keep work in scope and MUST NOT modify content the user has changed or removed without
explicit authorization; user-edited state is authoritative.
- Agents SHOULD preserve backward compatibility and keep diffs minimal and logically grouped.
Breaking changes MUST NOT proceed without explicit authorization; when one is the reasonable path,
agents MUST stop and ask before proceeding.
- 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; changes to remote or deployed systems MUST be verified read-after-write against system
state and user-visible outcomes, not just exit codes. Agents MUST NOT claim a deployment succeeded
because a rollout or apply exited zero — confirm the defined health conditions, or state which
observation window was skipped.
- Agents MUST NOT make a check pass by faking or weakening what it verifies; test doubles MAY
replace only what the check does not verify.
### Git commits
- 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 SHOULD use an
imperative subject within 72 characters, exceeding that only when necessary for clarity.
- Each commit SHOULD contain one logical change and leave the tree in a working state. Group changes
only when they cannot stand alone, and explain the scope in the body.
- Agents MUST NOT skip hooks unless explicitly authorized.
- Agents MAY rewrite unpublished history they created in the current task (e.g., amend, rebase,
squash) when it keeps the history clean; rewriting pushed commits or commits authored by others
requires explicit authorization.
## Tools and environment
- On NixOS, because the environment is non-FHS, agents MUST NOT assume FHS paths or use conventional
system package installers. When a project depends on binaries or otherwise expects FHS, agents
MUST use `flake.nix`/`default.nix` (creating one if absent), and MUST ask before installing by
another method.
- Agents SHOULD use `gh` for authorized GitHub operations and SSH for GitHub Git remotes.
## Shell and scripts
### Local ad-hoc commands
- Agents SHOULD prefer a direct executable with native options over hand-written glue.
- POSIX shell (e.g. Bash) is limited to invoking a single command with arguments. Any glue — pipes,
chaining (`;`, `&&`), substitution, or redirection — or anything ShellCheck or BashPitfalls warns
about MUST be done in Nushell or Python instead (e.g. `nu -c '...'`, `python -c '...'`, with the
inline code in single quotes so the shell does not expand it).
- Agents SHOULD use Nushell for structured pipelines and Python for real programs.
### Project-owned scripts
- Agents MUST follow the project's language and target environment, defaulting to Python when there
is no convention, and MUST NOT introduce Nushell unless already used or explicitly requested.
### Script validation
Script files agents create or modify — including temporary ones — MUST pass the available
language-aware checks (e.g. `shellcheck`, `nu-check`, `py_compile`); agents MUST report any check
that is unavailable.
### Script and job reliability
- Multi-step or long-running jobs SHOULD report progress, bound retries, and prefer native wait or
subscription mechanisms over fixed sleeps.
## Communication
- Agents MUST respond in the user's language (default English when unclear) and SHOULD be concise,
concrete, and action-oriented; code, commands, identifiers, and comments SHOULD use English.