Light Backend Coding

---
name: light-backend-coding
description: 后端代码编写、逻辑强、安全性高、可读性好、版本控制、代码审查。当任务需要写实验代码、模型代码、数据处理代码、可视化代码、后端接口或系统逻辑时使用。要求逻辑清晰、安全、可读、可维护、便于复现/扩展/部署。支持 Git 版本管理、代码审查、注释规范、README、依赖管理、环境配置、运行说明与项目结构整理。
user-invocable: false
---

# 后端代码编写与审查

## 写代码前
读现有代码，匹配项目的风格、约定与依赖库，不擅自引入新框架(CONVENTIONS)。明确输入输出、边界条件、复现要求(种子/版本)。

## 代码质量标准
- **逻辑清晰**：单一职责、小函数、清楚的数据流。
- **安全**：参数化查询、输入校验、异常处理；不硬编码密钥(走环境变量/配置)；不回显敏感值(a10)。
- **可读**：命名达意、注释解释"为什么"而非"是什么"、与周围代码同密度。
- **可维护/可扩展**：低耦合、配置化(Hydra)、避免过度工程。
- **可复现**：固定随机种子、锁依赖版本、记录环境、确定性数据划分。

## 工程实践
- **版本控制**：Git；功能分支不直接推 main；有意义的提交信息；仅用户明确要求才提交/推送。
- **依赖/环境**：
  - uv（推荐，Rust 实现快 10-100x）：`uv init` → `uv add <pkg>` → `uv lock`/`uv sync`(按 `uv.lock` 精确复现) → `uv run`；`uv python pin 3.11` 锁 Python 版本。
  - Poetry：`poetry add` → `poetry install`(按 `poetry.lock`)；依赖放 PEP 621 `[project.dependencies]`，dev 依赖入 `[tool.poetry.group.dev]`；CI 固定 Poetry 版本。
  - 始终提交 lock 文件，CI 用 `uv sync`/`poetry install` 还原确定性环境。
- **测试**：pytest——文件 `test_*.py`、函数 `test_*` 自动发现，纯 `assert`；`@pytest.fixture`(scope function/module/session) 做依赖注入，`@pytest.mark.parametrize` 跑多组输入，共享 fixture 放 `conftest.py`。新功能/修 bug 先配测试，改完跑 `pytest -x` 验证。覆盖率 `pytest --cov=pkg --cov-report=term-missing`，CI 出 `--cov-report=xml`。
- **质量门**：
  - Ruff：`[tool.ruff.lint]` 用 `select`/`extend-select`(如加 `B`)/`ignore`(如 `E501`)；`[tool.ruff]` 设 `line-length`/`target-version`；CI 分别跑 `ruff check .` 与 `ruff format --check .`(linter 与 formatter 是两个命令)。
  - **静态类型检查（mypy / pyright）**：按项目性质选档——**新项目/科研代码用 pyright basic（或 mypy 基础档，仅检明显类型错、不强制全注解）起步**，**库代码/对外 API 用 `mypy --strict`（要求全量注解，最严）**。CI 加一步 `mypy src`；第三方无 stub 时 `ignore_missing_imports`（库代码按模块 override 收紧），测试代码可 `ignore_errors`。scaffold 的 `pyproject.toml` 已带 `[tool.mypy]` 基础配置 + strict 切换注释，与 uv 路线不冲突。
  - pre-commit：`.pre-commit-config.yaml` 的 `repos` 用 `rev` 锁版本(tag/SHA，勿用浮动分支)；接 `astral-sh/ruff-pre-commit` 的 `ruff`(`args:[--fix]`)+`ruff-format`；`pre-commit install` 启用，CI 跑 `pre-commit run --all-files`。
  - SonarQube(必要时)：`sonar-project.properties` 设 `sonar.sources`/`sonar.tests`/`sonar.python.coverage.reportPaths=coverage.xml`；Quality Gate 卡阈值；token 走 secrets。**仅团队/长期维护/有合规要求时才上**——单人脚本、一次性实验靠本地 ruff+mypy+pytest 即够，别为重型基建徒增维护面(YAGNI)；适用边界详见 `references.md` SonarQube 节。
