84 lines
3.2 KiB
Markdown
84 lines
3.2 KiB
Markdown
# [PROJECT_NAME]
|
|
|
|
[short description]
|
|
|
|
## Project structure
|
|
|
|
```
|
|
src/
|
|
tests/ # Mirrors src/ structure; conftest.py provides shared fixtures
|
|
```
|
|
|
|
## Common commands
|
|
|
|
```shell
|
|
# Run application
|
|
[Command to run the application]
|
|
|
|
# Run tests
|
|
pytest
|
|
|
|
```
|
|
|
|
## Architecture
|
|
[Simple explanation of the global architecture]
|
|
|
|
|
|
## Collaboration rules
|
|
|
|
### RULE-01 — Development Process
|
|
|
|
- Before writing any code, explain the available options and approaches.
|
|
- Validate the chosen approach together before producing code.
|
|
- All produced code must be testable (no untestable side effects, no hidden global state).
|
|
|
|
### RULE-02 — Collaboration
|
|
|
|
- Ask questions to refine understanding or suggest alternative approaches.
|
|
- Ask questions one at a time. Wait for the answer to be fully understood before asking the next one.
|
|
- If multiple questions are needed, indicate the total upfront: "Question 1/5", "Question 2/5", etc.
|
|
|
|
### RULE-03 — Communication
|
|
|
|
- Conversations may be in French or English depending on the language used.
|
|
- All code, documentation, and comments must be in English exclusively.
|
|
|
|
### RULE-04 — Code Standards
|
|
|
|
- Python 3.12+. Follow PEP 8 conventions.
|
|
- Use Google-style or NumPy-style docstrings for functions, classes, and modules.
|
|
- `snake_case` for functions/variables, `PascalCase` for classes, `UPPER_SNAKE_CASE` for constants.
|
|
- Type hints on all function signatures (parameters and return types).
|
|
- No emojis in code, comments, or docstrings.
|
|
- Use `pathlib.Path` for all file path manipulations in new code.
|
|
- Use the `logging` module (never `print()`).
|
|
|
|
### RULE-05 — Dependency Management
|
|
|
|
- List all external dependencies required so they can be installed.
|
|
- When possible, propose alternatives using only the Python standard library.
|
|
- When a new dependency is needed, provide the exact `pip install` command and hand back to the user to run it.
|
|
- Never run `pip install` autonomously.
|
|
- Never modify `requirements.txt` directly — the user manages that file.
|
|
|
|
### RULE-10 — Running Tests
|
|
|
|
- Do NOT run tests automatically. Always ask the user before running `pytest`.
|
|
|
|
### RULE-11 — Functional Specifications as Source of Truth
|
|
|
|
- Feature specifications live in `docs/features/` (named `FEAT-NNN-<slug>.md`).
|
|
- These specs are the authoritative source for expected behavior. In case of doubt between code and spec, the spec wins.
|
|
- Do NOT read specs systematically. Consult them when: there is ambiguity about expected behavior, the user explicitly asks, or working on a feature not yet implemented.
|
|
- When creating a new feature, propose a spec in `docs/features/` before implementation.
|
|
|
|
## Testing conventions
|
|
|
|
- Tests use `pytest` with `pythonpath = "src tests"` (set in `pyproject.toml`).
|
|
- `conftest.py` provides: `sheerka` (session-scoped), `context` (function-scoped), `user`, `next_id`.
|
|
- Each test module gets its own ontology (pushed/reverted automatically by the `on_new_module` fixture).
|
|
- `tests/helpers.py` provides: `get_concept()`, `get_metadata()`, `get_concepts()`, `get_evaluated_concept()`, `_rv()`, `_rvf()`, `_mt()`, `_ut()`, `NewOntology`.
|
|
- `sheerka.initialize("mem://")` is used in tests (in-memory, no disk I/O).
|
|
- Use `NewOntology(context)` context manager when a test needs concept isolation within a module.
|
|
|