Serge ZaigraeffandClaude Opus 4.6
64c5a53d5b
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
59 lines
3.0 KiB
Markdown
59 lines
3.0 KiB
Markdown
# Development Rules
|
|
|
|
Living document. Updated after each session.
|
|
|
|
## Hard Rules
|
|
|
|
Non-negotiable. Violation = stop and fix before continuing.
|
|
|
|
* Branch freshness: Run `git fetch origin && git log HEAD..origin/dev --oneline` before work. Rebase if non-empty.
|
|
* Post-refactor verification: Verify all imports compile (`python -m py_compile <file>`) after dependency changes.
|
|
* Impact assessment: Ask how changes affect the rest of the project before implementation.
|
|
* 3+ Iteration Pivot: If a problem requires 3+ iterative fixes, propose a radical architectural simplification.
|
|
* Dependency removal audit: `grep -r 'import.*package'` all consumers, verify replacement covers every use case before removing.
|
|
|
|
## Git Strategy
|
|
|
|
* **Branch First**: Create feature branch from `dev` for multi-file or non-trivial changes. Minor features (single-concern, <=3 files) may be committed directly to `dev`. Never work directly on `main`.
|
|
* **Base Branch**: `dev` contains latest stable changes. Always branch from `dev`.
|
|
* **Release**: `dev` merged into `main` for production. Never push directly to `main`.
|
|
* **Clean Up**: Delete feature branches after merge into `dev`.
|
|
|
|
## Coding Constraints
|
|
|
|
* Use standard library and framework built-ins. No custom algorithms when a one-liner exists.
|
|
* No over-engineering, no redundant abstractions. Simplest tool for the job.
|
|
* No nested conditional chains. Use lookup dictionaries and early returns.
|
|
* Crash on missing configs/dependencies. No default values for critical data (model_path, language).
|
|
* Semantic naming and strict type hints mandatory.
|
|
* Extract shared utilities only for genuinely reusable operations.
|
|
* All code comments and docstrings in Russian (project convention).
|
|
|
|
## Testing
|
|
|
|
* No formal test suite yet. Verify changes with:
|
|
- `python -m py_compile <file>` for syntax/import checks on each modified file.
|
|
- `python -c "from app import WhisperServiceAPI"` for full import chain validation.
|
|
- Manual API testing via web UI or curl against running server.
|
|
|
|
## Self-Review (after 3+ file changes)
|
|
|
|
1. `git diff --stat` -- verify only expected files changed.
|
|
2. Full diff review -- incomplete guards, duplicated literals, formatting.
|
|
3. Grep for old names after renames.
|
|
4. `python -m py_compile` on every modified `.py` file.
|
|
|
|
## Audio Processing Rules
|
|
|
|
* FFmpeg and SoX are external dependencies. Always check subprocess return codes.
|
|
* Temp files must be created via `TempFileManager.temp_file()` context manager -- never raw `tempfile.mktemp`.
|
|
* Audio pipeline order matters: convert to WAV 16kHz -> normalize -> compress/expand -> speedup -> add silence.
|
|
|
|
## Flask / API Rules
|
|
|
|
* New endpoints go in `app/api/routes.py` inside `_register_routes()`.
|
|
* All transcription endpoints delegate to `TranscriptionService.transcribe_from_source()`.
|
|
* New audio input methods: subclass `AudioSource`, implement `get_audio_file()`.
|
|
* File validation runs through `FileValidator` -- never validate inline in routes.
|
|
* Configuration values accessed via `self.config.get()` with sensible defaults, except critical params which must crash if missing.
|