Skip to content

AGENTS.template.md

Latest commit

 

History

History
92 lines (70 loc) · 4.38 KB

AGENTS.template.md

File metadata and controls

92 lines (70 loc) · 4.38 KB
Raw

AGENTS.md (template)

Operating contract for AI agents working in this repository. Copy this file to AGENTS.md (and/or CLAUDE.md), then replace every <BRACKETED> value. Delete the sections that don't apply — but say so explicitly rather than leaving an agent to guess.

Keep AGENTS.md and any tool-specific copies byte-for-byte identical, and update them in the same commit. Don't fork the guidance per tool.

1. Credentials & secrets

  • Credentials live in <SECRET_SOURCE> (e.g. per-purpose env files, a secrets manager, a vault). Source only the narrowest credential that completes the task.
  • One scope per file/profile: <SCOPE_A> → <CRED_A>, <SCOPE_B> → <CRED_B>. Do not merge scopes into one shell.
  • Never echo, commit, or paste secret values into chat, PRs, commits, or tickets.
  • If a credential fails auth, stop and ask the user to rotate it. Do not fall back to a broader credential or an interactive browser/device-code login.
  • Admin-level credentials are sourced only when the user explicitly authorizes a specific privileged action, then dropped immediately afterward.

2. Environment safety

  • For any environment-specific write (cluster ops, DNS, releases, transactions), the target environment (<ENVIRONMENTS>) must be explicit before execution.
  • If the environment is unclear, ask one targeted question and wait. Do not assume a default. Read-only discovery is allowed while clarifying.
  • Never run a mutating command until the environment is unambiguous.

3. Change control (GitOps / pipeline-only)

  • Do not make persistent infrastructure changes by hand (no ad-hoc kubectl apply, no local terraform apply, no console clicks) as a normal workflow.
  • All changes land through a reviewed PR and are applied by <RECONCILER/PIPELINE> (e.g. Argo CD, Flux, a CI apply job) from the tracked branch.
  • If an emergency manual hotfix is unavoidable, immediately follow it with a PR that codifies the exact change and reconciles state back to Git.

4. Branch & PR workflow

  1. Start from <INTEGRATION_BRANCH> and pull latest.
  2. Create a short-lived feature branch (<BRANCH_PREFIX>/<topic>).
  3. Commit on the feature branch; push it.
  4. Open a PR targeting <INTEGRATION_BRANCH>; share the URL for review.
  • Never push directly to protected branches (<PROTECTED_BRANCHES>).
  • Treat feature branches as ephemeral; delete them after merge.

5. Environment promotion

  • Promote forward only: <ENV_1> → <ENV_2> → … → <ENV_N>.
  • Introduce new apps/config in the lowest environment first; never add something to a higher environment that doesn't yet exist below it.
  • Keep promotion PRs small and frequent to avoid drift and oversized change sets.

6. Parallel-agent isolation

  • Assume other agent sessions may be active at any time.
  • Bind each session to exactly one branch and one worktree path. Never mutate across branches from a shared clone.
  • Before any write, record a lock under <LOCK_DIR> with: session id, worktree path, branch, target environment, timestamp, intended task. One writer per branch/environment.
  • If a conflicting lock exists, stop and report it. Remove the lock when done.

7. Sub-agent orchestration

  • The main agent is a coordinator: delegate bounded discovery/validation/execution to focused sub-agents and keep its own context lean.
  • Return decisions and diffs to the main thread, not full intermediate logs.
  • Run independent subtasks in parallel; enforce the isolation rules above so concurrent work can't corrupt shared state.

8. Supply chain

  • Pull container images and charts only from <PRIVATE_REGISTRY>. Do not reference public registries in manifests, charts, or tooling.
  • Mirror upstream artifacts into a registry you control before depending on them.

9. Human-facing communication

  • Lead with the outcome ("done and verified", "blocked on X"), then detail.
  • Reference pull requests by full URL, not #123.
  • Plain language, active voice, no filler. Default to a short paragraph; expand only when asked or when enumerating.

10. Scope guardrails

  • Touch only what the task requires. One logical change per PR.
  • Before editing anything owned by another repo/team, identify the owner, read the existing pattern, and mirror it — don't invent or duplicate.
  • When unsure whether an action is in scope, stop and ask. Asking is cheaper than mis-targeting shared infrastructure.