# AGENTS.md — Quy tắc ngắn cho Codex CLI

## Source of truth

1. `README.md`
2. `config/*.yaml`
3. tests đã được người dùng chấp thuận
4. mã hiện tại

Khi các nguồn mâu thuẫn, không tự suy đoán. Báo rõ mâu thuẫn và dừng ở điểm cần quyết định.

## Token-efficient workflow

- Chỉ đọc tệp liên quan trực tiếp; dùng `rg`, `find`, `sed -n`, `head`, `tail`.
- Không dump toàn bộ NetCDF, log, HTML hoặc cây thư mục lớn.
- Với NetCDF, chỉ in dimensions, variables, units, ranges, missing counts và vài timestamps.
- Với log, đọc phần đầu, phần cuối và đoạn quanh `ERROR|Traceback|FAILED|Killed|OOM`.
- Không lặp lại README trong trả lời.
- Không in diff đầy đủ khi diff lớn; tóm tắt và chỉ nêu hunk quan trọng.
- Không chạy lại toàn pipeline nếu unit/integration test nhỏ đủ kiểm chứng.
- Dùng synthetic/sampled data trước; chỉ chạy full HPC sau khi smoke test pass.
- Giữ câu trả lời cuối dưới dạng status ngắn.

## Work discipline

Trước khi sửa:

```text
PLAN
- goal
- files
- tests
- assumptions/blockers
```

Sau khi sửa:

```text
RESULT
- changed
- tests
- outputs checked
- unresolved
- next command
```

## Prohibitions

- Không sửa input.
- Không hard-code paths/scientific settings.
- Không random split time series.
- Không fit trên validation/operational.
- Không gọi `fit` trong GĐ2.
- Không refit SPEI distribution trong PA2.
- Không im lặng bỏ qua missing members/files.
- Không ghi đè output/artifact nếu thiếu `--overwrite`.
- Không đổi tên biến, file hoặc dimensions đã quy định mà chưa được duyệt.
- Không refactor ngoài phạm vi.
- Không tuyên bố thành công khi chưa validate output.

## Coding requirements

- Python package logic ở `src/dr_sfc/`; `scripts/` chỉ là entry points.
- Type hints cho public functions.
- Docstring ngắn cho scientific functions.
- Structured logging.
- Deterministic random seeds.
- Config validation trước khi chạy.
- Atomic writes.
- Checkpoint/resume.
- Non-zero exit code khi lỗi.
- Tests cho mọi sửa lỗi khoa học hoặc time alignment.

## Required checks for every NetCDF output

```text
file exists and size > 0
open succeeds
expected variables exist
dimensions/order correct
coordinates monotonic
units present
valid range plausible
missing fraction reported
init/target dates correct
config hash and artifact version present
```

## Prompt handling

Khi người dùng giao một yêu cầu rộng:

1. Không xây toàn bộ ngay.
2. Chia thành milestone nhỏ.
3. Thực hiện milestone đầu tiên sau khi phạm vi rõ.
4. Không hỏi lại thông tin đã có trong README/config.
5. Chỉ hỏi câu có ảnh hưởng quyết định khoa học hoặc interface.

## Completion statement

Chỉ dùng từ `completed` khi acceptance criteria đã pass. Nếu chưa, dùng một trong:

```text
implemented but not fully validated
partially completed
blocked
failed
```