light-backend-coding

Backend Code Writing and Review

Before Writing Code

Read the existing code, match the project's style, conventions, and dependency libraries, and do not introduce new frameworks without authorization (CONVENTIONS). Clarify inputs and outputs, boundary conditions, and reproduction requirements (seed/version).

Code Quality Standards

• Clear logic: single responsibility, small functions, clear data flow.
• Security: parameterized queries, input validation, exception handling; do not hardcode secrets (use environment variables/configuration); do not echo sensitive values (a10).
• Readable: meaningful naming, comments explain "why" rather than "what", same density as surrounding code.
• Maintainable/extensible: low coupling, configuration-driven (Hydra), avoid over-engineering.
• Reproducible: fix random seeds, lock dependency versions, record the environment, deterministic data splits.

Engineering Practices

• Version control: Git; do not push feature branches directly to main; meaningful commit messages; commit/push only when the user explicitly requests it.
• Dependencies/environment：
  • uv (recommended, Rust implementation 10-100x faster):uv init → uv add <pkg> → uv lock/uv sync(according to uv.lock exact reproduction) → uv run；uv python pin 3.11 lock the Python version.
  • Poetry：poetry add → poetry install(according to poetry.lock); put dependencies in PEP 621 [project.dependencies], dev dependencies in [tool.poetry.group.dev]; CI pins the Poetry version.
  • Always commit the lock file, and in CI use uv sync/poetry install to restore a deterministic environment.
• Testing: pytest—files test_*.py, functions test_* are auto-discovered, pure assert；@pytest.fixture(scope function/module/session) for dependency injection,@pytest.mark.parametrize to run multiple sets of inputs, shared fixtures go in conftest.py. For new features/bug fixes, write tests first, and after changes run pytest -x to verify. Coverage pytest --cov=pkg --cov-report=term-missing, CI produces --cov-report=xml。
• Quality gates：
  • Ruff：[tool.ruff.lint] use select/extend-select(e.g. add B)/ignore(e.g. E501)；[tool.ruff] set line-length/target-version; CI runs ruff check . and ruff format --check .separately (linter and formatter are two commands).
  • Static type checking (mypy / pyright): choose the level according to the nature of the project—for new projects/research code, start with pyright basic (or mypy basic level, checking only obvious type errors and not requiring full annotations)，for library code/public APIs use mypy --strict(requires full annotations, the strictest). Add a CI step mypy src; when third parties have no stubs, ignore_missing_imports(for library code, tighten via per-module overrides), test code may ignore_errors. The scaffold's pyproject.toml already includes [tool.mypy] basic configuration + strict toggle comments, and does not conflict with the uv route.
  • pre-commit：.pre-commit-config.yaml of repos Use rev pin versions (tag/SHA, no floating branches); connect with astral-sh/ruff-pre-commit of ruff(args:[--fix])+ruff-format；pre-commit install enabled, CI runs pre-commit run --all-files。
  • SonarQube (when necessary):sonar-project.properties set sonar.sources/sonar.tests/sonar.python.coverage.reportPaths=coverage.xml; Quality Gate blocks on thresholds; tokens go through secrets.Only adopt for teams/long-term maintenance/compliance requirements—for solo scripts and one-off experiments, local ruff+mypy+pytest is enough; don't add maintenance surface for heavy infrastructure (YAGNI); for applicability boundaries see references.md the SonarQube section.
