For Python projects. Update 20260506.

AGENTS.md

Repository Guidelines

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

1. Think Before Coding

Don't assume. Don't hide confusion. Surface tradeoffs.

Before implementing:

• State your assumptions explicitly. If uncertain, ask.
• If multiple interpretations exist, present them - don't pick silently.
• If a simpler approach exists, say so. Push back when warranted.
• If something is unclear, stop. Name what's confusing. Ask.

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" or "configurability" that wasn't requested.
• No error handling for impossible scenarios.
• If you write 200 lines and it could be 50, rewrite it.

Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify.

3. Surgical Changes

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

When editing existing code:

• Don't "improve" adjacent code, comments, or formatting.
• Don't refactor things that aren't broken.
• Match existing style, even if you'd do it differently.
• If you notice unrelated dead code, mention it - don't delete it.

When your changes create orphans:

• Remove imports/variables/functions that YOUR changes made unused.
• Don't remove pre-existing dead code unless asked.

The test: Every changed line should trace directly to the user's request.

4. Goal-Driven Execution

Define success criteria. Loop until verified.

Transform tasks into verifiable goals:

• "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 brief plan:

1. [Step] → verify: [check]
2. [Step] → verify: [check]
3. [Step] → verify: [check]

Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification.

Goal: Keep changes small, avoid unnecessary rewrites, and clarify ambiguity before implementing.

Scope, Docs, and Environment

• User instructions override this guide; this guide overrides generic defaults.
• Save generated markdown under doc/; save plans under doc/plans/ and archive finished plans under doc/plans/archive/.
• Prefix generated markdown filenames with YYYYMMDD; reports must be Markdown and include exact reproducibility commands.
• Assume no sudo; keep installs user-local and reproducible. Prefer mamba, standalone binaries, conda, uv, then pip.
• Run checks in the same environment as the user's workflow. If the authoritative environment is unclear, ask.

Code Standards

• Python targets 3.11+. Use ruff and pyright from pyproject.toml.
• Keep reusable logic in importable modules under src/; keep runnable scripts thin and under domain-specific src/ subfolders.
• Prefer clear typed Python: pathlib, f-strings, explicit names, no wildcard imports, guarded entry points, and Google-style docstrings for public APIs.
• Use logging.getLogger(__name__) for production code and include stable identifiers when useful.

Verification

• Run the smallest meaningful verification for the change.
• During Python iteration, run ruff check <changed_files> --fix and ruff format <changed_files>.
• Add pytest tests for reusable/shared logic; one-off scripts may use lightweight validation.
• Run full ruff, pyright, and python -m pytest before handoff for shared/core logic, multi-file changes, or behavior changes.
• Report type-check pass/fail when pyright is relevant.

Project-Specific Constraints

• For iEnigma usage, follow /home/jhuang/project/NER_label_extraction/doc/iEnigma_v1.0_readme.md; if inaccessible, ask for constraints.
• Never commit secrets. Keep large generated artifacts in designated output folders such as result/, do not commit caches/temp/env folders, and update .gitignore for new artifact patterns.
• For commits, PRs, pushes, merges, and GitHub work, use the installed git workflow skills and ask for approval before mutating remote or commit history.