67 lines
2.5 KiB
Markdown
67 lines
2.5 KiB
Markdown
# Agent Guide
|
|
|
|
## Runtime And Syntax
|
|
|
|
- Python baseline is 3.14 (`requires-python = ">=3.14"`).
|
|
- Python 3.14 syntax is allowed. Do not rewrite valid new syntax just because it
|
|
looks unusual.
|
|
- Example: Parentheses-Free Exceptions (PEP 758).
|
|
|
|
## Code Organization
|
|
|
|
- Prefer focused packages/modules over large flat files when adding new areas.
|
|
- Preserve current package boundaries. If unsure, check `docs/project_map.md`
|
|
and `docs/source_architecture.md`.
|
|
- Put related files in folders from the start when the area is likely to grow.
|
|
Example: prefer `src/pack/foo/bar.py` over adding many unrelated
|
|
`src/pack/foo_bar.py` files.
|
|
- Do not add compatibility treatment for unused things. Compatibility is for
|
|
real callers, real persisted data, or documented external contracts. If a
|
|
symbol/format has no production callers and no real stored data, prefer
|
|
removing or migrating it cleanly over preserving ghost behavior.
|
|
|
|
## Tests
|
|
|
|
- Prefer pytest `tmp_path` for test-local filesystem state.
|
|
- Avoid fixed paths under `local_temp_root()` unless the test explicitly needs
|
|
cross-process persistence and cleans up after itself.
|
|
- Prefer `async def test_x()` with pytest-asyncio over
|
|
`def test_x(): async def scenario(): ...; asyncio.run(scenario())`.
|
|
- Prefer field-level assertions like `actual["field"] == expected["field"]`
|
|
over whole-object equality unless extra fields are intentionally forbidden.
|
|
- Scope test runs. This repo is large; broad test commands can be slow.
|
|
|
|
## Verification Commands
|
|
|
|
```bash
|
|
uv run pytest -q
|
|
uv run ruff check
|
|
uv run ruff format
|
|
uv run basedpyright --level error
|
|
```
|
|
|
|
Use `uv run --env-file .env pytest -q` when live MCP-backed tests need local
|
|
environment configuration.
|
|
|
|
## Docs
|
|
|
|
- Before editing docs, read `docs/AGENTS.md`.
|
|
- `docs/current_roadmap.md` is the live roadmap.
|
|
- If docs mention a partial implementation, add a short comment or docstring at
|
|
the code seam too. Future agents see code before they see old plans.
|
|
|
|
## Comments And Docstrings
|
|
|
|
- Add comments/docstrings around weird or non-obvious logic.
|
|
- Add docstrings explaining compound return types that otherwise say little,
|
|
for example `tuple[list[str], Any]`.
|
|
- Polish common helper docs if you keep using the helper.
|
|
|
|
## Skills And Tools
|
|
|
|
- Skills can be useful but can overstate urgency. Use judgment.
|
|
- Serena is useful for symbol discovery and rename-like navigation. Prefer
|
|
built-in edit tools for ordinary file edits.
|
|
- If an MCP tool is irrelevant to the project or clutters available tools,
|
|
mention it so it can be disabled.
|