Skip to content

AGENTS.md

Latest commit

 

History

History
135 lines (114 loc) · 6.55 KB

AGENTS.md

File metadata and controls

135 lines (114 loc) · 6.55 KB
Raw

AGENTS.md

This document provides guidelines for AI agents contributing to this repository. Any AI agent must follow all the rules and regulations that are inside of this file.

Overview of Instructions

  • Always use uv: This project uses uv for all dependency management, virtual environments, and task running. Do not use pip or venv directly.
  • Follow all guidelines: This document contains the complete set of guidelines from AGENTS.md and docs/plan.md. You must follow them strictly.
  • Verify your changes: Before committing any changes, you must run all linters and tests to ensure your changes are correct and follow the project's style. Use uv run task all.
  • Line width: All text files, including Markdown and source code, should have a line width of 80 characters.
  • Format PLAN.md: Manually ensure PLAN.md lines do not exceed 80 characters by wrapping long lines appropriately.
  • Permission to run commands: You have permission to run all commands in this file to verify their functionality.
  • Incremental changes: Make small, incremental changes. This makes it easier to review your work and catch errors early.
  • Communicate clearly: When you propose changes, explain what you've done and why.

Notification Instructions

  • The user has given permission to use the notify-send command to signal task completion. Here is an example of the command: notify-send "Queston from Coding Agent" "Please clarify how to complete the testing task.".
  • The user wants a notify-send notification whenever I ask a question.
  • Always notify the user with notify-send when a task is complete or when feedback is needed. I have standing permission to use the notification tool.

Build, Lint, and Test Commands

  • Install dependencies: uv sync --dev
  • Run all tasks: uv run task all
  • Run all linters: uv run task lint
  • Format code: uv run task format (check), uv run task format-fix (fix)
  • Lint code: uv run task check
  • Type check: uv run task mypy, uv run task ty, uv run task symbex
  • Test all: uv run task test
  • Test with coverage: uv run task test-coverage
  • Test variants: uv run task test-not-property, uv run task test-not-random, uv run task test-silent
  • Run a single test: pytest tests/test_file.py::test_function or uv run pytest tests/test_file.py::test_function
  • Markdown lint: uv run task markdownlint

Code Requirements

All the Python code should follow these standards:

  • Function bodies: No blank lines within function bodies - keep code contiguous.
  • Docstrings: Single-line docstrings starting with a capital letter, ending with a period.
  • Comments: Other comments start with a lowercase letter; preserve existing comments during refactoring.
  • Imports: Group imports in this order: standard library, third-party, local imports. Use absolute imports (from rollcall.module import). Finally, make sure that all imports are placed at the top of the file. Do not place imports into the middle of a file or even at the start of a function or class.
  • Formatting: Use ruff format (line length 79 for lint, 88 for isort); trailing commas enabled.
  • Types: All functions must have type hints for parameters and return values.
  • Naming: snake_case for functions/variables, PascalCase for classes, UPPER_SNAKE_CASE for constants.
  • File operations: Use pathlib.Path for all file system operations, never string paths.
  • Error handling: Use specific exceptions, not generic Exception; provide meaningful error messages.

Project Structure Requirements

  • Source code in src/rollcall/ directory.
  • Tests in tests/ directory with matching structure to source.
  • Use uv for dependency management, virtual environments, and task running.
  • Support Python 3.11, 3.12, and 3.13 on MacOS, Linux, and Windows.
  • Use Pydantic models for data validation and JSON serialization.

Project Behavior Requirements

  • The purpose of this project is to make it easy for a course instructor (e.g., a teacher in elementary through high school or a professor at a college or a university) to generate a QR code that displays in a terminal window.
  • When a student scans the QR code, then are taken to a Google Form that has some pre-filled fields, including the current date, time, and session name. The student then completes the rest of the form (e.g., name, email) and submits it. Once a student has submitted the form this is their way of "checking in" to indicate that they were present during the class session.

Test Requirements

All test cases should follow these standards:

  • Since a test case is a Python function, it should always follow the code requirements above.
  • Test cases should have a descriptive name that starts with test_.
  • Test cases should be grouped by the function they are testing.
  • Test cases should be ordered in a way that makes sense to the reader.
  • Test cases should be independent of each other so that they can be run in a random order without affecting the results or each other.
  • Test cases must work both on a local machine and in a CI environment.
  • Test cases should aim to achieve full function, statement, and branch coverage.
  • Property-based tests must be marked with @pytest.mark.property.
  • Test cases should not produce any console output.

Making Changes

  1. Understand: Thoroughly understand the request and the relevant codebase. Use the available tools to explore the code.
  2. Plan: Formulate a clear plan before making any changes.
  3. Implement: Make small, incremental changes.
  4. Verify: Run uv run task all to ensure your changes are correct and follow the project's style.
  5. Commit: Write a clear and concise commit message explaining the "why" of your changes.
  6. Rules: Always follow the rules in this file and in the docs/plan.md file.
  7. Completion: When you are finished with tasks, please summarize what tasks you completed, how you completed them, the challenges you faced, how you overcame them, and the rules that you followed during completion of the tasks.

Additional Notes for the Coding Agent

Note: Every time a coding agent finishes a task, it should add notes to the PLAN.md file as it deems appropriate. The coding agent should write the notes as a Markdown list. The purpose of the notes in the PLAN.md file are to summarize the changes that the coding agent made to the codebase. The coding agent should always carefully explain the changes that it made so that the human software engineer can understand the changes that were made.