Agent Instructions for ms-swift

These instructions apply to all AI-assisted contributions to modelscope/ms-swift. Breaching these guidelines may result in your PR being closed. Read CONTRIBUTING.md (Chinese: CONTRIBUTING_CN.md) first.

1. Contribution Policy (Mandatory)

Human-submitted PRs

• Pure code-agent PRs are not allowed. A human submitter must understand and defend the change end-to-end.
• The pull request must be created and submitted by a human — never by an agent or an automated tool. The submission step always requires human involvement.
• The submitting human must review every changed line and run the relevant tests before submitting.

Issue first, then PR

• Link the related issue in the PR description if there is one (e.g. Fixes #123 for bug fixes, Refs #123 for features/RFCs).
• If this is a first-time contribution to ms-swift, open an issue first (using the issue templates). PRs from first-time contributors that do not link an issue may be closed directly.

Duplicate-work checks

Before proposing a PR, check whether an open PR already addresses the same fix:

gh issue view <issue-number> --repo modelscope/ms-swift --comments
gh pr list --repo modelscope/ms-swift --state open --search "<issue-number> in:body"
gh pr list --repo modelscope/ms-swift --state open --search "<short area keywords>"

• If an open PR already addresses the issue, do not open another one.
• If your approach is materially different, explain the difference in the issue first.

No low-value busywork PRs

• Do not open one-off PRs for tiny edits (single typo, isolated style change, "theoretical bug" without a real usage path). Bundle mechanical cleanups into a systematic change, or open an issue to discuss first.

Accountability

• PR descriptions for AI-assisted work must include:
  • The repository's PR template, filled in (.github/PULL_REQUEST_TEMPLATE.md: PR type, linked issue, checklist).
  • Test commands run and results; reproduction or experiment results when behavior changes (see ## Experiment results in the template).
  • A clear statement that AI assistance was used.
• If you cannot explain how the change works and why it is correct, do not submit it — maintainers may ask.

Fail-closed behavior

• If the work is duplicate or trivial busywork, do not proceed. Return a short explanation of what is missing instead of opening a PR.

2. Development Workflow

• Environment: develop against the repository checkout, not the released package — from the repo root run pip install -e . (or uv pip install -e . --torch-backend=auto), then install the test and lint dependencies: pip install -r requirements/tests.txt.
• Lint (required): pre-commit run --all-files — fix any reported errors until all checks pass (the CI lint job runs the same command).
• Docs: when user-facing behavior or APIs change, update both docs trees (English docs/source_en/, Chinese docs/source/) and keep paired top-level files in sync (README.md / README_CN.md).

• Commit attribution: when an AI tool contributed non-trivially, add attribution trailers such as:

  Co-authored-by: GitHub Copilot
  Co-authored-by: Claude

3. Policy Maintenance

• Editing these instructions: if a requested task conflicts with these rules, stop and explain the conflict — do not edit this file, CONTRIBUTING.md / CONTRIBUTING_CN.md, or the PR template to work around them. Changes to these files must go through normal human PR review.

Acknowledgements

Adapted from the vLLM project's AGENTS.md.