AGENTS.md git:20260909.7a703feA

Immutable. This exact content never changes and is served at /api/v1/blob/84b51a50aa844525.

# AGENTS.md - OMK 项目约定

OMK（Observe. Measure. Know.）通过固定模型、改变知识载体，观测和测量 prompt、RAG、skill、agent、workflow 的版本差异。所有改动优先保护测量可比性、证据完整性和用户数据。

本文件是工具中立的项目入场清单。Claude Code 通过 CLAUDE.md import；不为不同工具复制维护第二份项目规则。

## 开工与交付

- 涉及 commit、PR、分支或发版时，读取 CONTRIBUTING.md 的相关流程；同一任务已读且未变化时复用。
- 修改子目录前，检查从仓库根到目标文件路径上的 AGENTS.md，最近的文件补充或覆盖上层项目约定；普通局部任务不遍历全仓规则。
- 开工先明确需求、非目标、受影响边界和风险。用户确认方向后，在已授权的交付链内连续推进，不在实现、验证、自主 CR 等常规步骤间反复询问下一步。合并和发版分别按已有授权判断，不将合并等同于发布授权。
- 默认直接替换旧实现，不为没有明确需求的旧入口、旧字段或旧行为保留兼容层、别名和双轨分支。涉及已发布的公共契约或存量数据时，先说明影响与替换／迁移方案，向用户确认后执行，不自行决定兼容，也不直接做破坏性替换；当前任务已有明确决定时不重复确认。必要的破坏性变更仍须遵守下述版本化与迁移要求。
- 长任务及时更新对应 Issue／PR 的已有执行清单，状态以实际完成情况为准。
- 开发反馈优先跑受影响验证；首次 push 前默认跑一次 yarn ci，除非用户明确要求更窄验证，或改动仅限不影响生成产物、链接、打包与行为的手写文档／规则。首次 push 后事实未变化时，不为交付机械重跑本地门禁；存在远端 CI 时，以其结果补充确认。事实变化时，后续修复成批完成，并按影响范围重跑精准验证或完整门禁，不把远端 CI 当作增量反馈环。
- clean-room 验收只在发布、打包／安装契约变化、真实用户入口变化或风险审查明确要求时执行；触发条件、被测边界与证据未变化时不重复执行。
- 人工启动 Studio 供用户查看时，优先使用用户指定的固定端口，否则使用 CLI 默认固定端口；不主动传 `--port 0`。端口占用时先识别已有服务，确认属于本任务后再复用或重启，不擅自改用随机端口。随机端口仅用于隔离自动化测试或用户明确要求的场景；展示地址仍使用 `server.start()` 返回值。

## 自主 CR 与完成定义

- 改变行为、契约、打包、文档承诺或仓库规则的改动，在首次 push／交付前自主完成一次 CR；纯机械改动快速复核，深度与风险匹配。
- 首次自主 CR 前必须完整阅读 [`CODE_REVIEW.md`](./CODE_REVIEW.md)；同一任务规则未变化时复用，不重复加载。以审查者视角只读检查最终变更、直接调用边界、契约和验证证据；发现跨模块影响时沿证据扩大范围。可使用独立 reviewer，否则做 fresh-pass 自审。
- P0～P2 在交付前解决，P3 解决或登记 follow-up。修复后复查受影响面并重跑受影响验证；只有架构／公开行为实质变化、CI 新问题、重要 rebase 冲突或外部审查提出新高风险方向时，才重新做完整 CR。
- Finding 的证据、优先级和格式遵守 CODE_REVIEW.md。无 finding 时明确说明，不制造猜测性问题；门禁、真实用户路径和未验证范围如实报告，不以 CI 绿色代替需求完成。
- 用户要求审查具体 PR 时，将结论直接发布到对应 PR；用户明确要求仅本地审查时不发布，未指定或无法确定对应 PR 时不猜测发布对象。

### CR 运行产物隔离

- artifacts/cr/ 和 knowledge/cr/ 不是源码资产，不得在仓库内创建或保留，也不用 .gitignore 隐藏。纯只读审查不创建过程文件；只有实际运行会写盘的 CR 工具时，才用唯一仓库外临时目录保存全部运行产物，并显式配置输出路径，不得执行回写仓库的结果同步。
- CR 前后检查工作树状态，确保审查工具未产生额外污染，不清理或覆盖用户原有修改。Issue／PR／CI 是持久审查记录；只有用户明确要求时才将报告作为项目资产提交。

## Code Review Rules

- 不静默改变评分口径、统计语义、prompt 字节、Schema identity 或持久化契约。必要变更显式版本化，在 PR 标题／描述标记对应 BREAKING-*、迁移及测量影响。
- eval-core 保持宿主无关和确定性，不反向依赖 CLI、文件系统、网络、环境变量、具体执行器或 Studio。Core 只表达纯契约与确定性变换，副作用放在 eval-workflows 或对应 adapter。
- 保留来源、时间、关联身份与原始证据；派生视图不覆盖原始证据，观测信号不冒充因果结论。
- 测试使用显式临时根和环境隔离，覆盖失败／中断后的 cleanup 路径；生产写入只落到公开存储契约允许的位置，不擅自写用户目录或全局状态。
- 新建或可安全改名的判别字段使用 eventKind、runtimeKind 等限定名；裸 kind 默认保留给 Artifact.kind。已发布、落盘或对外暴露的 public schema 既有 kind 不顺手改名；必要改名单独迁移并保持旧文件可读。细节见 docs/specs/terminology-spec.md §5.4。
- 用户可见服务 URL 使用 server.start() 返回的实际地址，不硬编码端口。
- .agents/skills/omk/ 是官方 Skill 单一来源，.claude/skills/omk 保持软链，不复制第二份；本文件不重复 Skill 用户教程。

## Git 与写作

- main 是唯一长期分支；从 main 创建短分支，通过 PR 合并，不直接提交 main，也不恢复 develop 流程。发版通过短分支 PR 回 main，再由 tag 触发；具体流程见 CONTRIBUTING.md。
- 分支默认使用 codex/ 前缀。提交格式为 type(scope): 中文 subject，scope 使用稳定模块名，本文件使用 agents-md。
- 用户可见文案中文优先，中文使用全角标点；代码、路径、命令、URL、frontmatter、数学区间、技术标识符及英文技术括注保留对应语法。Conventional Commits 的 type(scope): 前缀保持半角。
- LLM judge 统一称为“评委”，不称“判官”。PR 审查评论语言跟随用户操作系统设置语言。
- PR 说明用户影响、迁移及测量限制，链接相关 Issue／前置 PR；不堆叠行号、测试清单或 diff 已体现的嵌套实现细节。

## 参考入口

- 用户文档：README.md、README.zh.md。
- Skill：.agents/skills/omk/SKILL.md。
- 审查：CODE_REVIEW.md。
- 设计规范：docs/。
- Git 与发版：CONTRIBUTING.md。