• CI: GitHub Actions goes in .github/workflows/*.yml；actions/checkout@v6 + actions/setup-python@v6(cache:"pip", caching is off by default and must be explicitly enabled);strategy.matrix.python-version multiple versions in parallel; typical pipeline checkout → install dependencies → ruff check → pytest; secrets injected via ${{ secrets.X }} .
• Maintenance meta-rules (when the repo has manifests/scripts): two sets of meta-rule details—asset manifest anti-drift (manifest validated by exact keys to prevent missed registration, AST checks script entry points, warning promoted to hard gate) and script self-test entry governance (explicit --selftest, offline synthetic assertions, optional dependencies "verify if available, degrade if not")—see references/asset_manifest_governance.md and references/skill_selftest_ci.md。
• Documentation: README (install/run/reproduce commands), key module comments, run instructions.

Debugging and Review

Four methods (locate the root cause before acting, don't patch at the symptom)—for details and elaboration see references/code_examples.md"Four Methods of Debugging and Review":

• Systematic debugging: read the error word by word → reproduce reliably → check recent changes → place boundary instrumentation to locate which layer is broken → trace the data flow in reverse to the source and fix; change only one variable at a time; if 3 consecutive fix attempts still fail → stop and question the architecture.
• Self code review: grade by Critical/Important/Minor; every suggestion passes five checks (technically correct/will it break things/why written this way/cross-platform/full context) + YAGNI; respond technically, not with performative agreement.
• Improve architecture: use the "deletion test" to diagnose shallow modules vs deep modules, and refactor shallow modules into "small interface hiding large implementation".
• Split subtasks/finish branch: isolate context, spec review before quality review; merge → rerun tests → remove worktree → delete branch, discarding work requires explicit confirmation.

Security Notice

When creating a network-exposed interface/service, if there is no authentication you must proactively point out the security impact (security_awareness), and do not silently ship an unauthenticated service.

Deliverables

Runnable code + tests + dependency/environment instructions + README + run commands. Structure is organized by a06.Standard handoff artifact when in the a03 experimental code stage:run_manifest.md(record run commands/environment/artifact paths/key metrics, hand off to m06; naming see CONVENTIONS §6.1). To get started you can directly copy the same-directory assets/project-scaffold/(includes pyproject.toml/.pre-commit-config.yaml/CI/example module+tests + CODE_REVIEW_CHECKLIST.md + scripts/(boundary debugging instrumentation), version numbers have been actually tested,pytest verified by actual runs). Recommended TDD (test-driven-development): first write a minimal failing test andwatch it fail with your own eyes(confirm it's a missing feature rather than a typo) → write the simplest implementation to go green → only refactor after green; write no production code without a failing test.For code comparison examples of minimal sufficient vs over-engineering, source validation vs symptom patching see references/code_examples.md。

Connection

Implement the m05 plan and the m02 pipeline; prioritize reusing the db03 method card's implementation_repo(verified official implementations/libraries, such as HuggingFace Transformers, scikit-learn, xgboost/lightgbm, diffusers) rather than reinventing the wheel; produce output for m06 analysis; register code versions in db09; hand off system-level design to a04.

• Paper reproduction implementation: the reproduction tasks approved by m05 "reproduce existing paper protocols" are implemented by this skill—write code according to its deviation budget and reproduction log format; the reproduction log's "change only one variable at a time" shares the same origin as this skill's systematic-debugging hypothesis-verification; among the three-way attribution of reproduction failure (implementation differences/data differences/problems in the original text), "implementation differences" is the part this skill can continue to approach, and when it points to "problems in the original text," hand it off to research-ethics; do not rashly assert in code that the original text is wrong.

---

For hard tool information (real endpoints/parameters/configurations/workflows), see the same directory's references.md. In-depth topics: for the TDD red flags and rationalization rebuttal table, see references/tdd_redflags.md; for the four stages of systematic debugging + boundary instrumentation, see references/debug_protocol.md(with runnable templates assets/project-scaffold/scripts/debug_instrument.sh and boundary_trace.py); self-review checklist assets/project-scaffold/CODE_REVIEW_CHECKLIST.md. For the asset inventory/manifest anti-drift verification pattern, see references/asset_manifest_governance.md; for skill scripts --selftest and the CI actual execution gate pattern, see references/skill_selftest_ci.md; for breakpoint recovery, quality gates, entry-document anti-drift, and commit discipline when maintaining the Light skill package, see references/light_skill_pack_maintenance.md。