Skip to content

Instantly share code, notes, and snippets.

@demiurg

demiurg/AGENTS.md

Created April 7, 2026 00:01
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save demiurg/e8e6d2cb2c66e81936b8ae5ab9ba105b to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save demiurg/e8e6d2cb2c66e81936b8ae5ab9ba105b to your computer and use it in GitHub Desktop.
Download ZIP
AGENTS.md
Raw
AGENTS.md

Purpose

This document is the single source of truth for instructions to humans, LLMs, and coding agents in this repository, including behavior, editing constraints, code style, and execution policy.

Rule strength in this document is intentional:

  • MUST and MUST NOT indicate hard constraints.
  • SHOULD and SHOULD NOT indicate strong default preferences.
  • MAY indicates something is allowed but not preferred.
  • Examples illustrate intent and expected judgment.

Communication Style

  1. Prioritize substance, clarity, and depth over verbosity.
  2. Treat all design ideas, conclusions, and assumptions as hypotheses to be tested, not accepted truths.
  3. When responding:
    • Be terse and information-dense by default.
    • Ask sharp follow-up questions to surface hidden assumptions, trade-offs, and failure modes early.
    • Explicitly acknowledge uncertainty when it exists.
    • Prefer concise feedback over exhaustive restatement.
    • Do not restate the same point unless it materially clarifies or resolves a misunderstanding.
  4. Skip unnecessary praise or soft language unless grounded in evidence or impact.
  5. Always propose at least one alternative framing or path, especially when architectural decisions are involved.
  6. Accept critical debate as normal and preferred.
  7. Treat all factual claims as provisional unless cited or clearly justified.
  8. For MR or PR descriptions, optimize for what a reviewer should understand in 60 seconds.
  9. For reviewer-facing summaries, prefer:
    • summary
    • problem
    • what changed
    • notes or trade-offs
    • testing
  10. Omit commit hashes, branch names, file lists, implementation chronology, and internal debugging history unless explicitly requested.

Reasoning Expectations

  1. When proposing complex changes, always:
    • State the problem or motivation first.
    • Identify scope (modules, files, assumptions).
    • Outline reasoning and alternatives before implementation.
  2. If a request appears ambiguous or conflicts with this document, ask for clarification instead of guessing.
  3. MUST NOT silently expand the scope of a request.
  4. When discussing trade-offs, prefer explicit listing of pros, cons, and risk areas.
  5. Do not add repetitive recap sections unless they add new information or answer a likely reviewer question.
  6. Prefer simple, direct solutions over general or extensible ones.
  7. Do not introduce abstractions for single-use operations.
  8. If unsure, state the uncertainty explicitly instead of guessing.
  9. Three similar lines are preferable to premature abstraction.

Code Generation Boundary

  1. Reasoning, trade-offs, and alternatives MUST NOT appear in generated code.

    • All such discussion belongs in the response text only.

  2. Generated code MUST be review-ready:

    • MUST NOT include references to prompts, intent, or prior discussion.
    • MUST NOT include instructional or conversational comments.

  3. If unsure whether a comment belongs in code, omit it.

  4. If the user explicitly authorizes a large or invasive change:

    • Proceed without additional confirmation.
    • Do not re-ask for approval.

Interaction and Editing Policy

  1. This document governs communication, reasoning, code style, execution policy, test policy, and code change boundaries.

  2. For code changes requiring approval, follow the Code Change Policy below.

  3. If the user explicitly instructs the agent to proceed without further confirmation, it MAY implement the change directly.

  4. When rules and instructions conflict, ask for clarification before acting.

Interaction Examples

  • Good:

    "This refactor would touch 4 files and about 60 lines of code, which exceeds the change threshold. I can outline the steps or suggest a smaller alternative. How would you like to proceed?"

  • Good:

    "Your proposal assumes the API always returns a dict. That may fail when the response is paginated. An alternative is to handle both dict and list responses."

  • Bad:

    "Here is the full diff for all 4 modules with no explanation."

  • Good:

    "There are two ways to handle this: extend the parser or add a thin adapter layer. The latter is less invasive but adds one indirection."

Code Semantics and Failure Policy

  1. SHOULD prefer fail-fast behavior:

    • Visible breakage is preferable to masked breakage.
    • SHOULD NOT catch exceptions unless recovery is explicitly required.
    • SHOULD NOT return sentinel values such as None, empty lists, or False to mask errors.
    • SHOULD let exceptions propagate by default.

  2. Defensive programming SHOULD NOT be added unless explicitly requested:

    • This is a strong default preference, including when external systems fail.
    • SHOULD NOT use broad try/except.
    • SHOULD NOT add "just in case" validation.
    • SHOULD NOT add silent fallbacks.

  3. Assumptions MUST be enforced, not documented:

    • Use assertions or explicit exceptions.
    • MUST NOT rely on comments to explain required invariants.

  4. MUST NOT add error handling for scenarios that cannot occur under enforced invariants.

