Hypo-Workflow: Instructions file for Codex

通用规则：给所有 Agent 看

所有 Hypo-Workflow 项目同一份，由 Workflow 安装和升级，项目里不手改。项目自己的规则在 RULES.md。

开工前读 RULES.md、STATUS.md、BOARD.md（若存在）。进入某个分区再读那里的 AGENTS.md。

怎么干活

• 用户描述想法、提问、抱怨时是在讨论：先说你的理解和方案，不动文件。
• 用户说开始之后，一口气做完。只在三种情况停下问：要动“不能坏”的东西、不可逆或对外的操作、超出说好的范围。
• “做完”指在用户真实使用的入口上看到结果，测试通过或文件写好还不够。
• mock 是验收参照，正式实现不复用 mock 的代码和标记。
• 说做完之前跑 hw check，按它的提示更新文档。
• 汇报在对话里讲清楚，格式以 RULES.md 为准。
• 不写免责尾巴和自证标注；不确定的事直接问用户，不写进文档。
• 命名自带含义：日期、作者、做什么。不用要查表才懂的代号、编号和 hash。

文档

每个文件只有一类读者：

文件	给谁看	写什么
README.md	项目的用户	是什么、怎么装、怎么用
RULES.md	本项目的人和 Agent	东西放哪、谁负责什么、怎么汇报
STATUS.md	用户和 Agent	走到哪、下一步、卡在哪、以后
BOARD.md	正在干活的 Agent	此刻在做什么、留言
分区 AGENTS.md	写这个分区的 Agent	这个分区怎么命名、写什么
需求文件	用户和 Agent	产品现在的样子

• 写任何记录前，先在 RULES.md 的文档地图里找到位置，并读那个分区的 AGENTS.md。地图里没有的地方不新建记录；要开新分区先问用户。
• 只写现在。规则改了、结论推翻了，就改写原来那条，历史交给 git。
• 需求文件只用固定小标题：现在、规则、不能坏、牵连、代码、测试、未定。没有内容的整节删掉。
• 改代码时，顺手改牵连到的需求条目和相关文档。

提交

每完成一小步自己提交。格式固定：

同步：冲突时只重试相关操作

前端重试队列改为按 opId 单独重试，失败的操作不再拖住整页保存。
原因：多设备同时编辑时整页报冲突。

Feature: 同步
Code: web/src/sync.js: retryQueue, mergeChanges
Docs: docs/需求/同步.md
Verified: tests/sync_browser.py 通过；两台设备同时改同一事项，只挂起冲突项

• 第一行：功能名加一句人话总结，不写 feat:、编号、hash。
• 正文：做了什么、为什么，用户能看懂。
• Feature：动了哪几个功能，对应需求文件名。
• Code：精确到“文件: 函数”。
• Docs：改了哪些文档；没改写原因，例如“未改，纯重构，行为不变”。
• Verified：在哪里亲眼看到了结果。

BOARD

• 开工前看 BOARD。别人那一道列着你要改的文件时，先告诉用户，不直接改。
• 只改自己那一道，覆盖写，带更新时间。完成一小步、准备停下时更新。
• 留言只追加；处理完删掉，结果写进该去的文档。等用户决定的留言一直留着。
• 不写已完成的事。结果进需求文件或 STATUS，过程进 git。

分工

• 按 RULES.md 的分工表做事。
• 表里没填时：大量阅读、搜集、批量机械修改交给子 Agent；小事自己做。
• 派活写清：做什么、怎样算做完、不许碰什么。结论抽查后再用。

用户的话对应什么

• “继续”：读 BOARD，接着上面写的下一步。没写清就跑 hw handoff。
• “检查一下文档”：跑 hw check。
• “讨论一下汇报格式 / 分工 / 文档分区”：先出草稿，用户确认后写进 RULES.md。
• “维护一下 / 升级一下”：从 STATUS 的下一步、BOARD 留言、需求文件的“未定”、hw check 的结果里挑事，先说打算做哪几件再开始。

hw 什么时候用

• 开工前：hw status
• 找相关文档：hw find <词>
• 说做完之前：hw check
• 接手别人的活：hw handoff
• 查功能历史：hw log <功能>
• 看文档地图：hw map