- **CI**：GitHub Actions 放 `.github/workflows/*.yml`；`actions/checkout@v6` + `actions/setup-python@v6`(`cache:"pip"`，缓存默认关须显式开)；`strategy.matrix.python-version` 多版本并行；典型流水线 checkout → 装依赖 → `ruff check` → `pytest`；secrets 用 `${{ secrets.X }}` 注入。
- **维护元规则（仓库有清单/脚本时）**：资产清单防漂移（manifest 按精确键校验防漏登、AST 查脚本入口、warning 升 hard gate）与脚本自测入口治理（显式 `--selftest`、离线合成断言、可选依赖"可用则验证不可用则降级"）两套元规则细节见 `references/asset_manifest_governance.md` 与 `references/skill_selftest_ci.md`。
- **文档**：README(安装/运行/复现命令)、关键模块注释、运行说明。

## 调试与审查
四套方法（动手前先定位根因，不在症状处打补丁）——细节与展开见 `references/code_examples.md`「调试与审查四法」：
- **系统化调试**：逐字读错误→稳定复现→查最近改动→边界埋点定位坏在哪层→反向追数据流到源头修；一次只改一个变量；连修 3 次仍失败→停手质疑架构。
- **自我代码审查**：按 Critical/Important/Minor 分级；每条建议过五查（技术正确/会否破坏/为何这么写/跨平台/上下文全）+ YAGNI；回应技术化不表演性赞同。
- **改进架构**：用"删除测试"诊断浅模块 vs 深模块，把浅模块改造成"小接口藏大实现"。
- **拆子任务/收尾分支**：隔离上下文、规格审查先于质量审查；合并→重跑测试→移 worktree→删分支，丢弃工作需显式确认。

## 安全提示
创建网络暴露的接口/服务时，若无鉴权必须主动指出安全影响(security_awareness)，不静默上线无认证服务。

## 产出
可运行代码 + 测试 + 依赖/环境说明 + README + 运行命令。结构交 a06 规整。**作 a03 实验代码阶段时的标准交接工件：`run_manifest.md`**（记录运行命令/环境/产物路径/关键指标，交 m06；命名见 CONVENTIONS §6.1）。
起步可直接复制同目录 `assets/project-scaffold/`（含 `pyproject.toml`/`.pre-commit-config.yaml`/CI/示例模块+测试 + `CODE_REVIEW_CHECKLIST.md` + `scripts/`(边界调试埋点)，版本号已实测、`pytest` 实跑通过）。
推荐 TDD(test-driven-development)：先写最小失败测试并**亲眼看它失败**(确认是功能缺失而非拼写错)→ 写最简实现转绿 → 绿灯后才重构；无失败测试不写生产代码。**最小够用 vs 过度工程、源头校验 vs 症状补丁的代码对照例见 `references/code_examples.md`。**

## 衔接
实现 m05 方案与 m02 流水线；优先复用 db03 方法卡的 `implementation_repo`（已验证的官方实现/库，如 HuggingFace Transformers、scikit-learn、xgboost/lightgbm、diffusers）而非从零造轮子；产出供 m06 分析；代码版本登记 db09；系统级设计交 a04。
- **论文复现落地**：m05「复现已有论文协议」放行的复现任务由本技能实现——按其偏差预算与复现日志格式落代码，复现日志的"逐次只改一个变量"与本技能 systematic-debugging 的假设-验证同源；复现失败的三分归因（实现差异/数据差异/原文问题）中"实现差异"是本技能可继续逼近的部分，指向"原文问题"时移交 research-ethics，勿在代码里轻率断言原文有错。

---
工具硬信息(真实端点/参数/配置/工作流)见同目录 `references.md`。
深用专题：TDD 红旗与合理化反驳表见 `references/tdd_redflags.md`；系统化调试四阶段+边界埋点见 `references/debug_protocol.md`（配套可跑模板 `assets/project-scaffold/scripts/debug_instrument.sh` 与 `boundary_trace.py`）；自审清单 `assets/project-scaffold/CODE_REVIEW_CHECKLIST.md`。
资产清单/manifest 防漂移校验模式见 `references/asset_manifest_governance.md`；技能脚本 `--selftest` 与 CI 实际执行门模式见 `references/skill_selftest_ci.md`；维护 Light 技能包时的断点恢复、质量门、入口文档防漂移与提交纪律见 `references/light_skill_pack_maintenance.md`。