Skip to content

AGENTS.md

Latest commit

 

History

History
47 lines (38 loc) · 8.17 KB

AGENTS.md

File metadata and controls

47 lines (38 loc) · 8.17 KB
Raw

AGENTS.md

Repo rules for AI agents working on qui.

Rules

  • Stay inside requested scope. Do not implement review-suggested/extra changes without explicit user approval. Keep diffs minimal in high-churn areas: internal/services/crossseed, internal/qbittorrent, internal/models.
  • Avoid repo-wide pnpm format / eslint --fix sweeps unless explicitly requested. Do not weaken, delete, or skip tests or lint rules to hide failures.
  • qui is single-user self-hosted software. Prefer readable, maintainable code over paranoid guards for impossible states. No backward compatibility shims unless requested.
  • Never add AI advertising, attribution, or co-author lines to a commit or a PR. Some agent tools add a co-author trailer by default.
  • Update PR branches by merging develop into them, never rebase/force-push. PRs are squash-merged, so rebase gains nothing and force-pushes break review history and contributors' local branches.
  • Never publish private tracker links or torrent names taken from a client. This covers PR and issue titles, bodies, and comments, commit messages, documentation/, and tracked files under docs/. No tracker URL that carries a path, query, or key: torrent pages, announce URLs, passkeys, .torrent links. Bare hostnames and tracker names stay allowed; the code and docs use them.
    • No release name copied word for word from a user report, a torrent client, Discord, or a DM. Build an equivalent name: keep each token that matters, change the title and the group. Make sure the new name still causes the bug before you publish it. Naming a work in prose, or building a name from a real title and group tag, is allowed. Keep the real string in notes outside the repo so the repro stays runnable. New test fixtures and code comments use built names. Do not sweep the existing ones.
    • A screenshot or a recording that you attach on GitHub, in a PR body or a comment, is public. Before you capture it, turn on incognito mode (the eye icon in the status bar of the torrent list). It replaces torrent names, trackers, categories, tags, and save paths with fake values. brrbin is private: only the maintainers can open an Evidence, so captures for brrbin can show the real values. In every capture, mask passkeys, announce URLs, and API keys.
  • Before each push that changes code, also a merge-conflict fix or a fix on a contributor's PR: make precommit and targeted tests for touched packages. Before the final report, also make build (frontend bundle + Go binary).
  • Go tests: always use -count=1. Leave -race to CI. Run the full suite (make test) locally only when asked, or when one change crosses many packages. API contract changes must update internal/web/swagger and pass make test-openapi and go test -count=1 -run TestAllEndpointsDocumented ./internal/api.
  • Before you report a code change complete, run it live: build and start the app (make build then the binary, or make dev) and exercise the behavior the change touches. Report the command and the output you observed. If the change needs human judgment (UI look and feel, real tracker behavior), ask the user to test it and say what remains for them. If a live run is not possible, say so and name the closest check you did run. In the final report, state required checks run, skipped/deferred checks with reason, and unresolved failures. Do not claim complete while a required repo check is known failing unless user accepts the risk.

Read When

  • Before you plan an issue or a pull request for your user, do the collaborator check in docs/agents/collaborator-check.md one time per session.
  • Before you commit, open a PR, add commits to one, post or apply a review suggestion, or show screenshots in a PR, read docs/agents/pull-requests.md. Before you open a PR or add commits to one, also do the performance checks in docs/agents/performance-checks.md for the full PR diff.
  • qui must work on Windows and Unix-like hosts. Before you write or review code that builds, compares, or validates a filesystem path, or a test of that code, read docs/standards/paths.md.
  • When you write or review code, follow the rules for its area in CODING_STANDARDS.md. Before changing cross-module data flow, service boundaries, API routing, or long-lived architecture, read docs/architecture.md.
  • Before you plan, edit, spec, or review a change to web/, i18n, React components, or frontend tests, read web/AGENTS.md. Before you change a locale file or a translation, also read web/src/i18n/AGENTS.md.
  • Before you change the database schema or a migration, read internal/database/AGENTS.md. Migration rules live there.
  • Read docs/linting.md when lint output is unclear or needs a policy judgment, and before you run a make lint target other than precommit, run scripts/ratchet, edit its allowlist, or move Go code into a new file.
  • Before you act on a Dependabot alert, or edit the Docker, compose, or release files at the repo root, read docs/agents/maintenance.md.
  • To read a bin.getqui.com link in a pull request, a Paste (/p/) or an Evidence (/e/), run brrbin fetch <link>. docs/agents/issue-tracker.md describes the sign-in and the files that the command writes.
  • Issue tracker: bug reports and feature requests are GitHub Discussions; a confirmed bug becomes a linked issue. See docs/agents/issue-tracker.md.
  • Triage: labels equal the six role names in docs/agents/triage-labels.md. Both the workflow and a local /triage session obey docs/agents/triage.md; its outcomes override the skill's own outcomes. Domain docs: GLOSSARY.md at the root, ADRs in docs/adr/. See docs/agents/domain.md.

Code Review Rules

Codex and other AI PR reviewers read this section. The other rules in this file and in the docs it points to (precommit, field test, commit gate, PR body format) are for coding agents. Do not apply them to PR authors.

  • Report a defect only when the change causes a concrete wrong behavior. Name the trigger and the result for the user. If you cannot name both, omit the finding.
  • Check the merge base. If develop already has the problem, still report it, but label it "already on develop" and do not call it a regression.
  • When the PR body, a linked issue, an ADR in docs/adr/, or a code comment calls a behavior deliberate, respond to that reason. Report a design flaw only when you can say why the stated reason does not hold.
  • Report a change that departs from an accepted ADR in docs/adr/, and name the ADR. Suggest only fixes that keep to the accepted ADRs.
  • A claim about Windows runtime behavior (cmd.exe parsing, PATHEXT, junctions, short paths, GUI detachment) needs a native run. Cross-compilation, command-construction assertions, and skipped capability tests do not show runtime behavior. If you can run Windows, run a minimal repro and record the environment, the exact command, and the result. If you cannot, ask the PR author a question with repro steps. The maintainer does not run Windows, and Windows contributors know its behavior better.
  • Do not report what gofmt, golangci-lint, ESLint, tsc, or pnpm check:i18n already report. Do not ask for docstring coverage. Do not ask for a code comment, except a marker that a standard in this repo requires. Report a stale comment.
  • Read earlier review threads. Do not repeat a finding that was resolved or refuted, unless you have new evidence.
  • When a PR adds, changes, or removes a test, apply docs/standards/tests.md, and ask for a new test only when it allows one. A real time.Sleep in a Go test outside synctest.Test is a defect: on a slow CI runner the test fails at random. Name the test and the wait that a channel or synctest.Test can replace.
  • The match corpus (internal/services/crossseed/match_corpus_test.go) grows freely. A PR that deletes or edits a row, adds an allowed difference, or adds a skip must say in its body which user-visible verdict changes and why. Report the edit when the body gives no such reason, even when the corpus-change label is set.