Skip to content

AGENTS.md

Latest commit

 

History

History
59 lines (44 loc) · 3.89 KB

AGENTS.md

File metadata and controls

59 lines (44 loc) · 3.89 KB
Raw

AGENTS.md

Writing code

  • Minimal try/except: let errors propagate — silent failures hide bugs. Only catch exceptions for intentional fault tolerance (retries, robustness).
  • Targeted comments: don't explain your work process or reference old code. Use targeted comments sparingly to clarify ambiguous logic.
  • Zen of Python: remember the Zen of Python when writing code.
Beautiful is better than ugly.
Explicit is better than implicit.
Simple is better than complex.
Complex is better than complicated.
Flat is better than nested.
Sparse is better than dense.
Readability counts.
Special cases aren't special enough to break the rules.
Although practicality beats purity.
Errors should never pass silently.
Unless explicitly silenced.
In the face of ambiguity, refuse the temptation to guess.
There should be one-- and preferably only one --obvious way to do it.
Although that way may not be obvious at first unless you're Dutch.
Now is better than never.
Although never is often better than *right* now.
If the implementation is hard to explain, it's a bad idea.
If the implementation is easy to explain, it may be a good idea.
Namespaces are one honking great idea -- let's do more of those!

Running code

  • Always use uv: run code with uv run or uv run <command>, never raw python.
  • Adding dependencies: add to pyproject.toml and run uv sync --all-extras to install and lock them.
  • Git dependency pins: when pinning git dependencies in pyproject.toml, always use a small (7-char) commit hash for the rev field.
  • Never edit .venv/: the local virtual env is read-only. Edits there are silently overwritten by the next uv sync and don't propagate to teammates or CI. Reading files under .venv/ to understand library behavior is fine; writing is not. To fix a dependency issue, update pyproject.toml (pin a fork via 7-char commit hash if needed), vendor the code into src/, or patch upstream.

Skills

Skills live in skills/ and are symlinked to .claude/skills/. They teach agents how to handle specific workflows (e.g. starting the inference server, writing configs). When you make changes to the codebase, check if any skills need to be updated to stay accurate.

You are responsible for maintaining the skills folder. When a workflow fails and you fix it – whether with help from the user or through trial and error – you must update the skills to make implicit knowledge explicit. You are also responsible for keeping the skills up to date whenever you or anyone else modifies the code.

Testing

Write tests as plain functions with pytest fixtures. Don't use class-based tests.

  • Conservative test additions: don't add new tests unless the user explicitly asks for them or it's clearly necessary. Editing existing tests is fine, but adding new test files or test functions should be the exception, not the default.
  • Test what matters: only test code with clear, isolated logic — pure functions, abstract base classes, data transformations, well-defined algorithms. Don't test runtime-level code, framework glue, or anything that requires extensive mocking/patching just to get a test to pass. If you need to patch everything out to make it testable, it's probably not worth testing.

Git

  • Branch prefixes: use the following prefixes for branches: feat/, fix/, chore/

GitHub

  • Draft PRs: always create PRs as drafts (gh pr create --draft) to avoid triggering CI unnecessarily.
  • Pull requests: do not include a "test plan" section in PR descriptions unless you actually ran tests to verify the changes or the user explicitly asked for one.
  • Keep PR descriptions in sync: every time you push commits to a PR, also update the PR description (gh pr edit <num> --body-file ...) so it reflects the current state of the branch — not just what was true when the PR was opened. Preserve any auto-generated blocks (e.g. <!-- CURSOR_SUMMARY -->).