mirror of
https://github.com/Akkudoktor-EOS/EOS.git
synced 2026-11-13 09:13:30 +01:00
2245976de4
The sandbox provides an isolated Docker environment for AI-assisted development (OpenCode + Claude Code + Qwen Code) against the local AkkudoktorEOS repository. The sandbox does not protect the repository from harmful changes by the agent. It limits what a misled agent can reach on the machine, but the agent can still write any change into the repository. Primary security defence is to check every change before it is run on the host. Same holds for opening a pull request or updating one. Additional changes - Reduce AGENTS.md to the project summary, baseline rules, completion checklist, and an index of the skills. - Add skills for the Python environment and REST API error responses. - Add the development guide page docs/develop/ai.md: the AI coding workflow, how agents get the project rules from AGENTS.md and ai/skills, and how to use the sandbox (start, agent logins, project commands with a virtual environment outside the workspace, running EOS and EOSdash, GitHub access, persistent data, security model). - Add a checklist for reviewing agent changes before pushing, starting with .git, which stays writable in the sandbox. - Check out all text files with LF line endings (.gitattributes), also on Windows with core.autocrlf, so the sandbox scripts run in the container and git in the container agrees with git on the host. Batch files keep CRLF. - Publish the ports of ai/compose.yaml on request (AI_SANDBOX_PORTS=1). docker compose run publishes them only with --service-ports. Off by default, so that several sandboxes can run in parallel. Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
2.6 KiB
2.6 KiB
AGENTS.md — Akkudoktor-EOS
Akkudoktor-EOS is a Python-based energy management and optimization system. It provides energy forecasts, optimization, energy management plans, and integrations with local energy devices and controllers.
The project prioritizes reliable local operation, clear interfaces, maintainable code, testability, and type safety.
Rules for every change
- Follow existing architecture and coding conventions.
- Prefer small, focused changes that preserve established interfaces and behavior.
- Use type annotations for functions, methods, and relevant variables.
- Write Google-style docstrings for modules, classes, and public functions/methods, following surrounding code.
- Keep code compatible with the supported Python version (
pyproject.toml). - Avoid introducing unnecessary dependencies.
- Use descriptive, domain-meaningful names.
- Never use production
assertfor input validation or runtime error handling; use explicit exceptions. - Use existing logging facilities and conventions.
- Follow existing patterns for config, validation, error reporting, resource management.
- Preserve compatibility with existing tests and supported integrations unless a change explicitly requires otherwise.
- Never use the workspace
.venv: runuv,makeand all Python tools in a virtual environment outside the workspace (UV_PROJECT_ENVIRONMENT), seeai/skills/python-environment/SKILL.md.
Skills
Detailed rules live in ai/skills/. Load the relevant skill for the task:
| Skill | Load when |
|---|---|
ai/skills/application-configuration/SKILL.md |
Config, Pydantic models, defaults |
ai/skills/commit-messages/SKILL.md |
Creating/checking commit messages |
ai/skills/energy-domain/SKILL.md |
Optimization, adapters, units/signs |
ai/skills/filename-conventions/SKILL.md |
Creating/renaming files |
ai/skills/python-environment/SKILL.md |
Before running uv, make, pytest, mypy, ruff or any Python |
ai/skills/python-quality/SKILL.md |
Writing/modifying Python |
ai/skills/rest-api/SKILL.md |
Adding/changing REST endpoints, API error responses |
ai/skills/testing/SKILL.md |
Adding/updating tests, bug fixes |
Completion checklist
Before considering a change complete:
- New and renamed files comply with the filename rules in
pyproject.toml. - The filename linter passes.
- Tests have been added or updated as appropriate.
- Relevant pytest tests pass.
- Ruff checks pass.
- Mypy checks pass where applicable.
- Configuration and documentation updated when necessary.
- No unrelated changes or unnecessary exceptions introduced.