# Coding Guidelines

用于代码修改、debug、构建、测试、部署或 commit。纯科研 review、论文写作、paper reading 不读取本文件。

## Goal

交付真实可运行、可验证、diff 小的工程改动。

## Commands

- 项目对外入口优先封装成 Makefile targets，例如 `make build`、`make test`、`make run`。
- 已有成熟脚本时，用 Makefile 包一层，不替换底层脚本。
- 特殊参数、环境变量、导出路径、部署步骤写在 Makefile 注释或相邻文档里。

## Implementation

- 先读现有架构、脚本、测试、日志和约定，再改代码。
- 只改与任务直接相关的行；不做无关重构、格式化或清理。
- 匹配现有风格。
- 保持模块边界小：职责清晰、命名明确、控制流浅、不做 speculative abstraction。
- 谨慎新增依赖；标准库或现有工具能解决时不要引入重库。
- 不用 fake data、hardcoded fallback、`_KNOWN_WORKS`、宽泛 `try/except` 或静默降级伪装可运行。

## Debug And Test

- bug 和性能结论必须基于复现、日志、时间线、配置指纹或测量。
- Python 项目优先用当前虚拟环境和项目工具链，例如 `source .venv/bin/activate`、`uv run`、`uv pip`、`python -m pytest`。
- 新功能或 bugfix 按风险补聚焦测试。
- 改完运行相关测试/构建，并报告准确验证结果。

## Artifacts

- 数据和中间产物优先落成稳定文件：JSON/JSONL、CSV、日志、URL、dashboard、trace 或 export command。
- 前端/可视化要交付真实可用界面，不做营销页；大列表要分页、lazy load 或限制展示规模。
- 浏览器插件和本地部署流程一旦验证可行，把关键步骤沉淀成 docs 或 skill。

## Git

- commit 前整理工作区：只纳入目标源码/文档，排除构建产物、临时文件、备份和大型实验 artifact。
- 提交前运行必要检查，并报告 commit SHA。

## Response

- 优先给可直接使用的文本、命令、路径和结论。
- 解释只服务于决策，不输出泛泛背景。