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.
• Secure: 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 go into [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 outputs --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, which only checks obvious type errors and does not require 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 override), test code can ignore_errors. The scaffold's pyproject.toml already includes [tool.mypy] basic configuration + strict toggle comments, and does not conflict with the uv approach.
  • pre-commit：.pre-commit-config.yaml of repos Use rev lock versions (tag/SHA, do not use floating branches); connect astral-sh/ruff-pre-commit of ruff(args:[--fix])+ruff-format；pre-commit install enable, 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 thresholds; token goes through secrets.
• CI: GitHub Actions put .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 use ${{ secrets.X }} injection.
• Maintenance meta-rules (when the repository has manifests/scripts): asset manifest prevents drift (manifest validated by exact keys to prevent missed registration, AST checks script entry points, warnings promoted to hard gate) and script self-test entry governance (explicit --selftest, offline synthetic assertions, optional dependencies "verify if available, degrade if unavailable") — for details of the two sets of meta-rules 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, do not patch at the symptom) — details and elaboration see references/code_examples.md"Four Methods of Debugging and Review":

• Systematic debugging: read the error word by word → reproduce stably → check recent changes → instrument boundaries to locate which layer is broken → trace the data flow backward to the source and fix; change only one variable at a time; if 3 consecutive fixes still fail → stop and question the architecture.
• Self code review: grade by Critical/Important/Minor; every suggestion goes through five checks (technically correct/will it break anything/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 transform shallow modules into "small interface hiding large implementation".
• Split subtasks/wrap up branches: isolate context, spec review before quality review; merge → rerun tests → remove worktree → delete branch, discarding work requires explicit confirmation.

Security notes

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 launch an unauthenticated service.

Deliverables

Runnable code + tests + dependency/environment description + README + run commands. Structure is organized by a06.Standard handoff artifact when working in the a03 experimental code phase:run_manifest.md(record run commands/environment/artifact paths/key metrics, hand off to m06; naming see CONVENTIONS §6.1). To start, you can directly copy the same directory's 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 actually runs and passes). Recommended TDD (test-driven-development): first write the minimal failing test andwatch it fail with your own eyes(confirm it is a missing feature rather than a typo) → write the simplest implementation to turn it green → refactor only after green; do not write production code without a failing test.For code comparison examples of minimal sufficiency 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; output for m06 analysis; code versions registered in db09; system-level design handed off to a04.

• Paper reproduction implementation: The reproduction task approved by m05 "Reproduce Existing Paper Protocol" is implemented by this skill—code is written 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 difference/data difference/original-text problem), "implementation difference" is the part this skill can continue to approach, and when it points to an "original-text problem," 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/configuration/workflows), see the same directory 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 list/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 a Light skill package, see references/light_skill_pack_maintenance.md。