AI Coding Guide

AI Coding Guide#

This guide defines how AI-assisted coding should be used in DeePTB. AI can help draft code, tests, docs, and reviews, but maintainers remain responsible for scientific correctness.

Required Discipline#

  • Treat tensor shape, dtype, device, batching, and key semantics as correctness issues.

  • Prefer existing DeePTB interfaces and domain concepts over new helper layers.

  • Keep changes scoped to the PR goal. Avoid drive-by cleanup in high-risk modules.

  • Update tests, examples, and docs when config, CLI, data format, or public behavior changes.

  • Mark AI-assisted PRs in the PR template.

Red Lines#

AI-generated changes must not silently:

  • Rename or repurpose AtomicDataDict keys.

  • Change orbital ordering or basis mapping outside OrbitalMapper.

  • Change reduced matrix element conventions.

  • Change SK or E3 Hamiltonian block expansion semantics.

  • Change config defaults or schema without docs and tests.

  • Change checkpoint or dataset compatibility without an explicit migration path.

  • Move domain logic into generic utilities where reviewers cannot see the physics meaning.

High-Risk Changes Need Regression Tests#

Add or update regression tests when touching:

  • dptb/data/_keys.py

  • dptb/data/transforms.py

  • dptb/nn/hamiltonian.py

  • dptb/nn/build.py

  • dptb/utils/argcheck.py

  • dptb/nnops/loss.py

  • dptb/nnops/trainer.py

Useful regression tests usually check concrete behavior: tensor keys, shapes, ordering, config parsing, checkpoint loading, numerical outputs, or CLI behavior.

Review Prompts For AI Tools#

Use the prompts in docs/maintenance/ai_review_prompts.md for repeatable review. The recommended minimum set is:

  • Maintainer Review: correctness, compatibility, risk, and merge recommendation.

  • Test Gap Review: changed behavior that is missing regression, smoke, or example coverage.