Universe-Keyboard: Instructions file for Codex

AGENTS.md

本仓库的 AI 协作规则。所有 agent 在开始工作前必须先阅读本文件。

基本沟通规则

• 始终使用中文回复。
• 除非用户明确要求实施或修改，否则先讨论方案，不直接改文件。明确授权后，在该任务范围内持续推进；不因加载技能、角色切换或上下文压缩重复请求相同授权。
• 代码改动必须优先保证可读性。
• 可以适当增加注释，但注释应解释意图、边界或复杂原因，避免复述代码。
• 遇到不确定问题时，先核查事实并区分假设。已授权范围内的常规实现选择可自主决定；影响产品合同、权限、必需证据或不可逆动作的缺口才请求决定。
• 适当使用第一性原理分析：输入是什么、状态在哪里、副作用是什么、输出如何验证。

工作入口

新会话开始时先阅读：

1. AGENTS.md
2. docs/KNOWLEDGE_INDEX.md
3. docs/ACTIVE_WORK.md（当前 Active 工作项 ≤10；生命周期以 Assignment 为准）
4. 按 docs/READING_MAPS.md 中的任务类型加载对应文档
5. 涉及代码改动时再阅读 docs/PROJECT_CONTEXT.md
6. 运营卫生规则见 docs/kos/kos-2.1-operational-maturity.md（不替代 KOS 2.0 冻结原则）
7. KOS 2.2 目前为 advisory，Adopted pin v0.9.0：E-01、A-01/B-01、P-01、D-01 仍仅供新记录显式 opt-in；v0.9.0 的 M-02 触发身份/非递归收尾适用于本决定后的触发，reviewer 范围/预算/停止条款适用于决定后新分配的独立 lane。细则见 docs/kos/UPGRADE_STATUS.md 与 .kos/project.json。校验绿不是 Product / merge / Release。未授权 required。
8. Task Workspace（opt-in，UK-007）：只对 Assignment 明确写明采用 ops/task-workspace.md（Kit commit 9ca6dc015bf01084150538aac65cedc25b2a33a5，见 docs/kos/UPGRADE_STATUS.md）的新任务生效；现有 Active 任务、Codex 任务与 Worktree 不迁移、不修改。拿到 Task ID 时：① 在 docs/assignments/ 按 record_id 定位 Assignment（找不到再按 Task ID 搜 PR 与远端分支）；② 定位 carrier 分支；③ fetch 后读该分支 head 上的 docs/tasks/<TASK-ID>/BRIEF.md、log.md，以及 AUTH、Plan 和 read_on_demand 指向的必要证据；④ 确认当前阶段、Checkpoint 与剩余工作；⑤ 先按合同第四、八节核对 Writer，再动手：若无待接收 P，且从 log.md 推出的 W 是本 Agent、授权有效，可以继续写任务；若待接收 P 指向本 Agent，且第八节核对满足接收条件（共同前置条件成立并命中第 3 行，含 H == S），只可提交并推送 ACCEPT，ACCEPT 推送成功后才取得任务代码和其他授权路径的写权；镜像与 log 冲突、状态未知或不满足接收条件，必须停止，不得推测权限；Human 署名的异常接管仍按合同第四节执行，本条不扩大其权限；⑥ 在有效授权内继续；⑦ 重要进度变化时写 Checkpoint。无法访问仓库或 GitHub 的 Agent 须明确请求所需资料，或由 Human 中转。无法判断阶段调整是否属于已授权的非实质性细节时，停止并请求 Human。本入口不绑定模型、客户端或厂商，也不是完全自动化的跨平台接管或排他锁。

CONTEXT_INDEX.md 保留为详细文档注册表，不再是新会话的第一导航入口。 需要确定长期团队所有权、跨线程协作或永久线程 bootstrap 时，阅读 docs/VIRTUAL_ENGINEERING_TEAM.md。 正式任务进入 Ready 或开始执行前，必须按 docs/ASSIGNMENT_POLICY.md 核对 Assignment；任何必需字段为 UNKNOWN 时停止并交回 Product Lead。边界明确的只读问题使用该 Policy 的例外。阶段依赖与当前授权解释见 docs/AI_WORKFLOW.md。 需要领域 agent 时，必须选择 docs/playbooks/ 下的对应操作手册，并遵守其停止、交接和证据规则。