116 lines
4.0 KiB
Markdown
116 lines
4.0 KiB
Markdown
# Agents.md
|
||
|
||
# Project Context — Python (General)
|
||
|
||
This repository is a general Python project. Ensure a virtual environment exists, create it with `uv` if missing, keep `requirements.txt` accurate, and then follow the user's instructions.
|
||
|
||
---
|
||
|
||
## Environment
|
||
|
||
- Virtual env: prefer `uv` to manage the venv and installs.
|
||
- Create: `uv venv` (optionally `--python <version>`).
|
||
- Use: activate `.venv` or run commands via `uv run <cmd>`.
|
||
- Dependencies:
|
||
- If `requirements.txt` exists: `uv pip install -r requirements.txt`.
|
||
- When packages are added/removed, update `requirements.txt` to stay accurate.
|
||
- Default policy: freeze exact versions unless the user specifies otherwise (e.g., `uv pip freeze > requirements.txt`).
|
||
- Never assume the environment is active.
|
||
- Before asking the user to run a command manually, verify whether the virtual environment is active.
|
||
- If not active, instruct explicitly how to activate it:
|
||
- Unix/macOS: `source .venv/bin/activate`
|
||
- Prefer `uv run <command>` to avoid activation issues.
|
||
|
||
---
|
||
|
||
## Directory & File Safety Rules
|
||
|
||
When writing files or creating directories:
|
||
|
||
- If instructed to create or write into a folder with a specific name:
|
||
- **First verify whether a directory with that name already exists.**
|
||
- Do NOT create it blindly.
|
||
- If it exists, reuse it unless the user explicitly requests overwriting.
|
||
- If a file would be overwritten, clarify intent unless overwrite is explicitly requested.
|
||
|
||
- Avoid duplicating folder structures.
|
||
- Do not create parallel directories with similar names (e.g., `src` and `src_new`) unless explicitly requested.
|
||
- Maintain consistent project structure conventions.
|
||
- Respect existing naming conventions.
|
||
|
||
---
|
||
|
||
## Command Execution Policy
|
||
|
||
When suggesting commands to the user:
|
||
|
||
1. Ensure the command is compatible with the project’s tooling (`uv` preferred).
|
||
2. Avoid global installs.
|
||
3. Avoid OS-specific assumptions unless specified.
|
||
4. If the command modifies the environment (e.g., installing packages):
|
||
- Make sure `requirements.txt` is updated accordingly.
|
||
5. If the user is inside a container or remote environment, do not assume local execution context.
|
||
6. Never assume shell state (activated venv, exported variables, current directory). Always be explicit.
|
||
|
||
---
|
||
|
||
## Operating Model
|
||
|
||
- Ask quick clarifying questions if versions, entry points, or expected behaviors are ambiguous.
|
||
- Prefer small, incremental changes with brief plans for multi-step work.
|
||
- Do not commit secrets.
|
||
- Avoid committing large build artifacts unless requested.
|
||
- Do not introduce new tooling (linters, formatters, frameworks) unless:
|
||
- The user requests it.
|
||
- It is strictly necessary to complete the task.
|
||
- Avoid unnecessary architectural refactors.
|
||
- Prioritize minimal, reversible changes.
|
||
|
||
---
|
||
|
||
## Code Modification Principles
|
||
|
||
- Follow existing code style and architecture.
|
||
- Avoid unnecessary refactors.
|
||
- Keep changes minimal and scoped.
|
||
- Preserve backward compatibility unless explicitly told otherwise.
|
||
- If introducing new files:
|
||
- Place them in logically consistent locations.
|
||
- Avoid breaking import paths.
|
||
- Do not remove or rename files unless explicitly instructed.
|
||
|
||
---
|
||
|
||
## Reproducibility
|
||
|
||
- The environment must remain reproducible from scratch using:
|
||
- `uv venv`
|
||
- `uv pip install -r requirements.txt`
|
||
- No hidden dependencies.
|
||
- No reliance on undeclared system packages unless clearly documented.
|
||
- Ensure all runtime dependencies are declared.
|
||
|
||
---
|
||
|
||
## Typical Tasks
|
||
|
||
Agents operating in this repository may:
|
||
|
||
- Implement features.
|
||
- Fix bugs.
|
||
- Run tests.
|
||
- Update documentation.
|
||
- Improve structure when explicitly requested.
|
||
- Keep the environment reproducible and synced with declared requirements.
|
||
|
||
---
|
||
|
||
## Safety & Determinism Rules
|
||
|
||
- Do not perform destructive actions (e.g., delete directories, drop databases) unless explicitly instructed.
|
||
- Do not overwrite configuration files without confirmation.
|
||
- Always prefer deterministic operations.
|
||
- If uncertain about intent, ask before acting.
|
||
|
||
---
|