From 3e6eeb857e96eb714fc6b9627db62a7ff7a7667f Mon Sep 17 00:00:00 2001
From: Gahow Wang <gahow.wang@gmail.com>
Date: Tue, 19 May 2026 14:27:21 +0800
Subject: [PATCH] Organize minimal agent context routing

---
 AGENTS.md                       | 32 ++++++++++-----------
 references/coding-guidelines.md | 45 +++++++++++++++++++++++++++++
 workflows/development.md        | 50 +++++++++++++++++++++++++++++++++
 3 files changed, 110 insertions(+), 17 deletions(-)
 create mode 100644 references/coding-guidelines.md
 create mode 100644 workflows/development.md

diff --git a/AGENTS.md b/AGENTS.md
index 1e53a1d..c1f3329 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,19 +1,17 @@
-- 命令入口统一使用 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。
-- 回复风格以直接可用为准。能直接给替换文本、命令、文件路径或结论时就直接给；解释要服务于决策，不要泛泛而谈。
+# Agentic Context Router
 
-## Research Agent Context
+目标：首屏 context 只负责路由，不承载长规则。先判断任务意图，只读取最小匹配文件。
 
-- 需要科研判断、论文审查、实验审计、evaluation 组织、论文图审查或技术文档整理时，先读取 `SOUL.md`，再按其中的 Skill Routing 选择一个最小匹配文件。
-- 保持模块边界：`skills/` 放单一能力，`workflows/` 放多阶段流程，`references/` 放稳定参考材料。不要把临时项目笔记混入长期 context。
-- Review 类输出要有证据定位和严重程度；实验类输出要能回到原始数据、脚本、图表或论文段落。
+## Routing
+
+- AI Infra 日常开发、GPU 测试、长期实验环境：`workflows/development.md`
+- 科研判断、论文审查、实验审计、evaluation、论文图、技术文档：先读 `SOUL.md`，再按其中 routing 选择一个最小匹配文件。
+- 代码修改、构建、测试、部署、commit：读取 `references/coding-guidelines.md`。
+- benchmark crime 背景材料：只有在 benchmark 审计需要展开参考时读取 `references/benchmarking-crimes.md`。
+
+## Context Hygiene
+
+- 每个 context 文件只表达一个稳定意图：skill、workflow 或 reference。
+- 优先写触发条件、输入、输出、验收标准和 artifact 模板。
+- 不沉淀一次性项目细节、长日志、会议流水账、大段背景材料或可由 git/history/实验目录恢复的信息。
+- 能路由就不要复制；能引用文件路径就不要内联全文。
diff --git a/references/coding-guidelines.md b/references/coding-guidelines.md
new file mode 100644
index 0000000..5c6c237
--- /dev/null
+++ b/references/coding-guidelines.md
@@ -0,0 +1,45 @@
+# 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
+
+- 优先给可直接使用的文本、命令、路径和结论。
+- 解释只服务于决策，不输出泛泛背景。
diff --git a/workflows/development.md b/workflows/development.md
new file mode 100644
index 0000000..ecbafa2
--- /dev/null
+++ b/workflows/development.md
@@ -0,0 +1,50 @@
+# AI Infra Development Workflow
+
+用于 AI Infra research 项目的 GPU 开发测试和长期实验。默认 GPU 相关工作发生在 `dash*` 共享机器上。
+
+## Host Model
+
+- GPU hosts 命名为 `dash0`, `dash1`, ...；以当前 `~/.ssh/config` 为准，直接 `ssh dash*`。
+- 如果某台配置过的 `dash*` 无法连接，视为机器已下线，跳过即可。
+- 所有 `dash*` mount 同一个 NAS-backed `$HOME`；HOME 内路径在不同机器上等价。
+- 不需要在不同 `dash*` 之间做额外文件同步。
+- 个人 git remote 通常是 gitea，例如 `git@gitea:gahow/<repo>.git`。
+
+## Before GPU Work
+
+占用 GPU 前必须先判断空闲卡数。不要默认独占共享机器。
+
+1. 枚举候选 `dash*`。
+2. 跳过无法 ssh 的机器。
+3. 在可达机器上运行 `nvidia-smi`。
+4. 检查空闲 GPU 数、显存占用和已有用户进程。
+5. 只在有足够空闲 GPU 的机器上启动开发测试或实验，并记录 host 与 GPU ids。
+
+## Code And Data
+
+- 代码同步：使用 git；必要时 push/pull 到个人 gitea。
+- 大规模日志、checkpoint、trace、临时数据：保留在 `dash*` 可访问的本地/NAS 路径，不进 git。
+- 长期实验必须记录 repo commit、命令、配置、机器名、GPU 分配、日志路径和启动时间。
+- 能被后续 agent 继续处理的结果，优先落成稳定文件：JSON/JSONL、CSV、日志目录、分析脚本或 README。
+
+## Rules
+
+- 不要因为某个 `dash*` 连接失败而中断整个任务；继续尝试其它 `dash*`。
+- 不要假设不同机器有不同 HOME；除非用户特别说明，路径在所有 `dash*` 上等价。
+- 不要把大日志或实验产物加入 git；只提交代码、脚本、配置模板和必要文档。
+- 如果真实 GPU 环境跑不通，报告机器、命令、错误和已检查的 GPU 状态。
+
+## Minimal Run Record
+
+```yaml
+repo:
+commit:
+host:
+gpu_ids:
+command:
+config:
+start_time:
+log_path:
+result_path:
+notes:
+```