caixinyu2017-star 后端代码编写与审查
写代码前
读现有代码，匹配项目的风格、约定与依赖库，不擅自引入新框架(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还原确定性环境。
- uv（推荐，Rust 实现快 10-100x）：
- 测试：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.mdSonarQube 节。
- Ruff：
- 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。