agentic-ctx/references/coding-guidelines.md

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

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