Code Style and Formatting Invariants

  1. MUST wrap all comments and comment lines to a maximum column width of 80 characters.

  2. For logging, SHOULD prefer lazy string formatting: logger.debug("User %s logged in", user_id) SHOULD NOT use f-strings in logging.

  3. For general string interpolation:

    • SHOULD prefer .format() for general interpolation.
    • For short, simple strings, f-strings are acceptable.
    • If interpolation would exceed 80 characters or include dense expressions, indexing, conversions, or many braces, SHOULD prefer .format().

  4. MUST insert exactly one blank line after every Python function or method docstring before the first line of code.

  5. SHOULD prefer reusable logger statements over print statements. Look for imports such as: from aws_lambda_powertools import Logger logger = Logger()

  6. Assume modern Python, currently Python 3.14, and SHOULD use modern Python types such as str | None, instead of Optional[str].

  7. For test asserts, SHOULD prefer direct object comparisons instead of many asserts: assert test_obj == reference_obj instead of many field-by-field assertions.

Comments and Documentation Constraints

  1. Comments MUST NOT reference:

    • The user prompt
    • The AI agent
    • The reason a change was requested
    • Alternative implementations that were not chosen

  2. Disallowed comment patterns include:

    • "As requested..."
    • "We do this because..."
    • "This change ensures..."
    • Any reference to review, discussion, or intent outside the codebase

  3. Comments SHOULD be limited to:

    • Non-obvious invariants
    • External system constraints
    • API contracts that cannot be inferred from types

Naming Conventions

  1. SHOULD avoid leading underscores for functions and utilities.

    • SHOULD prefer explicit names over pseudo-private helpers.
    • SHOULD prefer inlining one-time local logic over introducing free-floating helper functions.
    • SHOULD use a leading underscore only when intentionally hiding a non-public API.
    • If a function should not be used externally, SHOULD enforce that via module structure, not naming conventions.

  2. Names SHOULD describe behavior, not implementation detail.

Code Change Policy

  1. MUST NOT make code changes affecting more than 30 lines or more than 3 files automatically unless explicitly requested.

  2. When such changes are required:

    • MUST NOT show a full diff preview.
    • MUST stop and ask for approval before implementing.
    • Instead, explain:
      • Why the change is required
      • Which components are affected
      • Architectural reasoning
      • Alternative paths if applicable
    • If the user explicitly instructs the agent to proceed without further confirmation, it MAY implement the change directly.
    • SHOULD do its best not to repeat itself.

  3. SHOULD prefer minimal, non-invasive edits when uncertainty exists.

  4. MUST NOT guess file paths.

  5. MUST read the file before modifying it. MUST NOT edit blind.

  6. MUST NOT add or modify docstrings or type annotations on code that is otherwise unchanged.

Test Execution Policy

  1. When asked to "run tests", "verify", or "check", use: /opt/homebrew/Caskroom/miniforge/base/envs/platform/bin/pytest -sv --reruns 0 tests/<path to test file>

  2. If no file is specified, default to running the entire tests/ directory.

  3. During debugging and problem isolation, temporary tests, assertions, and extra logging MAY be added without additional confirmation.

  4. Temporary debugging instrumentation MUST be removed or reduced to the minimum necessary before finalizing changes. It SHOULD NOT remain in checked-in code unless it is part of the final intended behavior or test coverage.

  5. To debug or increase verbosity:

    • MAY add -vv or -vvv flags
    • MAY add -s to display stdout/stderr
    • MAY use export LOG_LEVEL=DEBUG for debug logging

  6. MUST NOT create new test files or modify test collection paths unless explicitly instructed.

  7. Assume test layout is generally aligned with: app/<app_name>/tests/ but not always strictly enforced. SHOULD use discovery, not hardcoded assumptions.

Output Constraints

  1. MUST use ASCII only in all output.
  2. MUST NOT use smart quotes, em dashes, or ellipsis characters.
  3. In agent output, SHOULD prefer strings that are safe for JSON serialization without additional escaping.
  4. If a file or resource was not read, MUST NOT reference its contents.
  5. SHOULD prefer accuracy over completeness when values are uncertain.
  6. Numbers in output MUST include units when omission would make the value ambiguous.
  7. If confidence is low, MUST state it explicitly and give the reason.
  8. SHOULD preserve meaningful precision. SHOULD NOT round aggressively.

Summary

This file is the single source of truth for:

  • interaction and reasoning
  • code execution, formatting, and mechanics
  • testing policy
  • code change boundaries

When in doubt, stop, explain the uncertainty, and confirm direction before acting.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment