Skip to content

AGENTS.md

Latest commit

 

History

History
73 lines (54 loc) · 2.53 KB

AGENTS.md

File metadata and controls

73 lines (54 loc) · 2.53 KB
Raw

AGENTS.md

PR review philosophy

When reviewing or generating code, apply this checklist:

  1. Necessity

    • Ask whether each added block is required for the requested behavior.
    • Flag speculative abstractions, premature generalization, and dead paths.

  2. Simplicity

    • Prefer less code when readability and correctness are preserved.
    • Suggest idiomatic code for the language in that module only if it makes the result easier to understand.
    • Avoid "clever" one-liners that reduce maintainability.

  3. Readability

    • Prefer explicit names, small functions, shallow nesting, and linear control flow.
    • Flag dense logic that would be easier to read if split or renamed.

  4. Local consistency

    • Compare with nearby modules and existing patterns before proposing structure/style changes.
    • Follow existing naming, error-handling, typing, and test conventions.

  5. PR sizing

    • Flag PRs that combine unrelated concerns.
    • Suggest a split when refactoring, behavior changes, and cleanup are mixed together.

Review output format

When reviewing a PR, output:

  • Critical issues
  • Simplicity/readability suggestions
  • Consistency concerns
  • Whether the PR should be split
  • A brief overall verdict

Development Patterns

Database Migrations

Python services with databases use Alembic:

cd framework
uv run --no-sync --python=3.11.14 python -m dev.generate_migration "Description"

For Alembic-backed services, do not write a new migration file from scratch when the intended change is a schema diff. Help the user use python -m dev.generate_migration from the framework/ directory instead, then review the generated revision and make only the minimal adjustments needed. This helps avoid schema drift between SQLAlchemy models and committed migrations.

The migration generator is Alembic-branch aware. It upgrades the temporary database to all heads, then autogenerates a revision against the selected branch head. The default branch head is flwr@head; these commands are equivalent:

cd framework
uv run --no-sync --python=3.11.14 python -m dev.generate_migration "Widen integer columns"
cd framework
uv run --no-sync --python=3.11.14 python -m dev.generate_migration --head flwr@head "Widen integer columns"

After autogeneration:

  • Confirm the new revision has the intended down_revision.
  • Confirm the generated operations match the SQLAlchemy metadata change.
  • Review generated batch_alter_table blocks for SQLite compatibility.
  • Update generated schema documentation if table metadata changed.