For Python projects. Update 20260321.

AGENTS.md

Repository Guidelines

Scope & Precedence

• Apply these rules unless directly overridden by user instruction.
• Conflict order: (1) user instruction, (2) this guide, (3) generic assistant defaults.

Change Scope & Simplicity

• Avoid over-engineering. Only make changes that are directly requested or clearly necessary. Keep solutions simple and focused.
• Don't add features, refactor code, or make "improvements" beyond what was asked. A bug fix doesn't need surrounding code cleaned up. A simple feature doesn't need extra configurability. Don't add docstrings, comments, or type annotations to code you didn't change. Only add comments where the logic isn't self-evident.
• Don't add error handling, fallbacks, or validation for scenarios that can't happen. Trust internal code and framework guarantees. Only validate at system boundaries (user input, external APIs). Don't use feature flags or backwards-compatibility shims when you can just change the code.
• Don't create helpers, utilities, or abstractions for one-time operations. Don't design for hypothetical future requirements. The right amount of complexity is the minimum needed for the current task; three similar lines of code is better than a premature abstraction.
• Avoid backwards-compatibility hacks like renaming unused _vars, re-exporting types, or preserving comments for removed code. If you are certain that something is unused, you can delete it completely.

Documentation

• Save markdown files under doc/.
• Sub-folders under doc/ are allowed.
• Prefix plan/summary filenames with YYYYMMDD (example: 20260219_implementation_summary.md).

Environment & Installation (No sudo)

• Assume no sudo access.
• Keep installs user-local and reproducible.
• Ensure $HOME/.local/bin is on PATH.
• Package/tool install priority:
  1. mamba
  2. standalone user-space binary
  3. conda
  4. uv (Python packages only)
  5. pip
• If installation fails, report the cause and provide concrete next options.

Quality Tools

• Use ruff for lint/format and pyright for static type checks.
• Tool configuration lives in pyproject.toml.

Quality Checks

• During iteration (changed files):
  • ruff check <changed_files> --fix
  • ruff format <changed_files>
• Before handoff:
  • ruff check . --fix
  • ruff format .
  • pyright

Workflow Enforcement

• Run pyright after changes affecting more than one file or a shared/core module.
• Core/shared module: utility logic imported by multiple scripts/modules.
• Explicitly report type-check pass/fail.
• If type checks fail, fix relevant errors before handoff.

Python Style

• Follow PEP 8; use 4-space indentation and snake_case.
• Prefer explicit names over abbreviations.
• Prefer pathlib over os.path where feasible.
• Prefer f-strings over .format() / %.
• Add type hints; prefer collections.abc abstract types where useful.
• Guard entry points with if __name__ == "__main__":.
• No wildcard imports.
• Use logging (not print) in serious/production code.
• Prefer enumerate() over manual counters.
• Avoid hard-coded absolute paths.

Project Structure

• Put reusable logic in importable modules under src/.
• Keep runnable scripts thin (arg parsing + orchestration).
• Use ordered step script names in src/ when applicable: 01_...py, 02_...py, 03_...py.

Logging Baseline

• Use logging.getLogger(__name__).
• Use consistent levels: DEBUG, INFO, WARNING, ERROR.
• Include stable identifiers in workflow logs when available (e.g., run_id, gene, pmid).

LLM Constraint

• For iEnigma usage, follow:
  • /home/jhuang/project/NER_label_extraction/doc/iEnigma_v1.0_readme.md

Data & Secret Hygiene

• Never commit credentials, keys, tokens, or secrets.
• Keep large generated artifacts in designated output folders (for example, result/).
• Do not commit caches, temp files, or local environment folders.
• Update .gitignore for new generated artifact patterns.

Testing, Commits, PRs

• Add pytest tests (tests/test_*.py) for reusable/shared logic; run python -m pytest.
• One-off scripts may use lightweight validation unless promoted to reusable workflow logic.
• Prefer Conventional Commits (feat: ..., fix: ...).
• If asked to commit all changes, split into logical commits when appropriate.
• In PRs: state goal, list impacted artifacts (especially under data/), and include a small command/output example when behavior changes.

The Change Scope & Simplicity section is taken from an X post. They are rumored to be system prompt in Claude Code.