- 命令入口统一使用 Makefile。对于代码项目最后暴露出来的构建、测试、运行、导出、部署等接口，优先提供 `make build`、`make test`、`make run` 等目标，便于用统一方式操作项目；已有成熟脚本时，用 Makefile 封装而不是替换底层脚本。
- 特殊命令参数写入 Makefile 注释。涉及特定参数、环境变量、导出路径、部署步骤等非通用用法时，在 Makefile 注释或相邻文档里说明有哪些命令、每个命令如何使用。
- 优先交付能真实运行的结果。不要用 fake data、hardcoded fallback、`_KNOWN_WORKS`、宽泛 `try/except` 或静默降级来伪装项目可运行；如果真实环境跑不通，就继续定位和修复，或者明确报告真实阻塞。
- 先理解现有工程再改代码。读当前架构、已有脚本、测试、日志和约定，沿用项目已有模式；除非为了解决当前问题，不做无关重构。
- 对 bug 和性能问题要基于证据定位。先复现、读日志、抽取时间线或配置指纹，再给结论；不要把单次失败泛化成架构约束或模型/系统“不支持”。
- 实现时保持小而硬的边界。模块职责清晰，函数命名明确，避免深层嵌套和过度抽象；新增依赖要谨慎，能用标准库或现有工具解决时不要引入重库。
- 测试要覆盖真实风险。新增功能或修复 bug 时补聚焦测试，尽量先跑失败再修复；改完必须运行相关测试/构建命令，并在结果里说明验证情况。
- Python 项目优先使用当前虚拟环境和项目工具链。通常先 `source .venv/bin/activate`，再用项目已有的 `uv run`、`uv pip`、`python -m pytest` 等方式执行，避免直接用系统 Python。
- 数据和中间产物要便于后续 agent 使用。涉及 dashboard、日志、结果、trace、配置比较等场景时，优先提供稳定的本地文件、JSON/JSONL、URL 或导出命令，让其它本地程序可以继续处理。
- 前端/可视化要先做真正可用的界面。不要把需求做成营销页；列表数据要考虑分页、lazy load 或只展示前 N 条，避免长期使用后性能退化。
- 浏览器插件和本地部署类任务要记录踩坑。Safari extension、签名、Xcode、nginx、后台服务等一旦验证出可行流程，应把关键步骤沉淀成文档或 skill，避免下次重复犯错。
- 需要 commit 时保持仓库整洁。整理应提交和应忽略的文件，避免把构建产物、临时文件、备份文件误提交；提交前运行必要检查并报告 commit SHA。
- 回复风格以直接可用为准。能直接给替换文本、命令、文件路径或结论时就直接给；解释要服务于决策，不要泛泛而谈。

## Research Agent Context

- 需要科研判断、论文审查、实验审计、evaluation 组织、论文图审查或技术文档整理时，先读取 `SOUL.md`，再按其中的 Skill Routing 选择一个最小匹配文件。
- 保持模块边界：`skills/` 放单一能力，`workflows/` 放多阶段流程，`references/` 放稳定参考材料。不要把临时项目笔记混入长期 context。
- Review 类输出要有证据定位和严重程度；实验类输出要能回到原始数据、脚本、图表或论文段落。