unzhakov
8314cee29c
- Shrink global AGENTS.md: 153 → 56 lines (−63%) Removed: git workflow, TDD, overthinking guards, code style, reasoning protocol Kept: personality, git basics, thinking levels, general principles, backend - Create project AGENTS.md: 71 lines Added: stack/commands, GitHub Flow git workflow, Conventional Commits, TDD (Python-specific), quality gates, debug verification - Trim CONVENTIONS.md: 161 → 68 lines (−58%) Removed: verbose examples, redundant unit convention section, lengthy SpectrumComponent code example - Delete DEVELOPMENT.md: 238 lines → 0 (migrated to AGENTS.md) Setup/release checklist removed (not agent concerns) Git workflow, TDD, quality gates, notebook QC, debug verification all migrated to AGENTS.md - Update README.md project structure Total per-session metadata: 552 → 195 lines (−65%)
72 lines
2.5 KiB
Markdown
72 lines
2.5 KiB
Markdown
# Agent Instructions — beta-spectrum
|
|
|
|
High-precision beta decay spectrum calculator. Extracts shape factor C(W) from ⁹⁹Tc beta spectrum to parametrize g_V coupling.
|
|
|
|
## Stack & Commands
|
|
|
|
```
|
|
pytest # all tests
|
|
nbmake notebooks/ # execute notebooks as tests
|
|
black --check . # formatting
|
|
ruff check . # linting
|
|
mypy . # type checking (strict)
|
|
bs_pnpi --nuclide Tc99 -vv --output ./output/verification.csv # debug verification
|
|
```
|
|
|
|
Install: `source ~/.pyenv/sci/bin/activate && pip install -e ".[dev]"`
|
|
|
|
## Git Workflow (GitHub Flow)
|
|
|
|
- **Never commit directly to `main`.** Always branch: `git checkout -b dev/<short-desc>`
|
|
- **Atomic commits** with **Conventional Commits** format:
|
|
- `feat:`, `fix:`, `docs:`, `style:`, `refactor:`, `perf:`, `test:`, `chore:`
|
|
- Imperative mood, present tense, under 72 chars
|
|
- WIP commits fine on dev branches — squash before final merge
|
|
- **Commit each logical change** — don't wait for green. Use `git add -p`.
|
|
- **Rebase over merge** for linear history: `git rebase main` before merge.
|
|
- Delete branch locally + remotely after merge.
|
|
|
|
## TDD
|
|
|
|
Test-first by default. For new classes/functions: write failing test first.
|
|
|
|
- **RED** — failing test defining desired behavior
|
|
- **GREEN** — minimal code to pass
|
|
- **REFACTOR** — clean up, confirm tests still pass
|
|
|
|
State which phase you're in. Name phases explicitly.
|
|
|
|
### Python Testing Conventions
|
|
|
|
- Tests mirror package structure: `beta_spectrum/components/foo.py` → `tests/physics/test_foo.py`
|
|
- Shared fixtures in `tests/conftest.py`
|
|
- Classes organized by feature area (e.g., `TestComponentBasicProperties`)
|
|
- Descriptive names: `test_<function>_<expected_behavior>_<context>`
|
|
- Include implementation-level assertions (type checks, pre/postconditions)
|
|
- Use `hypothesis` for property-based tests where applicable
|
|
- Physics tests verify: physical constraints at thresholds, positivity, monotonicity, numerical stability
|
|
|
|
## Quality Gates
|
|
|
|
All must pass before merge:
|
|
|
|
```bash
|
|
pytest
|
|
nbmake notebooks/
|
|
black --check .
|
|
ruff check .
|
|
mypy .
|
|
```
|
|
|
|
Run individually to identify failures.
|
|
|
|
## Debug Verification (Final Step)
|
|
|
|
After quality gates pass, run:
|
|
|
|
```bash
|
|
bs_pnpi --nuclide Tc99 -vv --output ./output/verification.csv --plot ./output/verification.png --log-file ./output/debug.log 2>&1 | tee ./output/debug_stdout.log
|
|
```
|
|
|
|
Verify parameter consistency across all components. Save artifacts to `./output/`.
|