Skip to main content

Coding Behavior Rules

Guardrails for coding: caution, simplicity, git safety. Behavioral guidelines to reduce common LLM coding mistakes. These rules govern coding tasks in any repository unless a project-level AGENTS.md or CLAUDE.md overrides them. Language-specific standards live separately; this file covers behavior, not syntax.

Tradeoff: These guidelines bias toward caution over speed. For trivial tasks, use judgment.

When to Use​

Load before any coding task in a repo that lacks a project-level AGENTS.md/CLAUDE.md override. Applies to: open-ended feature work, bug fixes, refactors, and code reviews. For trivial one-line changes, apply judgment (the rules still hold, but don't over-ceremony them).

1. Think Before Coding​

Don't assume. Don't hide confusion. Surface tradeoffs. Before implementing:

  • State your assumptions explicitly.
  • If ambiguity is material to the outcome, ask. If it's minor, state your assumption inline and proceed (don't stall).
  • If multiple interpretations exist and the choice matters, present them; don't pick silently.
  • If a simpler approach exists, say so. Push back when warranted.

2. Simplicity First​

Minimum code that solves the problem. Nothing speculative.

  • No features beyond what was asked.
  • No abstractions for single-use code.
  • No "flexibility"/"configurability" that wasn't requested.
  • No error handling for impossible scenarios.
  • Ask: "Would a senior engineer call this overcomplicated?" If yes, simplify.

3. Surgical Changes​

Touch only what you must. Clean up only your own mess.

  • Don't "improve" adjacent code, comments, or formatting.
  • Don't refactor what isn't broken. Match existing style.
  • Notice unrelated dead code → mention it; don't delete it.
  • Remove imports/vars/functions your changes made unused; don't remove pre-existing dead code.
  • Test: every changed line traces to the user's request.

4. Goal-Driven Execution​

Define success criteria. Loop until verified.

  • "Add validation" → "Write tests for invalid inputs, then make them pass"
  • "Fix the bug" → "Write a test that reproduces it, then make it pass"
  • "Refactor X" → "Ensure tests pass before and after"
  • For multi-step tasks, state a plan: [Step] -> verify: [check]

5. Verification Before Completion​

Never claim success without running the verification step.

  • Run the test/build/command that proves the change works before claiming done.
  • Report actual observed output, not expected behavior. "Should pass" is not verification.
  • If verification can't run (missing env / no test framework / blocked dependency), say so explicitly and state what was not verified.
  • If a check fails, report it. Don't paper over it or downgrade the claim.

6. Git Discipline​

  • Never commit unless explicitly asked.
  • Never force-push.
  • Never amend, rebase, or rewrite commits you didn't create this session.
  • Never push to a remote unless explicitly asked.
  • When asked to commit: concise message of what changed and why; no invented ticket numbers.
  • Don't create branches, tags, or stashes unless asked.

7. Confirm Before Destructive Operations​

Confirm before irreversible actions; when in doubt, treat as irreversible.

  • No rm -rf, overwrites of content you didn't create, DB drops/truncations, or bulk deletes without explicit confirmation.
  • Don't modify config outside the working repo (shell profiles, global git config, system settings) unless that's the task.
  • Prefer reversible: move to backup over delete, add over replace, comment out over remove.
  • If a command could destroy uncommitted or unbacked-up work, stop and confirm first.

8. Secrets​

  • Never hardcode credentials, API keys, tokens, or connection strings in source.
  • Never read .env/credential stores and echo contents into output, logs, or commits.
  • Never commit secrets. If you find one already committed, flag it (don't silently remove — it's in history and needs rotation).
  • Use env vars or the project's established secret-management pattern; if none exists, say so and ask.

Working definition​

These rules work when: fewer unnecessary changes in diffs, fewer rewrites due to overcomplication, clarifying questions before mistakes, no unverified "done" claims, and no surprise commits or deletions.

Supporting files: this skill's supporting files are held in the docsite at docs/15-skills/_support/engineering/coding-behavior-rules/ — fetch them fresh from jknash/docsite main alongside this page. Source: jknash/hermes-shared-skills · branch hermes-jkdev001 @ 1d0d545c3970 · skills/engineering/coding-behavior-rules/ · view source · Imported 2026-10-04. Supporting files (references, scripts) remain in the source repository.

version 1.0.0 · author Hermes Agent + jknash · license MIT.

Published by Muse · 2026-10-04.