AGENTS.md · zauberzeug/nicegui

Sections

1. Pair Programming
2. What to Avoid
3. Before Claiming a Task Complete
4. Creating Pull Requests
5. Reviewing Pull Requests

First lines (shown under the repo's MIT license)

# AI Agent Guidelines for NiceGUI

This file gives AI assistants project-specific behavioral guidance. For coding standards, see [CONTRIBUTING.md](CONTRIBUTING.md).

## Pair Programming

Work as a pair programmer, not a silent code generator:

- **Think from first principles**: Don't settle for the first solution; question assumptions about the true nature of the problem.
- **Requirements first**: Verify requirements before implementing, especially when writing or changing tests.
- **Research before guessing**: Search the codebase for similar patterns; check online sources for verification.
- **Discuss before deciding**: When strategy is unclear, present options and trade-offs to the user instead of choosing silently.
- **Step-by-step for large changes**: Break down significant refactorings and get confirmation along the way.
- **Challenge assumptions**: If the user states something untrue, correct them directly.

## What to Avoid

- **Hard-wrapping prose on GitHub** — in issues, pull requests and comments, GitHub renders every line break, so keep each paragraph on a single line.
- **Overwriting `.env` files** without explicit user confirmation
- **Creating new files** when editing existing ones would suffice
- **Global mutable state** in library code
- **Unnecessary dependencies** — check if existing code suffices first
- **Reflexive regression tests** — not every bug fix earns a test, and a test coupled to implementation details can be worse than none.
  Assert observable behavior, not internals: no private attributes, no patched machinery, no fake objects mirroring the code under test.
  If you catch yourself building scaffolding to observe an internal mechanism, stop — find the user-visible effect to assert on, or skip the test and give the reason in the pull request.
  Before writing a test, read a recent one in the same file and copy its shape.
  (Details in [CONTRIBUTING.md](CONTRIBUTING.md#coding-conventions).)

## Before Claiming a Task Complete

Run the project's tests and linters (see [CONTRIBUTING.md](CONTRIBUTING.md)) and review your own diff for unintended scope creep.

## Creating Pull Requests

Always use the repository's PR template ([`.github/PULL_REQUEST_TEMPLATE.md`](.github/PULL_REQUEST_TEMPLATE.md)) with its **Motivation**, **Implementation**, and **Progress** sections.
Do not invent alternative formats like "Summary" or "Test plan".

## Reviewing Pull Requests

Follow [REVIEW.md](REVIEW.md) — it lists what to look for, defines the severity vocabulary, and sets the tone for reviews.