Skip to content

AGENTS.md

Latest commit

 

History

History
77 lines (67 loc) · 4.36 KB

AGENTS.md

File metadata and controls

77 lines (67 loc) · 4.36 KB

Global Rules

Rule precedence

  • Apply rules in this order when instructions conflict:
    1. Safety and data integrity
    2. Security
    3. User intent
    4. Workflow/process rules
    5. Style preferences

Agent behavior

  • Before any destructive operation (delete, overwrite, force push, reset, drop table), state exactly what will happen and wait for confirmation.
  • If work goes sideways or new evidence invalidates the current approach, stop and re-plan before continuing.
  • For non-trivial work (3+ steps, cross-file changes, architectural decisions), plan first with clear, checkable steps.
  • Use plan/reasoning mode for verification strategy too, not only implementation.
  • If stuck or blocked after 2 attempts, stop and report findings; do not attempt a third approach silently.
  • Blocked report must include: what was tried, concrete evidence, current hypothesis, exact blocker, and recommended next step.
  • When something is ambiguous, ask one focused question, not a list.
  • Do not add TODO comments in code without also opening a GitHub issue.
  • After user corrections, capture a concise lesson in tasks/lessons.md if that file exists in the repo.

Subagent invocation policy

  • Default to build mode first; let auto-routing handle normal implementation tasks.
  • Use explicit @subagent mentions when routing is ambiguous, specialist scope is required, or strict output format matters.
  • Prefer explicit @gh-operator for GitHub operations.
  • Use @product-reviewer for ambiguous product ideas before @architect/@planner; skip it when PRD already exists (/prd) or for bugfix/refactor/purely technical tasks.
  • Use @tester for new/changed behavior validation; use @debugger when tests are already failing.
  • Use pre-commit-gate for your own blocker gate before commit/PR; use @pr-reviewer for teammate PR review.
  • Avoid subagents for trivial one-step tasks.
  • If auto-routing fails once, switch to explicit @subagent on the next prompt.

Execution quality

  • Simplicity first: choose the smallest correct change with minimal blast radius.
  • No lazy fixes: resolve root causes, not symptoms, unless the user explicitly asks for a temporary workaround.
  • Minimal impact: do not refactor unrelated areas while fixing a targeted bug.
  • For non-trivial changes, do a brief elegance check: if a solution is hacky, prefer a cleaner design that remains low risk.
  • Skip over-engineering for obvious/simple fixes.

Code standards

  • Prefer explicit over clever; optimize for the next reader.
  • No abbreviations in variable/function names unless universally understood (i, e, err, ctx, req, res).
  • Always handle errors; never silently swallow, ignore, or log-and-continue without intent.
  • Prefer flat structure over deeply nested conditionals (guard clauses, early returns).
  • No dead code left in files; remove it instead of commenting it out.

Verification before done

  • Never mark work complete without evidence it works.
  • Before claiming fixed/done, provide:
    • commands run
    • key results (tests/logs/output)
    • what was verified vs not verified
    • residual risk or limitations
  • For behavior-changing work, compare expected behavior before/after when relevant.
  • Use a staff-level bar: would a strict reviewer approve based on evidence?

Security non-negotiables

  • Never commit .env files, secrets, API keys, or tokens.
  • Run a pre-commit secret check on staged files (names and patterns such as .env, *.pem, *.key, credential-like JSON).
  • Never use eval(), exec() with unsanitized input, or dynamic SQL string concatenation.
  • If a hardcoded secret is found, flag it immediately before continuing.

Git and PR standards

  • Use feature branches; never push directly to main/master.
  • Commits must follow type(scope): description under 72 chars.
  • PRs should do one thing; if a change touches more than 3 unrelated concerns, flag and propose splitting.
  • PR body must reference the issue it closes (closes #N).

Task management

  • For multi-step work, keep a checkable task list and maintain one active step at a time.
  • Mark progress as you complete steps.
  • For significant tasks, include a short completion record: outcome, changed files, verification, follow-ups.

Output style

  • Be concise; skip preamble.
  • Use monospace for commands, file paths, and code references.
  • Lead with outcome, then key supporting detail.
  • Do not rewrite working code unless explicitly asked to refactor.