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 reproducibility 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 that 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; feature branches, do not push 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(exactly reproduce according to uv.lock ) → 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 in [tool.poetry.group.dev]; CI pins the Poetry version.
  • Always commit the lock file; CI uses 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) does dependency injection,@pytest.mark.parametrize runs multiple sets of inputs, shared fixtures go in conftest.py. Write tests first for new features/bug fixes; 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 project's nature—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 step to CI: mypy src; when a third party has no stubs, ignore_missing_imports(tighten library code per-module with override), test code may ignore_errors. scaffold's pyproject.toml already comes with [tool.mypy] basic configuration + strict toggle comments, which does not conflict with the uv approach.
  • pre-commit：.pre-commit-config.yaml 's repos Use rev lock the version (tag/SHA, do not use a floating branch); connect astral-sh/ruff-pre-commit 's 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 on thresholds; tokens go through secrets.Only adopt when team/long-term maintenance/compliance requirements exist—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 SonarQube section.
• CI: GitHub Actions goes in .github/workflows/*.yml；actions/checkout@v6 + actions/setup-python@v6(cache:"pip", cache 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 repository has manifests/scripts): two sets of meta-rule details—asset manifest drift prevention (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 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 root cause before acting, don't 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; after 3 consecutive failed fixes → stop and question the architecture.
• Self code review: grade by Critical/Important/Minor; every suggestion goes through 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/wrap up branches: 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 not silently ship an unauthenticated service.

Deliverables

Runnable code + tests + dependency/environment description + README + run commands. Structure is organized by a06.The standard handoff artifact when acting as 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 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). TDD (test-driven-development) recommended: first write the smallest failing test andwatch it fail with your own eyes(confirm it's a missing feature, not a typo) → write the simplest implementation to turn it green → refactor only after green; 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 reuse of 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 system-level design to a04.

• Paper reproduction implementation: reproduction tasks cleared by m05 "reproduce an existing paper protocol" 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 difference/data difference/problem in the original text), "implementation difference" is the part this skill can continue to approach; when it points to "problem in the original text", hand it over to research-ethics, and 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'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。