|
| 1 | + AGENT SAFEGUARDS (non-negotiable) |
| 2 | + |
| 3 | +Operating principles |
| 4 | +1) Prefer clear code over comments. |
| 5 | + - Use comments only for: non-obvious reasoning, security invariants, protocol quirks, or “why” that code cannot express. |
| 6 | + - Prefer descriptive names, small functions, and explicit types over commentary. |
| 7 | + |
| 8 | +2) Solve root cause, not band-aids. |
| 9 | + - Do not add retries/timeouts/logging to hide failures unless the root cause is addressed or explicitly impossible to fix. |
| 10 | + - If a workaround is necessary, document the root cause and the exact reason it can’t be fixed now. |
| 11 | + |
| 12 | +3) Use idioms of the language and ecosystem. |
| 13 | + - Follow standard style guides, conventions, directory layout, and tooling. |
| 14 | + - Avoid clever patterns that fight the ecosystem. Prefer boring, maintainable solutions. |
| 15 | + |
| 16 | +Quality gates |
| 17 | +4) Tests must run after each modification. |
| 18 | + - After any functional change, run the relevant test suite locally (or in CI steps) and ensure it passes. |
| 19 | + - If tests cannot run (missing dependency, environment), add or update a runnable test harness or clearly state what is required. |
| 20 | + - Never leave the repo in a state where tests are known failing. |
| 21 | + |
| 22 | +5) Documentation for all features. |
| 23 | + - Every new feature must have usage docs + one runnable example. |
| 24 | + - Docs must include intent, flags/config, and failure modes. |
| 25 | + - Prefer docs that answer user questions (“How do I…”) and include copy/paste snippets. |
| 26 | + |
| 27 | +6) Update CHANGELOG with all changes. |
| 28 | + - Every user-visible change must be added to CHANGELOG.md under “Unreleased”. |
| 29 | + - Use categories: Added / Changed / Fixed / Security / Deprecated / Removed. |
| 30 | + - Mention migration steps if behavior changes. |
| 31 | + |
| 32 | +Robustness & correctness |
| 33 | +7) Include error handling everywhere it matters. |
| 34 | + - Never ignore errors; propagate with context. |
| 35 | + - Wrap/annotate errors so the caller has actionable info. |
| 36 | + - Ensure exit codes/return values are correct and consistent. |
| 37 | + |
| 38 | +8) Test edge cases and invariants. |
| 39 | + - Add tests for: empty inputs, invalid inputs, boundary values, timeouts, large payloads (reasonable), and concurrency/ordering if relevant. |
| 40 | + - Include at least one test for each bug fixed to prevent regressions. |
| 41 | + |
| 42 | +Security & safety (important for agentic tooling) |
| 43 | +9) No harmful actions by default. |
| 44 | + - Do not delete data, rotate secrets, publish releases, or mutate external systems unless explicitly requested. |
| 45 | + - Treat external calls (network, cloud APIs) as “dangerous”: require explicit opt-in via config/flags. |
| 46 | + |
| 47 | +10) Least privilege and safe defaults. |
| 48 | +- Minimize permissions, capabilities, scopes, and access tokens. |
| 49 | +- For Kubernetes artifacts: runAsNonRoot, readOnlyRootFilesystem, allowPrivilegeEscalation=false, drop ALL capabilities unless justified. |
| 50 | + |
| 51 | +11) No secret leakage. |
| 52 | +- Never print tokens, passwords, or full credential material to logs. |
| 53 | +- Redact known secret patterns; avoid echoing env vars that might contain secrets. |
| 54 | + |
| 55 | +12) Deterministic builds and reproducibility. |
| 56 | +- Prefer pinned versions, lockfiles, and deterministic packaging. |
| 57 | +- Avoid “download latest at build time” unless necessary. |
| 58 | + |
| 59 | +Change management rules |
| 60 | +13) Small, reviewable diffs. |
| 61 | +- Prefer incremental changes with clear commit boundaries. |
| 62 | +- If a refactor is needed, do it in a separate commit/PR before feature changes. |
| 63 | + |
| 64 | +14) Respect existing standards and tooling. |
| 65 | +- Use the repo's existing lint/format/test tools (Makefile/package scripts/cargo test/etc.). |
| 66 | +- If tooling is missing, add it in a minimal conventional way. |
| 67 | + |
| 68 | +15) Provide a “How to verify” section in PR descriptions/output. |
| 69 | +- Include exact commands: build, lint, unit tests, integration tests (if any). |
| 70 | + |
| 71 | +Agent execution constraints (for local runners / GH actions) |
| 72 | +16) Only modify files that are in-scope for the task. |
| 73 | +- Do not reformat unrelated files. |
| 74 | +- Do not introduce new dependencies unless justified. |
| 75 | + |
| 76 | +17) When uncertain, choose the safer option and make it explicit. |
| 77 | +- Prefer failing fast with actionable errors over silent fallback. |
| 78 | +- If ambiguity remains, implement a guardrail and document the decision. |
| 79 | + |
| 80 | +18) When really uncertain, ask for help. |
| 81 | +- Avoid making assumptions without asking for confirmation. |
| 82 | + |
| 83 | +19) When running locally, prefer the mcp edit tool to direct file edits. |
| 84 | +- If issues arise where files seems unedited, alert the user before continuing |
| 85 | + |
| 86 | +20) Prefer bash commands/scripts to python3 when investigating |
| 87 | + |
| 88 | +Definition of done |
| 89 | +- Code compiles. |
| 90 | +- Code is formatted. |
| 91 | +- Tests pass. |
| 92 | +- Docs updated. |
| 93 | +- CHANGELOG updated. |
| 94 | +- Edge cases tested. |
| 95 | +- Security posture maintained. |
| 96 | +- Output includes a concise summary of changes + how to verify. |
0 commit comments