light-backend-coding
后端代码编写、逻辑强、安全性高、可读性好、版本控制、代码审查。当任务需要写实验代码、模型代码、数据处理代码、可视化代码、后端接口或系统逻辑时使用。要求逻辑清晰、安全、可读、可维护、便于复现/扩展/部署。支持 Git 版本管理、代码审查、注释规范、README、依赖管理、环境配置、运行说明与项目结构整理。
git clone --depth 1 https://github.com/Light0305/Light-skills /tmp/light-backend-coding && cp -r /tmp/light-backend-coding/skills/light-backend-coding ~/.claude/skills/light-backend-codingSKILL.md
# 后端代码编写与审查
## 写代码前
读现有代码，匹配项目的风格、约定与依赖库，不擅自引入新框架(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`。论文引用规划、审查与多格式生成。当用户需要处理参考文献、引用、bibtex 时使用。审查引用的关联度、真实性、权威性、时效性、数量、中外占比，是否引用了经典/最新/代表性/对比工作。避免虚假引用、过度引用、无关引用、堆砌、遗漏关键文献、低质量来源、引用与正文不匹配。生成 BibTeX/EndNote/GB-T 7714/APA/IEEE 等格式并按目标 venue 调整。
竞赛与项目申报材料辅助。当用户做统计建模、数学建模、互联网+、挑战杯、大创、创新创业、科研训练等项目时使用。辅助写申报书、项目计划书、商业计划书、路演 PPT、答辩稿、项目摘要、技术路线、创新点、可行性分析、市场分析、研究基础、预期成果、经费预算、团队分工。用于非论文投稿场景，可与论文/软著/专利/PPT 联动。
统一风格与一致性维护。在论文、PPT、图表、代码、项目文档之间保持术语一致、视觉风格一致、逻辑线索一致、创新点表述一致（常驻，所有任务后台生效）。避免同一项目在不同材料中出现说法不一致、指标名称不统一、图表风格混乱、创新点前后矛盾、方法名称变化、数据集名称不统一、论文与 PPT 逻辑不一致、软著与系统功能不一致。
数据处理、数据质量分析与数据集构建。当用户需要清洗数据、处理缺失/异常值、特征工程、数据增强、划分数据集、评估数据质量，或需自建数据集（采集、标注规范、格式、说明文档、隐私合规、发布）时使用。在提 idea 前优先判断现有数据是否足以支撑研究。
从顶会大牛角度进行专业绘图与组图。当用户需要把规划好的图实际画出来时使用。按情况用 Python(matplotlib/seaborn/plotly/altair)、R(ggplot2)、MATLAB、Visio、Origin、LaTeX/TikZ、Illustrator、PowerPoint 等。审美统一、专业清晰、配色合理、字体规范、线条清楚、高分辨率，适合直接投稿。不仅画图，还从论文表达角度判断怎么排、怎么组、怎么标注、怎么突出重点。
根据论文内容规划应该做哪些图、哪些表、插在哪里、各起什么作用。当用户需要论文图表规划时使用。图表不限于统计图，也包括数据集真实效果图、模型输出示例、案例展示、可解释性可视化等。规划框架图、技术路线图、数据集示意图、模型结构图、算法流程图、结果对比/消融/敏感性图、真实效果图、统计表/对比表等，以审稿人标准判断哪些必做、哪些冗余。
强大地读文件并学习——Word、PDF、PPTX、Excel、CSV、图片、视频、代码、压缩包等。当用户提供任何文件、问"这个文件讲了什么"、或任务需要理解已有材料时使用（常驻，自动触发）。不只提取文字，而是理解结构、逻辑、图表、数据、实验结果、格式要求、章节关系、视觉风格、隐含要求与可复用内容，并转化为可执行任务。
独特吸睛、审美好、有特色、美观全面的前端设计。当任务涉及前端界面、项目展示页、系统演示、大屏可视化、可视化平台、微信小程序 UI、移动端界面、设计系统、Tailwind v4、shadcn/ui、Next.js、React、Vite、可访问性、动效、重设计审计时使用。不只是能用，而是好看、统一、清晰、有亮点、有视觉记忆点，适合展示/答辩/演示/落地。按主题选风格：科技感、学术感、农业智慧化、数据可视化、极简、玻璃拟态、卡片式、大屏、管理系统、移动端、小程序等。